Skip to main content

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

Serves Overdeck as an MCP server over stdio. It takes no flags. The token comes from the environment: 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

Create a sign-in for a client that cannot open a browser; prints its tokens once. It prints the client id, the sign-in id, the level, the access token and the refresh token (odr_…), followed by:

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:
With no sign-ins it prints No MCP sign-ins.

revoke

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

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:
With nothing waiting it prints No sign-ins are waiting.

approve

Approve the waiting sign-in that shows this approval code. 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

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 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

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. 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: 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

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

pair

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

serve

Serve the Overdeck MCP tools on 127.0.0.1 (or stdio) for the paired machine. It runs until stopped. 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

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

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 or file a GitHub Issue.