> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# pan mcp: serve MCP, manage OAuth sign-ins and run the connector

> Serve Overdeck's MCP tools over stdio, manage OAuth sign-ins, and run the Overdeck connector for a bot

# `pan mcp`

Serve Overdeck's MCP tools to a client over stdio, manage the OAuth sign-ins that reach
`/mcp`, and run the Overdeck connector next to a self-hosted bot. This page lists the
commands; [MCP server](https://panopticon-cli.com/configuration/mcp.md) explains the tools and scopes, and
[Connect a bot](https://panopticon-cli.com/configuration/bots.md) walks through setting up a bot.

## serve

```bash theme={null}
pan mcp serve
```

Serves Overdeck as an MCP server over stdio. It takes no flags. The token comes from the
environment:

| Variable | Effect |
| - | - |
| `OVERDECK_MCP_TOKEN` | The access token. When it is set, it wins. |
| `OVERDECK_MCP_TOKEN_FILE` | Used only when `OVERDECK_MCP_TOKEN` is unset: the path of a file that holds the token. The file must be mode 0600. |

Before it serves, the command checks the token against this machine's token registry. Each
tool then calls the dashboard with that token, so the token's scopes decide what every call
may do. stdout carries JSON-RPC only; every diagnostic goes to stderr. The command exits 0
when stdin closes.

It exits 1 and prints one of these lines when it refuses to start:

| Cause | Message |
| - | - |
| Neither variable is set | `OVERDECK_MCP_TOKEN or OVERDECK_MCP_TOKEN_FILE is not set. Create a token with: pan token create mcp --scopes read:state,read:conversations,operate` |
| The file is readable by group or other users | `OVERDECK_MCP_TOKEN_FILE must be mode 0600 (it is 0644). Fix it with: chmod 600 <path>` |
| The file is empty | `OVERDECK_MCP_TOKEN_FILE is empty: <path>` |
| The file cannot be opened | `OVERDECK_MCP_TOKEN_FILE could not be read: <error>` |
| The token is unknown or revoked | `OVERDECK_MCP_TOKEN is refused: the token is unknown or revoked. Create a token with: pan token create mcp --scopes read:state,read:conversations,operate` |
| The token is not an API token (a paired device, linked machine, phone or connector credential) | `OVERDECK_MCP_TOKEN is refused: a paired device credential cannot drive MCP.` |
| The token carries `admin` | `OVERDECK_MCP_TOKEN is refused: MCP tokens cannot carry admin. Create a token with: pan token create mcp --scopes read:state,read:conversations,operate` |

Create the token with [`pan token create`](https://panopticon-cli.com/cli/token#create). A client configured in the
Claude Desktop style points at a token file, so the token never appears in the config:

```json theme={null}
{
  "mcpServers": {
    "overdeck": {
      "command": "pan",
      "args": ["mcp", "serve"],
      "env": { "OVERDECK_MCP_TOKEN_FILE": "/home/you/.overdeck/mcp-token" }
    }
  }
}
```

## oauth

Manage OAuth sign-ins to `/mcp`. Every subcommand calls the dashboard on this machine, so the
dashboard must be running. When it is not, the command prints
`The dashboard is not running. Start it with pan up.` and exits 1. An error answer other
than 404 prints the dashboard's error text and exits 1. See
[Sign in with OAuth](https://panopticon-cli.com/configuration/mcp.md#sign-in-with-oauth) for the browser flow.

A sign-in has one of four access levels:

| Level | Label | Scopes |
| - | - | - |
| `read` | Read only | `read:state`, `read:conversations` |
| `message` | Can message | `read:state`, `read:conversations`, `tell` |
| `operate` | Can operate | `read:state`, `read:conversations`, `tell`, `operate` |
| `approve` | Can approve | `read:state`, `read:conversations`, `tell`, `operate`, `approve` |

Any other `--level` value prints `The level must be one of read, message, operate, approve.`
and exits 1.

### issue

```bash theme={null}
pan mcp oauth issue --name <name> --level <level>
```

Create a sign-in for a client that cannot open a browser; prints its tokens once.

| Flag | Effect |
| - | - |
| `--name <name>` | Required. Name shown in the sign-in list. |
| `--level <level>` | Required. Access level: read, message, operate or approve. |

It prints the client id, the sign-in id, the level, the access token and the refresh token
(`odr_…`), followed by:

```
These tokens are shown once. Store them in your client now.
```

### list

```bash theme={null}
pan mcp oauth list
```

List active OAuth sign-ins. Each line shows the sign-in id, the level, the client name, when
it was last used (or `never`) and the date its refresh token expires:

```
<sign-in id>  <level>  <client name>  last used <time>  refresh expires <date>
```

With no sign-ins it prints `No MCP sign-ins.`

### revoke

```bash theme={null}
pan mcp oauth revoke <familyId>
```

End one OAuth sign-in. `<familyId>` is the sign-in id from `list`. It prints
`Revoked sign-in <familyId>.`; an unknown id prints `No active sign-in <familyId>.` and exits 1.

### pending

```bash theme={null}
pan mcp oauth pending
```

List sign-ins waiting for your approval. Each line shows the approval code, the client name,
the host it redirects to, the level it asked for and when the request expires:

```
<approval code>  <client name>  → <redirect host>  wants <level>  expires <time>
```

With nothing waiting it prints `No sign-ins are waiting.`

### approve

```bash theme={null}
pan mcp oauth approve <code> --level <level>
```

Approve the waiting sign-in that shows this approval code.

| Flag | Effect |
| - | - |
| `--level <level>` | Required. Access level: read, message, operate or approve. |

The code ignores case and the dash: `KQZT-MWRB`, `kqztmwrb` and `kqzt-mwrb` name the same
approval. It prints `Approved sign-in <code> for <client name> at level <level>.` A code that
matches no waiting sign-in prints `No waiting sign-in has code <CODE>.` and exits 1.

### deny

```bash theme={null}
pan mcp oauth deny <code>
```

Deny the waiting sign-in that shows this approval code. It matches the code the same way as
`approve` and prints `Denied sign-in <code> for <client name>.`

## connector

Run an Overdeck connector for a self-hosted bot. The connector runs on the computer where the
bot runs, pairs with one Overdeck machine, and serves that machine's MCP tools on
`http://127.0.0.1:7466/mcp` (or stdio). See
[Run the Overdeck connector](https://panopticon-cli.com/configuration/bots.md#run-the-overdeck-connector) for the whole
setup.

`connect` is the one-command path for bots: the bot runs it, shows the user one link, and runs
it again until it prints `ready`. `login`, `pair` and `serve` remain the manual path. The
top-level `pan connect` is a different command: it installs this computer's Overdeck server.

It needs Node 22.16 or later. On a computer without Overdeck, run each command as
`npx -y @overdeck/core@<version> mcp connector <command>`; the Connect a bot dialog shows the
exact version.

| Variable | Effect |
| - | - |
| `OVERDECK_CONNECTOR_HOME` | The connector home. Default `~/.overdeck-connector`. |
| `OVERDECK_CONNECTOR_DIRECTORY_URL` | The overdeck.ai directory URL when `login` or `connect` has no `--directory-url`. Default `https://connect.overdeck.ai`. |
| `OVERDECK_ACCOUNT_URL` | The overdeck.ai account service URL when `login` or `connect` has no `--account-url`. Default `https://account.overdeck.ai`. |

The connector home is mode 0700 and holds up to five files, each mode 0600: `account.json`,
`identity.json`, `pairing.json`, `local-token`, and `pending-signin.json`, which exists only
while a sign-in that `connect` started waits for approval. The connector never reads or writes
`~/.overdeck`.

### connect

```bash theme={null}
pan mcp connector connect <pairingString> [--name <bot>] [--platform <id>] [--wait <seconds>] \
  [--account-url <url>] [--directory-url <url>]
```

Sign in, pair, verify the route, and print the MCP registration, in one command a bot can run
again after any result. Each run continues from the stage the last run reached. Put the pairing
string in single quotes.

| Flag | Effect |
| - | - |
| `--name <bot>` | The bot's name. The sign-in page shows it, and so do the directory and the machine. Default: the host name. |
| `--platform <id>` | `grok-bot`, `grok-build`, `hermes`, `openclaw` or `other`. It sets the shape of the registration lines. Default `other`. |
| `--wait <seconds>` | How long a run waits for an approval that an earlier run started. An integer from 0 to 900. Default `120`. |
| `--account-url <url>` | overdeck.ai account service URL. |
| `--directory-url <url>` | overdeck.ai directory URL. |

A `--wait` or `--platform` value outside these ranges prints one line to stderr and exits 1.

The stages, in order:

1. **Read the pairing string.** A string that is not an Overdeck connector pairing string stops
   the run with `bad-pairing-string`.
2. **Sign in.** With no `account.json`, the run requests a device code, saves it in
   `pending-signin.json`, prints the activate link and stops with `authorize` at once. The next
   run waits up to `--wait` seconds for the approval. If the user has not approved yet, it stops
   with `authorize` and the same link. If the code expired, it stops with `authorize` and a new
   link.
3. **Check the existing pairing.** When `pairing.json` names the machine in the pairing string,
   the run verifies it (stage 5) and uses the code only when the machine no longer accepts this
   connector.
4. **Pair** with the one-time code in the pairing string. A code is used at most once per run.
5. **Verify.** Open a link to the machine within 30 seconds and call
   `GET /api/connectors/self`.
6. **Report.** Print `Connected to <machine> over <route> with <scopes>.`, the registration in
   the platform's config shape, and the `ready` line.

**Registration lines by platform.** Before the `ready` line, `connect` prints the registration
in the shape the bot's platform reads:

| `--platform` | What it prints |
| - | - |
| `grok-bot` | The `mcpServers` block for the Grok Bot plugin's `mcp.json`. |
| `grok-build` | A note that the Overdeck plugin's `scripts/run-mcp.sh` starts the connector on its own, then the generic stdio JSON for use without the plugin. |
| `hermes` | The `mcp_servers.overdeck` entry (`command`, `args`) for Hermes's `config.yaml`, then a reminder to run `/reload-mcp` and that the Overdeck Hermes plugin needs `plugins.entries.overdeck.mcp_allowlist: ["overdeck"]` in the same file. |
| `openclaw` | The command `openclaw mcp set overdeck '<json>'`, which OpenClaw applies without a restart, then a note that the Overdeck OpenClaw plugin's summary and its `overdeck_pending` and `overdeck_answer` tools still need the connector's HTTP route (`serve` and its local token). |
| `other` | The generic stdio JSON `{ "command": "npx", "args": [...] }`. |

The last line of stdout is always one status line: `OVERDECK_CONNECT ` and then one line of
JSON with `"v":1`. A bot acts on this line only. The command never prints a token or the
device code. Examples, one for each status:

```text theme={null}
OVERDECK_CONNECT {"v":1,"status":"ready","machine":"studio","environmentId":"0f1e2d3c-4b5a-4978-8695-a4b3c2d1e0f9","route":"relay","scopes":["read:state","tell"],"registration":{"name":"overdeck","transport":"stdio","command":"npx","args":["-y","@overdeck/core@0.75.0","mcp","connector","serve","--stdio"]},"next":"Register the MCP server shown above, then call list_conversations once and tell the user the result."}
OVERDECK_CONNECT {"v":1,"status":"authorize","url":"https://account.overdeck.ai/activate?user_code=ABCDEFGH","expiresAt":"2026-11-05T12:15:00.000Z","next":"Show the user this link and ask them to open it and click Authorize. When they say they did, run the same command again."}
OVERDECK_CONNECT {"v":1,"status":"retry","code":"machine-offline","detail":"studio is offline in the overdeck.ai directory.","next":"The machine is offline. Ask the user to start Overdeck there, then run the same command again."}
OVERDECK_CONNECT {"v":1,"status":"error","code":"pairing-code-refused","detail":"The machine refused the pairing code (it may have expired); ask for a new one in Connect a bot.","next":"The pairing code expired, was cancelled or was already used. Ask the user to click Copy again in Overdeck (Settings → Anywhere → Bots) and paste the new message."}
```

`registration` carries `"env":{"OVERDECK_CONNECTOR_HOME":"<path>"}` only when that variable
is set.

| Status | Exit code | Meaning |
| - | - | - |
| `ready` | 0 | Paired and verified. Register the server in `registration`. |
| `error` | 1 | The run cannot finish without the user. Follow `next`. |
| `authorize` | 3 | The user must open `url` and click Authorize. Then run the command again. |
| `retry` | 4 | A temporary failure. Run the command again later. |

Every `retry` and `error` line carries a `code`, an optional `detail`, and a `next` sentence
for the bot. "Copy again" below means: ask the user to click Copy again in Overdeck
(Settings → Anywhere → Bots) and paste the new message. "Log out and rerun" means: run the
same npx command with `mcp connector logout` in place of `mcp connector connect …`, then run
the same command again.

| `code` | Status | Next step |
| - | - | - |
| `bad-pairing-string` | error | Copy again. |
| `unsupported-platform` | error | This computer's OS or CPU cannot run the connector; tell the user. |
| `home-unreadable` | error | Show the user `detail`; the connector home has a bad file. |
| `signin-denied` | error | The sign-in was cancelled or this GitHub account is not invited. Tell the user, then run the same command again for a new link. |
| `network` | retry | overdeck.ai could not be reached. Run the same command again in a minute. |
| `directory-refused` | error | Show the user `detail`. If it says the sign-in is not valid, log out and rerun. |
| `machine-not-in-account` | error | You signed in with an account that does not own this machine. Log out and rerun, and ask the user to authorize with the account their Overdeck uses. |
| `machine-offline` | retry | The machine is offline. Ask the user to start Overdeck there, then run the same command again. |
| `relay-plan-needed` | error | This network blocks direct connections and the account has no relay plan. Tell the user. |
| `no-webrtc-egress` | error | This computer got no TURN relay connection, usually because it cannot reach TLS on turn.cloudflare.com:443 or send UDP; running again will not help then. Tell the user to run `pan doctor` on their machine: if its TURN relay row is ok, use Public MCP or a host with WebRTC egress; if that row warns too, the relay is down, so run the command again once it passes. See [no-webrtc-egress](https://panopticon-cli.com/configuration/bots.md#no-webrtc-egress). |
| `machine-unreachable` | retry | The machine could not be reached. Run the same command again in a minute. |
| `pairing-code-refused` | error | The pairing code expired, was cancelled or was already used. Copy again. |
| `key-mismatch` | error | The machine's key does not match the message. Copy again. |
| `pairing-failed` | error | Copy again, and show the user `detail`. |
| `verify-failed` | retry | Paired, but the test call failed. Run the same command again. |

### login

```bash theme={null}
pan mcp connector login [--account-url <url>] [--directory-url <url>]
```

Sign this connector in to overdeck.ai with the device flow: open the URL it prints and enter
the code.

| Flag | Effect |
| - | - |
| `--account-url <url>` | overdeck.ai account service URL. |
| `--directory-url <url>` | overdeck.ai directory URL. |

### pair

```bash theme={null}
pan mcp connector pair <pairingString> [--label <name>]
```

Pair with one Overdeck machine using the string from Connect a bot.

| Flag | Effect |
| - | - |
| `--label <name>` | Name this connector shows on the machine. Default: the host name. |

### serve

```bash theme={null}
pan mcp connector serve [--port <port>] [--stdio] [--label <name>]
```

Serve the Overdeck MCP tools on 127.0.0.1 (or stdio) for the paired machine. It runs until
stopped.

| Flag | Effect |
| - | - |
| `--port <port>` | Loopback port for `http://127.0.0.1:<port>/mcp`. Default `7466`. |
| `--stdio` | Serve one MCP session on stdin and stdout instead. All diagnostics then go to stderr. |
| `--label <name>` | Name this connector shows in the overdeck.ai directory. Default: the host name. |

A `--port` that is not an integer from 1 to 65535 prints
`--port must be an integer from 1 to 65535` and exits 1.

### status

```bash theme={null}
pan mcp connector status [--port <port>]
```

Show the signed-in account, the paired machine, its scopes and the live route. It never
prints a token.

| Flag | Effect |
| - | - |
| `--port <port>` | Port of the running `serve`. Default `7466`. |

### logout

```bash theme={null}
pan mcp connector logout
```

Remove this connector from its machine and overdeck.ai, then delete its files, including a
waiting `pending-signin.json`.

## Get help

Still stuck? Ask on the [Overdeck Discord](https://discord.gg/ZpHE2ZTv5P) or file a
[GitHub Issue](https://github.com/eltmon/overdeck/issues).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.