External MCP clients (Public Project MCP)

External MCP clients such as Claude (claude.ai and Claude Desktop custom connectors), Cursor, VS Code or other agents can connect to devctrl as a remote MCP server. Each connection is an OAuth 2.1 grant from one signed-in devctrl user. It covers only the Projects and permissions that user approved. Owners can revoke a connection or change its permissions at any time.

This is separate from the operator-only Private MCP tunnel for ChatGPT and from outbound managed OAuth, where devctrl is the OAuth client. Public Project MCP never grants operator or administrator authority and never accepts console, operator or native-session credentials.

When to use it

Control Room through the remote web, desktop or TUI console remains the primary way to operate devctrl remotely. Public Project MCP is for external agents and connectors that have no devctrl session and need a narrow, owner-approved view of selected Projects.

Enable it

The feature is disabled by default. A server administrator enables it on the controller with:

DEVCTL_EXTERNAL_MCP_ENABLED=1
DEVCTL_EXTERNAL_MCP_ORIGIN=https://console.example

Use the stable public HTTPS address of the web console, such as Integrations → Web links → Own domain / HTTPS reverse proxy. Tokens are bound to this exact origin. Devctrl serves the endpoints only while the web gateway reports that address as its current public URL. A changed or unavailable address fails closed: discovery returns 503 and no flow starts. Revocation keeps working. A temporary quick-tunnel hostname is not suitable because it changes. An invalid origin leaves the feature disabled and logs a warning; the controller keeps running.

The MCP server URL is https://console.example/v1/public/mcp.

Connect a client

  1. Add https://console.example/v1/public/mcp as a remote MCP server in the client. For example, use a custom connector in Claude, or add an url entry in Cursor's MCP settings.
  2. The client discovers the authorization server, registers itself and opens a browser tab. The tab shows the client name and an eight-letter code such as BCDF-GHJK. Keep this tab open.
  3. In the devctrl console, open Integrations → External MCP clients and select Approve request (r). Enter the code.
  4. Review the client name, how it identified itself, and its callback address. Select one or more Projects with Space. No Project is preselected. Toggle permissions with 1–4. Read permissions the client asked for are preselected. Send instructions is never preselected.
  5. Select Approve (a) or Deny (d). The browser tab returns to the client automatically. Only the browser tab that started the flow receives the authorization code.
  6. In the client, list the tools and call list_projects. Last used in the panel confirms that the client actually connected. Approval alone does not prove this.

Enter a code only if you started the connection yourself just now. Never enter a code that someone else sent you. The code expires after ten minutes. The review warns when the callback opens a local application, such as a loopback or cursor:// address. Any local application could receive such a callback.

Permissions and tools

Scope Tools Data
project:read list_projects, get_project Granted Projects, default branch, owned workspace IDs and status
session:read list_sessions Owned sessions of a granted Project: ID, name, agent kind, status, short work summary
tasks:read get_task_graph Agent-reported tasks, steps and todos of a granted Project
session:write send_session_instruction Types plain text into an existing running session

tools/list shows only the tools of the granted scopes. A call to a tool without its scope returns HTTP 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="…". A client can then request the scope again (step-up). The owner must approve it again.

Every result is limited to the grant owner. Projects must be owned by that user. Control Room Projects and sessions are never grantable. Sessions another user runs in the same Project are excluded, including shared or team sessions. Results exclude account IDs, native process and session IDs, host paths, credentials, prompts and terminal contents.

send_session_instruction uses the same input transport as messenger integrations. It requires an existing running coding session and rejects terminal control characters. It never starts, resumes or restarts a process. It does not record the text as a human instruction for automatic approval reviewers, and it cannot answer permission requests. Pass the same deliveryId when retrying.

Manage connections

Integrations → External MCP clients lists your own connections with client, Projects, permissions, last use and expiry. Select one and:

The management API uses the normal console authentication:

Method Route Notes
GET /v1/mcp/external-connections Readiness, MCP URL, grantable Projects, own connections
PUT /v1/mcp/external-connections/:id {expectedRevision, projectIds, scopes}
DELETE /v1/mcp/external-connections/:id Revoke
POST /v1/mcp/external-connections/requests/review {userCode}; the reviewer claims the request
POST /v1/mcp/external-connections/requests/:id/approve {projectIds, scopes}
POST /v1/mcp/external-connections/requests/:id/deny {}

Only GET and DELETE appear in the operator operation catalog. Review, approval, denial and permission edits are human consent. They are not in the catalog and reject delegated Control Room callers.

Protocol

The implementation follows the MCP authorization specification:

The web gateway forwards only these exact paths without a console credential. The authorization page's poll is the only route that receives a cookie: one dedicated HttpOnly cookie scoped to that request path.

Security properties

Limitations