Scannable docs

How MCP Desk connects

Short reference: zero-config quick start, architecture, machine codes, device identity, hub, invite/connect, the live Mode B gateway, and the agent. Product language first — not a protocol dump.

Quick start (zero-config)

The latest Windows and Linux downloads need no flags for normal use. Double-click (or run), go Online, share your code, Approve — and the client gets a short-lived desk_ticket for the gateway URL.

  1. Get the latest build from Download and put it in any folder (for example Downloads).
  2. Windows: double-click servermcp-windows-x86_64.exe. Linux: make it executable and run it — no arguments.
  3. The desk comes Online and the console shows your 9-digit desk code (xxx xxx xxx) and a rotating OTP (changes about every minute). Share the code + current OTP to invite someone.
  4. Approve or Deny on the desk. After Approve, the client receives a short-lived desk_ticket (mdt_…) for the Mode B gateway — that is what belongs in Claude, Cursor, or similar. See Public MCP gateway. 
chmod +x servermcp-linux-x86_64
./servermcp-linux-x86_64

Built in — nothing to configure

  • Hub: https://hub.mcpdesk.io
  • Tunnel: wss://mcp.mcpdesk.io/tunnel — the desk dials out, so no inbound port or public address is needed. After Approve, clients reach the desk through the live Mode B gateway.

What first run creates

  • Device identity — desk code and ownership key live in your per-user data folder (not next to the binary), so the code stays the same across moves and restarts. See Device identity.

Restarting keeps the same desk code. Unattended access stays off unless you add a key file — see Access & security.

Architecture overview

Three pieces, same mental model as remote desktop products:

  1. Agent — small program on the machine that exposes that host’s MCP tools and stays registered with the hub.
  2. Hub — hub.mcpdesk.io — the registry and meeting point. Agents register; clients ask to connect by machine code; Approve still happens here.
  3. Client — an AI app (Claude, Codex, Cursor, and similar) or an operator that requests a code and, after Approve, uses the remote MCP tools.

You never hand the client a raw machine address. Share a code; approve on the device; the hub brokers the session.

Live: the optional Mode B gateway at mcp.mcpdesk.io is the public MCP data plane. The hub stays the registry — see Public MCP gateway.

Machine codes

Each agent shows a stable 9-digit code (xxx xxx xxx). The code stays the same for that machine so you can bookmark and share it like an AnyDesk address.

New desks get a random code assigned by the hub the first time they register. It is not derived from the network card, serial number, or any other hardware value — so it can’t be guessed from the machine, and it doesn’t change if the hardware does. Desks that already have a code keep it.

  • Share the code when you want a client or teammate to request access.
  • A short-lived OTP appears when someone requests a connection — the code alone is not enough for a new session.
  • The agent console prints your desk code and the current OTP on start — that’s where to read them.
  • There is no public “look up a code by hardware address” service. The only way to learn a desk’s code is from the desk itself (or from someone who shares it with you).

Device identity

