MCP access

The MCP module exposes a hosted Model Context Protocol endpoint so cloud agents — ChatGPT, Claude, and other MCP clients — can read mission context and use approved Overlord actions from their own interface. The assistant still follows workspace permissions and the mission lifecycle.

Note

This is the backend-hosted MCP surface, intentionally not a CLI shim. Local connector MCP scripts for Codex, Claude Code, Cursor, and Antigravity continue to use ovld protocol for checkout-local workflows — but they advertise the same canonical tool names and input contract as the hosted registry.

Endpoints

The hosted implementation is mounted by the backend when OVERLORD_MCP_ENABLED=true:

• GET /mcp — server/tool metadata for authenticated callers.
• POST /mcp — JSON-RPC MCP requests.
• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-protected-resource/mcp
• GET /.well-known/oauth-authorization-server
• POST /oauth/register
• GET /oauth/authorize (redirects to the web approval page)
• POST /oauth/token
• POST /oauth/revoke

The public ChatGPT Apps surface uses Apps SDK–compatible metadata: every tool has an input/output schema and a safety annotation, and read tools may point at bundled ui://overlord/* widget resources. The widgets are self-contained MCP Apps HTML; they render only a tool result’s structuredContent and make no third-party network or iframe requests.

Authentication

MCP requests authenticate through the backend Auth Layer before any tool is listed or invoked. Unauthenticated /mcp calls return a WWW-Authenticate: Bearer challenge pointing clients at the protected-resource metadata.

OAuth-aware clients use dynamic client registration followed by an authorization-code + PKCE flow. Approval happens in the web app at /oauth/approve; approving creates a scoped USER_TOKEN with the mission_lifecycle preset and exchanges the one-time authorization code for a bearer access token. Refresh tokens are not issued in contract version 0.

When a client supplies an OAuth resource parameter, Overlord binds it to the canonical hosted /mcp URL at approval and token exchange. A mismatch returns invalid_target; missing, denied, expired, revoked, or malformed credentials receive an OAuth-compatible 401 at /mcp.

Tip

When the SPA is deployed separately from the backend, the hosted web build can serve same-domain OAuth discovery metadata and proxy /mcp plus OAuth token traffic to the backend. Set OVERLORD_BACKEND_URL and OVERLORD_WEBAPP_PUBLIC_URL in the web deployment so remote MCP clients can use the webapp domain as the MCP resource.

See Authentication & troubleshooting for the credential model behind these tokens and the errors above.

Tools

The tool catalog is mission-first:

• overlord_resolve_project
• overlord_create_project
• overlord_list_project_statuses — read one project’s board columns (names and order are per project; the status type is not)
• overlord_search_missions
• overlord_create_mission
• overlord_create_inbox_item — create a private, account-owned unassigned task capture
• overlord_load_mission_context
• overlord_list_deliveries — read normalized delivery summaries for one mission; an objective display id such as coo:756.k7xm supplies the mission
• overlord_launch_objective — queue the normal execution request for one objective; requires objectiveId (UUID or display id) and agent; does not attach this MCP agent
• overlord_reorder_future_objectives — replace one mission’s complete future-objective UUID order
• overlord_add_objectives
• overlord_update_objective — turn auto-advance on or off and/or edit instruction text; requires objectiveId
• overlord_delete_missions — bulk soft-delete one to 100 missions (UUID or display id) atomically, also deleting their live objectives; requires confirm: true after the resolved list is shown to and approved by the user
• overlord_delete_objectives — bulk soft-delete one to 100 objectives (UUID or display id) atomically, also removing their live Run Queue membership; requires confirm: true after the resolved list is shown to and approved by the user
• overlord_list_run_queues — read compact or full Run Queue state before changing it
• overlord_reorder_run_queue — atomically replace every entry in one Run Queue
• overlord_queue_objective — add, move, or remove one objective from the project Run Queue, including front or rank placement; requires objectiveId
• overlord_manage_run_queue — create, update, delete, or reorder queue definitions with a full-scope token, or retry one held Run Queue entry with action: 'retry_entry' (uses execution_request:create, not a full-scope token)
• overlord_attach_session
• overlord_update_session
• overlord_deliver_session
• overlord_add_artifact — create a mission artifact mid-turn without delivering
• overlord_update_artifact — revise an existing mission artifact in place
• overlord_record_work

