# Set up Char for an agent

Char's MCP server is hosted, so nothing runs on the user's computer. Add the server, have the user sign in to Char, check the connection, then install the Char skill.

## 1. Add the MCP server

- **URL:** `https://api.char.com/v2/mcp`
- **Transport:** Streamable HTTP
- **Sign-in:** OAuth with PKCE. An unauthenticated request gets HTTP 401 with a `WWW-Authenticate` header naming `https://api.char.com/v2/.well-known/oauth-protected-resource/mcp`. That document names the authorization server, `https://auth.char.com`, which supports dynamic client registration. Clients with MCP OAuth support handle this themselves: the user signs in to Char in a browser and approves access.

In Char Next, **Settings → Apps** has Claude Code, Cursor, ChatGPT (Codex) and OpenCode. Choosing one writes the configuration below for the user.

| Client                        | Add the server                                                                                                                           | Sign in                                                   |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Claude Code                   | `claude mcp add --transport http --scope user char https://api.char.com/v2/mcp`                                                          | Run `/mcp` in Claude Code, pick `char`, then authenticate |
| Codex                         | `codex mcp add char --url https://api.char.com/v2/mcp`                                                                                   | `codex mcp login char`                                    |
| Cursor                        | Add `"char": { "type": "http", "url": "https://api.char.com/v2/mcp" }` to `mcpServers` in `~/.cursor/mcp.json`                           | Sign in from the `char` entry in Cursor's MCP settings    |
| OpenCode                      | Add `"char": { "type": "remote", "url": "https://api.char.com/v2/mcp", "enabled": true }` to `mcp` in `~/.config/opencode/opencode.json` | `opencode mcp auth char`                                  |
| Claude (web and desktop apps) | Settings → Connectors → Add custom connector, with the URL above                                                                         | Connect, then sign in to Char                             |
| ChatGPT                       | Add a custom MCP connector (developer mode) with the URL above and OAuth                                                                 | Connect, then sign in to Char                             |

Any other client that speaks Streamable HTTP with MCP OAuth:

```json
{
  "mcpServers": {
    "char": { "type": "http", "url": "https://api.char.com/v2/mcp" }
  }
}
```

## 2. Choose access

| Scope          | Allows                                                                                                    |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| `char:read`    | Required. Read Pages, meetings and transcripts, todos, contacts, chats, Schedules, Skills and History     |
| `char:write`   | Create and edit Pages, todos, contacts and projects, suggest work, and add to History                     |
| `char:delete`  | Delete Pages, contacts and todos, and merge contacts                                                      |
| `char:charlie` | Change what Charlie does on its own (Skills, Schedules), and run Schedules, which uses the user's credits |

Clients ask for read access when they first connect. When a call needs more, it gets HTTP 403 with `error="insufficient_scope"` and a `scope` naming what is missing. A client that supports step-up then asks the user to approve it; with any other client, remove the connection and add it again.

## 3. Check the connection

Call `agenda_get {}`. A working connection answers with the user's local date and time and their next events. Then `tools_read {"name": "pages_list", "arguments": {}}` lists the most recently edited Pages.

Check the tool list too: the tools your client loaded from Char, which is the server's `tools/list`. Char lists 20 tools by default, among them `tools_search`, `tools_read`, `tools_write` and `tools_delete`, which find and run the rest. The skill's recipes use `agenda_get`, `pages_search`, `pages_read`, `pages_create`, `pages_edit`, `todos_list`, `todos_add`, `pages_set_todo_status`, `todos_suggest`, `meetings_list`, `meetings_get`, `meetings_get_transcript`, `contacts_search`, `contacts_get`, `history_read_day` and `tools_read`. If one is missing, the server you reached doesn't offer it: tell the user which tool is missing instead of calling it.

If a call fails:

- **401 "Sign in to Char."**: the sign-in expired or never finished. Sign in again from the client.
- **403 `insufficient_scope`**: approve, or reconnect with, the scope the error names.
- **409 `not_moved`**: this Char account isn't on Char Next yet. Tell the user; another address or a retry won't help.
- **"Char is temporarily unavailable."**: retry later.

## 4. Install the skill

The Char skill teaches an agent what Pages, Home, daily pages, todos and History are, and which tool calls do what. Its files are public:

- `https://char.com/skills/char/SKILL.md`
- `https://char.com/skills/char/references/setup.md`
- `https://char.com/skills/char/references/mcp.md`
- `https://char.com/skills/char/references/cli.md`

Save them as a folder named `char`, with the references in a `references` subfolder, in the agent's skill directory:

| Client           | Skill directory                                                   |
| ---------------- | ----------------------------------------------------------------- |
| Claude Code      | `~/.claude/skills/char/` (or `.claude/skills/char/` in a project) |
| Codex            | `~/.codex/skills/char/`                                           |
| Cursor           | `~/.cursor/skills/char/`                                          |
| OpenCode         | `~/.config/opencode/skills/char/`                                 |
| Claude apps      | Zip the `char` folder and upload it as a custom skill             |
| No skill support | Add `SKILL.md` to the agent's instructions                        |

For example, for Claude Code:

```sh
mkdir -p ~/.claude/skills/char/references
curl -fsSL -o ~/.claude/skills/char/SKILL.md https://char.com/skills/char/SKILL.md
for file in setup mcp cli; do
  curl -fsSL -o ~/.claude/skills/char/references/$file.md https://char.com/skills/char/references/$file.md
done
```

Char Next shows the same files under **Settings → Skills → Use Char in other agents**.

## On the user's Mac

With Char Next signed in on a Mac, the `char-next` CLI reads and edits the same Pages and can read History. The user installs it from **Settings → Apps → Char CLI**. See the [CLI reference](cli.md).

Never ask the user to paste session cookies, OAuth tokens or passwords into a chat.
