On this page

• Three boxes a call crosses
• The umbrellas
• Three gates every command passes
• Workflows
• Tunables the operator owns
• The other direction: Commander as a consumer
• Reserved, not built

Commander MCP services - umbrellas, commands, scopes and workflows

The commander-mcp gateway is the half of Commander's MCP story that faces inbound: a chat client - Claude on the web or desktop, ChatGPT, MCP Inspector, any client that speaks Streamable HTTP - signs in once and operates Commander through a small set of umbrella tools. The other half, Commander handing MCP connections to the agents it launches, is described under the application page.

At this version the gateway serves 15 umbrella tools with 70 commands - 51 of them read-only, 4 destructive - plus two resources and one prompt per persona. It is published at <commander origin>/mcp (for example https://commander-dev.myorg.ai/mcp), with OAuth discovery served for that path. Commander proxies the path to the gateway process (commander-mcp-dev on dev, commander-mcp on prod), so a client needs one hostname and nothing else.

Three boxes a call crosses

1. The MCP client holds an access token minted by the gateway's own OAuth server after the operator signed in on the consent page and ticked scopes.
2. The gateway verifies the token locally, resolves the caller's role, checks scope → phase → role, validates the command's parameters, and relays over the loopback to Commander with a service token - acting as the signed-in subject, which Commander logs as acting=<subject>.
3. Commander answers the same REST API the browser uses. The gateway redacts the result (tokens, keys, PEM blocks, ANSI, invisible characters), frames anything agent-written as untrusted content, caps its size, and writes one audit row per call - denials included.

The umbrellas

Every tool is an umbrella: one MCP tool name, a command enum, and per-command parameters spelled out in the tool description. Call _hello first - it returns identity, role, effective phases and scopes, and a plan for the intent you state. Commands marked write need a phase above 0; destructive commands need confirm: true and are refused on prod.

Resources: commander://project/{slug}/sessions (a project's sessions; slug, short id or uuid) and commander://session/{id}/brief (Commander's own redacted conversation log). Prompts: every persona is offered as persona:<id>; the body is redacted, size-capped and scope-checked before it leaves.

Not on the list, on purpose: promote, rollback, pm2 restart, the Password Vault, Integrations, service accounts, license activation, the login seam and file uploads. Those remain the operator's hand in the browser.

Three gates every command passes

• Scope - what the human granted on the consent page.
• Phase - what the operator enabled on the instance (mcp_gateway_enable_phases: 0 read-only, 1 workboard/persona/settings writes, 2 session control). Dev runs 0,1,2; prod stays at 0 by policy.
• Role - what the operator assigned to the connector (or, in Auth mode, the signed-in subject). Effective power is role ∩ instance phases ∩ token scopes. Absent a grant, the default role applies (mcp_gateway_default_role, normally visitor). Grants take effect on the next call, no reconnect needed.

Workflows

Connecting Claude (web or desktop)

1. Add the connector - Settings → Connectors → Add custom connector → <commander origin>/mcp.
2. Discovery - the client reads the protected-resource metadata (RFC 9728) and the authorization-server metadata (RFC 8414) the gateway publishes for its path.
3. Registration - dynamic client registration (RFC 7591), bounded by rate, count and redirect-host rules; PKCE-only public clients.
4. Consent - the gateway's login page takes the Commander app password and shows the requested scopes as checkboxes; grant a subset if you like.
5. Token - authorization code → ES256 access token (1 h by default) + rotating refresh token (30 d). A replayed code revokes exactly its own lineage.
6. Tools appear - namespaced by umbrella; destructive commands carry a hint so Claude asks before sending confirm: true.

The step-by-step with screenshots and troubleshooting is on Connect a chat client to Commander over MCP.

Connecting ChatGPT

Create the connector with the same URL and OAuth. Standard connectors and Deep Research use only search and fetch; Developer Mode exposes the full umbrella set under the same scopes, phases and roles.

One tool call, end to end

• Transport - POST /mcp with a Bearer token verified locally (issuer, audience per RFC 8707, expiry, key id). Batches and sessions per subject are capped; a session's DELETE must come from its owner.
• Resolve - umbrella and command are looked up on null-prototype maps; an unknown or phase-disabled command is refused by name, never silently hidden.
• Gates - missing scope → -32001 Insufficient scope; destructive without confirm: true → an error that tells the model to ask the human and re-issue.
• Validate and relay - parameters are validated against the command's schema; command and confirm never leak upstream.
• Shape the result - structured content first; text is redacted, framed as untrusted with a per-call nonce, and capped at mcp_gateway_result_max_bytes; long lists come back as one line per row.
• Audit - one row per call with subject, client, tool, command, argument hash, outcome and latency. When the operator turns audit detail up, redacted arguments and results are kept for a bounded time as well, and every gateway session has its own id so a run can be studied afterwards.

Rolling out (operator, in short)

1. Mint the service token with scripts/mcp-gateway-setup.js --instance dev - it lands in secrets.env and the Password Vault, never in chat or git.
2. Start the gateway process with pm2 (--only commander-mcp-dev); Commander itself is not restarted.
3. Publish it: mcp_gateway_enabled, mcp_gateway_public_url (<origin>/mcp), and the reverse-proxy contexts for /mcp and the well-known discovery paths.
4. Phase 0 first, for as long as it takes to trust the audit trail; then 0,1 and 0,1,2 on dev. Phases are read at gateway boot - restart the gateway, not Commander.
5. Revoke a client or subject from the runbook when needed; every token lineage is traceable to the code that issued it.

Tunables the operator owns

All live under Settings → Advanced → MCP gateway and resolve settings row → environment → named default.

The other direction: Commander as a consumer

Commander also uses MCP servers. The broker resolves each credential path into one resolved connection that the per-session .mcp.json writer consumes when an agent is launched, and revokes tokens at session end. The gateway described here never touches that path; the two share only Commander's settings and audit conventions.

Reserved, not built

The terminal umbrella and git.commit have scopes but no handlers. ChatGPT Apps SDK widgets are a separate phase.