Each desk proves it is the same desk with its own key — no account required. On first start the agent creates an Ed25519 device keypair on that machine.

  • Private key stays on the desk. The file is device.key (Ed25519 PKCS#8). It is never logged or sent to the hub, the gateway, or any client. Only the public key is shared when the desk registers (optional companion device.pub).
  • Ownership, not hardware. The hub ties the machine code and the agent’s credentials to that public key. Re-registering with a hardware address alone does not hand out a new agent token — the desk has to prove it holds the key.
  • Recovery fingerprint (private). The agent also keeps a local, hashed fingerprint of the machine (OS machine ID and similar signals) to support recovery in a later release. Raw values never leave the machine, and the fingerprint is not the 9-digit code or a way to look one up.

Portable vs Installed

  • Portable — user-scope, foreground / default. Identity lives in your per-user data folder.
  • Installed — service / machine-scope (Installed / service mode via --installed or MCPDESK_INSTALLED). Identity lives in the machine-wide data folder.
  • Identity can migrate between Portable and Installed without a new ID — same key, same desk code.

Where identity is stored

Identity is not stored next to the executable — so you can run the agent from Downloads, a USB stick, or a read-only folder and keep the same code.

Portable (default, user-scope):

  • Windows: %LOCALAPPDATA%\MCPDesk\
  • Linux: your XDG data folder — typically ~/.local/share/mcpdesk/
  • macOS: ~/Library/Application Support/MCPDesk/

Installed (machine-scope / service mode):

  • Windows: %PROGRAMDATA%\MCPDesk\
  • Linux: /var/lib/mcpdesk
  • Custom location: --data-dir or the MCPDESK_DATA_DIR environment variable.

Upgrading from an older build? On first start the agent copies its existing settings from the executable’s folder into the data folder, keeping your code. Back up the data folder to keep a desk’s identity; deleting it makes the agent register as a new desk.

Hub

The hub is the registry and rendezvous: agents stay listed, clients request a machine by code, and Approve/Deny is coordinated here. Peers find each other by code — not by IP. The hub is not the Mode B MCP data plane (that’s the live gateway below).

  • Public hub (HTTPS, live): https://hub.mcpdesk.io
  • Agent setup: built in. Latest builds use https://hub.mcpdesk.io by default — no flag needed (--hub-url remains available as an override).
Live

Public MCP gateway (Mode B)

The central mcpdesk-gateway at https://mcp.mcpdesk.io is live — an optional public data plane so AI clients can reach a desk’s MCP tools without a public agent URL. Hub stays registry; gateway is the data path.

  • Client address: set this once to https://mcp.mcpdesk.io/{userId-guid} with header Authorization: Bearer and the reusable bearer from the dashboard (mdu_…). Leave both in the client.
  • Connect a desk: one message connect device <9 digits> code <one-time>, or send the 9-digit code first and the one-time code when the client asks. A wrong pair does not connect.
  • Older desk ticket: a client that already uses https://mcp.mcpdesk.io/m/<9digits>/mcp can keep that address with a short-lived desk_ticket (mdt_…). You do not need one of those to use the address above.
  • Desk side: works for desks with the gateway tunnel enabled — the agent dials wss://mcp.mcpdesk.io/tunnel outbound (--gateway-tunnel). Current Linux builds include it; zero-config Windows desks may have the tunnel dial built in.

Client path

  1. Sign up or log in and open the dashboard.
  2. Copy the client address https://mcp.mcpdesk.io/{userId-guid} and the bearer. Put them in the AI client once, with header Authorization: Bearer. Leave them there.
  3. On the desk, read the 9-digit code and the one-time code.
  4. In the client, send one message: connect device <9 digits> code <one-time>. Or send the 9-digit code, then the one-time code when asked.
  5. The same address keeps working. A wrong pair does not connect.

The blocks below are shape only (mdu_…). The live address is on the dashboard. The hub is the registry. https://mcp.mcpdesk.io is the HTTP MCP path.

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcpdesk-123456789": {
      "url": "https://mcp.mcpdesk.io/{userId-guid}",
      "headers": { "Authorization": "Bearer mdu_…" }
    }
  }
}

Claude Code

claude mcp add --transport http 'mcpdesk-123456789' 'https://mcp.mcpdesk.io/{userId-guid}' --header 'Authorization: Bearer mdu_…'

Codex CLI — ~/.codex/config.toml

[mcp_servers.mcpdesk-123456789]
url = "https://mcp.mcpdesk.io/{userId-guid}"
http_headers = { "Authorization" = "Bearer mdu_…" }

VS Code — user mcp.json

Open it with MCP: Open User Configuration. Project .vscode/mcp.json is a repo file — do not commit a ticket there.

{
  "servers": {
    "mcpdesk-123456789": {
      "type": "http",
      "url": "https://mcp.mcpdesk.io/{userId-guid}",
      "headers": { "Authorization": "Bearer mdu_…" }
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcpdesk-123456789": {
      "serverUrl": "https://mcp.mcpdesk.io/{userId-guid}",
      "headers": { "Authorization": "Bearer mdu_…" }
    }
  }
}

Gemini CLI — ~/.gemini/settings.json

{
  "mcpServers": {
    "mcpdesk-123456789": {
      "httpUrl": "https://mcp.mcpdesk.io/{userId-guid}",
      "headers": { "Authorization": "Bearer mdu_…" }
    }
  }
}