overlord_update_session, overlord_deliver_session, and overlord_record_work accept optional changeRationales annotations using canonical filePath, label, summary, why, impact, and optional header-only hunks. They annotate objective-ledger evidence; MCP does not enumerate changed files or inspect a worktree. Unknown item or hunk keys discard only that advisory entry with a bounded warning; for duplicate canonical paths, the last valid item wins.

Addressing a mission or an objective

Most mission-scoped tools take objectiveId — an objective UUID or a display id such as coo:756.k7xm — alongside missionId. A display id already names its parent mission, so missionId is optional whenever one is supplied. An objective UUID names no mission and still needs missionId. overlord_reorder_future_objectives is the exception: it only takes missionId, since it replaces the mission’s entire future-objective order rather than acting on one objective.

overlord_launch_objective, overlord_queue_objective, and overlord_update_objective require objectiveId as the primary argument — a display id is enough on its own. overlord_list_deliveries can take that same display id in place of missionId. On overlord_load_mission_context and overlord_attach_session the objective is also a pin: it selects which objective to read or execute, which is required on a mission running objectives in parallel.

Use overlord_list_run_queues before mutating a Run Queue. overlord_reorder_run_queue requires every live entry exactly once and returns the current order when it cannot safely apply a request. overlord_queue_objective accepts optional queue / after / front / position placement and remove: true to dequeue. Queue membership is target-neutral and sequences delivery-driven launches; it does not directly launch the objective. Entry operations require execution_request:create; overlord_manage_run_queue’s queue-definition actions (create/update/delete/reorder_queues) use project:update and require a full-scope token, but its retry_entry action uses execution_request:create like other entry operations. overlord_launch_objective is the explicit launch surface.

Widgets are attached to project resolution, mission search, mission-context, and delivery results:

• ui://overlord/project-selector.html
• ui://overlord/mission-list.html
• ui://overlord/objective-viewer.html
• ui://overlord/file-changes.html

The local connector MCP bridge scripts for Codex, Cursor, and Antigravity advertise the same canonical tool names and input contract shape. Backend tests compare those local tools/list responses against this hosted registry, so a new hosted tool cannot be added without updating the shipped connector shims.

Caution

Hosted MCP cannot observe an agent’s local working directory. Tools that create missions require an explicit projectId. Call overlord_resolve_project first when project identity comes from an exposed repository resource carrying .overlord/project.json.

overlord_add_artifact forwards to Protocol add-artifact and uses the same service as REST POST /api/missions/:id/artifacts. Required: type and label, plus at least one of contentText or externalUrl. Mission scope comes from either missionId or an objective display id passed as objectiveId/sessionKey — you don’t need all three. Use it to publish a plan, notes, or URL during a turn without delivering.

overlord_update_artifact forwards to Protocol update-artifact and uses the same service as REST PATCH /api/missions/:id/artifacts/:artifactId. Required: artifactId and expectedRevision, plus at least one of label, contentText, or externalUrl. As with overlord_add_artifact, mission scope comes from missionId or an objective display id, not both. Use it when a later objective must revise a plan artifact created earlier instead of delivering a duplicate.

Boundaries

MCP handlers call existing service/protocol functions and rely on their RBAC checks. They must not write database tables directly. Hosted MCP intentionally does not expose local filesystem inspection, runner queue claiming, execution-target mutation, or branch actions — those stay on the local CLI and runner surfaces.

Related

• The agent protocol — the equivalent lifecycle over the CLI, with the same operation names.
• Authentication & troubleshooting — token scopes and OAuth errors.