# Connecting an AI to PenPick

PenPick serves the writer's canvas over MCP. Connect once; from then on the AI reads and writes the canvas while the writer talks to it.

- Server: https://penpick.app/mcp (Streamable HTTP, stateless: every canvas tool takes the work's id as `work`, found with list_works)
- Signing in: OAuth 2.1. The client opens PenPick's page, the writer signs in and presses Allow. A client that cannot open a page uses a personal key instead, sent as `Authorization: Bearer <key>`.
- Plans: every plan can connect an AI, the free plan too (within its number of works).

## Setup by client

### Claude (claude.ai, Claude Desktop)

Add a custom connector in Claude's connector settings with the address https://penpick.app/mcp, sign in to PenPick and press Allow. Turn PenPick on in a conversation's tools.

### ChatGPT

Add a connector in ChatGPT's connector settings with the address https://penpick.app/mcp, then sign in to PenPick and press Allow.

### Claude Code

```
claude mcp add --transport http penpick https://penpick.app/mcp
```

The browser opens PenPick's page to allow it on first use.

### Cursor, and clients that cannot open a sign-in page

Make a personal key in PenPick under Settings › Connections (it is shown once), then:

```json
{
  "mcpServers": {
    "penpick": {
      "url": "https://penpick.app/mcp",
      "headers": {
        "Authorization": "Bearer ppk_..."
      }
    }
  }
}
```

VS Code names the list `servers` instead of `mcpServers`.

## Limits

- 1,500 requests an hour for each writer. Past it, requests are refused until the next hour.
- 4 requests at once for each writer. More are refused with Retry-After.

## Tools

| Tool | What it does |
| --- | --- |
| `list_works` | Lists the writer's works, most recently touched first: id, title, last written (updated), counts of chapters, characters and events, and sample when it was taken from a sample work. |
| `get_guide` | Reads how to work on the PenPick canvas. |
| `get_index` | Reads the work's index as it is now: the about, the chapters in order with their questions, every card's key, title and tags (for an event, the chapter it is placed in), and the number of gaps, including what the writer changed on the canvas. |
| `read_cards` | Reads the cards named by keys in full. |
| `read_chapter` | Reads one chapter as the screen shows it: its question and viewpoint, its flow (each event with its body, the memos in it and its related events), and how the memos in this chapter are in it, with their relationships. |
| `write_cards` | Makes or changes several cards (memos and events) at once. |
| `remove_cards` | Removes the cards named by keys. |
| `write_chapter` | Makes a chapter (without key) or changes one (with key, only the fields given). |
| `arrange` | Places events in chapter flows, moves them and takes them out. |
| `remove_chapter` | Removes a chapter. |
| `set_states` | Writes how a memo is in a chapter (its chapter state). |
| `link` | Links two cards. |
| `unlink` | Removes the link between two cards (related events, an appearance, a relationship). |
| `edit_work` | Writes what the work is, in one place: its title and the about in the writer's words. |

Every write may replace what was there and is marked destructive; only reads are read-only. The writer cannot undo what an AI removes, so it removes cards and chapters only when asked.

## Prompts

- `build_blueprint` (Build a blueprint from a text): Builds chapters, memos, events and links on the canvas from a text you give (a draft, a synopsis, a character sheet).
- `check_gaps` (Check the gaps): Finds where the blueprint is empty (clues shown once, events linked to nothing, memos in no event) and says whether each looks like a mistake. Changes nothing.
- `tidy_chapter` (Tidy a chapter): Reads one chapter against the writing guide and proposes changes; makes only the ones you agree to.

## When it does not work

- The AI answers without PenPick: ask it to use the PenPick canvas, and check that PenPick is on in the conversation.
- It works on another work: name the work's title; with several works, the AI should ask which one.
- No sign-in page opens: the client cannot open one; use a personal key.
- "This hour's canvas calls are used up": wait for the next hour.
- To disconnect: PenPick Settings › Connections, then disconnect the app or key.