Cline — cline_mcp_settings.json

{
  "mcpServers": {
    "mcpdesk-123456789": {
      "type": "streamableHttp",
      "url": "https://mcp.mcpdesk.io/{userId-guid}",
      "headers": { "Authorization": "Bearer mdu_…" }
    }
  }
}

Zed — settings.json context_servers

{
  "context_servers": {
    "mcpdesk-123456789": {
      "url": "https://mcp.mcpdesk.io/{userId-guid}",
      "headers": { "Authorization": "Bearer mdu_…" }
    }
  }
}

Kiro — ~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "mcpdesk-123456789": {
      "url": "https://mcp.mcpdesk.io/{userId-guid}",
      "headers": { "Authorization": "Bearer mdu_…" }
    }
  }
}

Test with curl

curl -i -H 'Authorization: Bearer mdu_…' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' https://mcp.mcpdesk.io/{userId-guid}

No paste box

  • Roo Code has no paste box. The only verified path is project .roo/mcp.json.
  • No paste box: putting the desk ticket in Claude Desktop’s config as env AUTH_HEADER for npx mcp-remote, even with --transport http-only, leaves a 15-minute bearer in a file the app reloads and passes it to an unpinned npx child.
  • Continue, OpenCode, ChatGPT, Goose, Amazon Q, JetBrains AI Assistant, and Devin Desktop have no verified one-paste config. Do not invent a file for those clients.

Shape only. The live address and bearer are on the dashboard. Add the server key. Do not replace the whole file. Leave this address in the client.

Never put token.txt, the install bearer, or the agent’s agent_token into Claude, Cursor, or any other client for the gateway URL. Use the reusable bearer from the dashboard (mdu_…).

Latest desks dial out to wss://mcp.mcpdesk.io/tunnel by default (zero-config). Later (hybrid): clients will go direct when a desk is already public, and use the gateway otherwise.

Invite / connect

  1. Start the agent on the target machine (no flags needed) → note the 9-digit code and current OTP
  2. Client or operator asks the hub to connect to that code (+ OTP when prompted)
  3. Machine owner sees who / from where → Approve or Deny
  4. After Approve, the client gets a short-lived desk ticket and reaches that machine’s MCP tools through the gateway

Optional always-on service (Windows service / systemd) keeps the agent up after reboot. Each new peer still needs Approve/Deny unless you opt into unattended access (see below).

Access & security

Every invite defaults to human approval on the Client. Unattended access is optional and file-gated — like SSH authorized_keys, not a hub account token.

  • Default: stable 9-digit code + rotating OTP. Every invite needs Approve/Deny on the Client. There is no silent accept.
  • Unattended (optional): only if authorized_keys — or its alias public.key — exists in the agent’s data folder (older installs: next to the binary). ed25519 public keys in OpenSSH format (ssh-ed25519 …), one per line. Neither file present → OTP + Approve only.
  • Challenge / verify: the Client uses that file for key challenge. No file, or no matching key → fall back to OTP + Approve.
  • Hub account token alone does not grant unattended access — credential ≠ authorized_keys.

On the agent

Start the agent — no flags needed. It registers with the public hub on launch, prints your desk code and OTP, and stays online so clients can request your machine by code. Local MCP tools on that host remain available to approved sessions. 

# Windows: double-click servermcp-windows-x86_64.exe
# Linux:
./servermcp-linux-x86_64

Identity is kept in the per-user data folder (see Device identity). To keep it somewhere else — a portable drive, a service account — pass a data folder: 

servermcp --data-dir /path/to/mcpdesk-data

The public HTTPS hub (https://hub.mcpdesk.io) is built in — no flag needed. Advanced: --hub-url overrides it.

Accounts (optional)

No account is needed to go online: a desk registers, gets its code, and proves ownership with its device key. Hub signup/login is optional — useful for admin and tracking which desks are yours. The machine code is still what you share for remote access. Web signup / login are live against the hub at https://hub.mcpdesk.io. Your website password is separate from desk credentials — never use one for the other.