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 explains the tools and scopes, and
Connect a bot walks through setting up a bot.
serve
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:
Create the token with
pan token create. A client configured in the
Claude Desktop style points at a token file, so the token never appears in the config:
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 for the browser flow.
A sign-in has one of four access levels:
Any other
--level value prints The level must be one of read, message, operate, approve.
and exits 1.
issue
It prints the client id, the sign-in id, the level, the access token and the refresh token
(
odr_…), followed by:
list
never) and the date its refresh token expires:
No MCP sign-ins.
revoke
<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
No sign-ins are waiting.
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
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 onhttp://127.0.0.1:7466/mcp (or stdio). See
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.
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
A
--wait or --platform value outside these ranges prints one line to stderr and exits 1.
The stages, in order:
- Read the pairing string. A string that is not an Overdeck connector pairing string stops
the run with
bad-pairing-string. - Sign in. With no
account.json, the run requests a device code, saves it inpending-signin.json, prints the activate link and stops withauthorizeat once. The next run waits up to--waitseconds for the approval. If the user has not approved yet, it stops withauthorizeand the same link. If the code expired, it stops withauthorizeand a new link. - Check the existing pairing. When
pairing.jsonnames 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. - Pair with the one-time code in the pairing string. A code is used at most once per run.
- Verify. Open a link to the machine within 30 seconds and call
GET /api/connectors/self. - Report. Print
Connected to <machine> over <route> with <scopes>., the registration in the platform’s config shape, and thereadyline.
ready line, connect prints the registration
in the shape the bot’s platform reads:
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:
registration carries "env":{"OVERDECK_CONNECTOR_HOME":"<path>"} only when that variable
is set.
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.
login
pair
serve
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
logout
pending-signin.json.