# Connect an agent

> Add the planpage MCP server to Claude Code, Claude Desktop, Claude on the web, Codex, Cursor or another client, choose what it can reach, and check that it works.

planpage is a remote MCP server at `https://app.planpa.ge/mcp`. You add it to your agent once, sign in to planpage in your browser, and choose which workspaces the agent can reach and what it can do in each. The same steps are in the app under **Your account → Agent connections → Connect an agent**.

## Set up your client

### Claude Desktop and Claude on the web

These are the Claude chat apps: the desktop app and claude.ai in a browser. They share one list of connectors, so add planpage in either and it appears in both. For the Claude Code command-line tool, see the next section.

1. Open **Settings → Connectors → Add custom connector**.
2. Name it `planpage` and paste the server URL: `https://app.planpage.dev/mcp`
3. Click **Connect**. A planpage window opens: sign in, choose the workspaces and what the agent can do in each, then allow access.
4. Turn planpage on for a chat from the tools menu under the message box.

### Claude Code

1. Add the server for every project:

   ```sh
   claude mcp add --transport http --scope user planpage https://app.planpage.dev/mcp
   ```

2. Start Claude Code, run `/mcp`, pick **planpage** and choose **Authenticate**. Your browser opens planpage to choose workspaces and access, then approve. A session that was already running needs a restart to see the tools.
3. Install the planpage skill so Claude knows when and how to plan here:

   ```sh
   mkdir -p ~/.claude/skills/planpage && curl -fsSL https://app.planpage.dev/skill/SKILL.md -o ~/.claude/skills/planpage/SKILL.md
   ```

### Codex

The Codex CLI, IDE extension and app share one configuration, so one setup covers all three.

1. Run the setup script. It adds planpage to `~/.codex/config.toml`, installs the planpage skill in `~/.agents/skills/planpage` and opens planpage in your browser to sign in.

   macOS and Linux:

   ```sh
   curl -fsSL https://app.planpage.dev/setup/codex | sh
   ```

   Windows (PowerShell):

   ```powershell
   irm https://app.planpage.dev/setup/codex.ps1 | iex
   ```

2. Restart Codex and ask it to run planpage's `whoami`.

To set it up by hand instead, add this to `~/.codex/config.toml` and run `codex mcp login planpage`:

```toml
[mcp_servers.planpage]
url = "https://app.planpage.dev/mcp"
tool_timeout_sec = 330
```

`tool_timeout_sec` lets `wait_for_review` wait up to five minutes. Without it, Codex stops tool calls after 60 seconds.

**Without a browser** (over SSH, on a dev box, or in Codex cloud, which is best-effort): create an API token in **Your account → Agent connections**, set it as `PLANPAGE_TOKEN` where Codex runs, and run the script with `sh -s -- --token` (on Windows, `& ([scriptblock]::Create((irm https://app.planpage.dev/setup/codex.ps1))) -Token`). That adds `bearer_token_env_var = "PLANPAGE_TOKEN"`, so Codex sends the token instead of signing in.

### Cursor

Add planpage to your MCP configuration:

```json
{ "mcpServers": { "planpage": { "url": "https://app.planpage.dev/mcp" } } }
```

Cursor opens planpage in your browser to sign in the first time it connects.

### ChatGPT and other MCP clients

Add a remote MCP server (Streamable HTTP) with the URL `https://app.planpage.dev/mcp` and OAuth sign-in. Clients that can't sign in with OAuth can use an API token instead: create one in **Your account → Agent connections** and send it as `Authorization: Bearer pp_…`.

## Choose workspaces and access

When you sign in, planpage shows a page headed "*Agent* wants to connect to planpage". On it you choose:

- **Connection name.** How the connection appears in your agent connections and to workspace admins. It defaults to the name the client gives itself. Rename it to something you will recognise later, such as "Claude Code on my laptop".
- **Workspaces it can reach.** Tick each workspace the agent may use. Your personal workspace and every organization you belong to are listed. Unticked workspaces are invisible to the agent.
- **What it can do in each.** Pick an access level per workspace.

| Access level | What the agent can do |
| --- | --- |
| **Read only** | Read documents. Can't publish or change anything. |
| **Publish only** | Post documents and answer comments. Never told to start work. |
| **Publish and run** | Post documents and carry out approved plans. |

The sentence under the list spells out what the agent will be able to do before you click **Allow access**. Approving plans always stays with people, whatever level you choose.

Most clients start every workspace at **Publish and run**. A client that asks only for read access starts at **Read only**. You can change any of this later; see [Agents and access](https://planpage.dev/docs/agents-and-access.md).

If the app sends access to a program on your own computer, the page warns you. Continue only if you started connecting from that program a moment ago.

## Check that it works

Ask your agent to run planpage's `whoami` tool. It returns the connection's name and every workspace it can reach, with your role and the connection's access level in each. If a workspace you expected is missing, edit the connection in **Your account → Agent connections**.

If the agent can't see any planpage tools, the session probably started before you connected. Restart it.

## The first time in a folder

planpage files plans by project, and agents find the project from the repository's git remote. The first time an agent uses planpage in a folder, it can't know where the plans belong, so it asks you. It lists your projects with their workspaces and offers to create a new one, suggesting a name from the repository.

After you answer, the agent records the repository on the project. Next time it finds the project on its own and doesn't ask again. A folder without a git remote can't be remembered this way, so the agent asks once per session. [Projects and folders](https://planpage.dev/docs/projects-and-folders.md) has the details.

## Connection limits

planpage is free during early access, with no limit on agent connections. API tokens count as connections; revoke any you no longer use.