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
- Add
https://console.example/v1/public/mcpas a remote MCP server in the client. For example, use a custom connector in Claude, or add anurlentry in Cursor's MCP settings. - 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. - In the devctrl console, open Integrations → External MCP clients and
select Approve request (
r). Enter the code. - 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. - 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. - 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:
- toggle permissions with
1–4, then Save permissions (s). Narrowing applies to existing tokens immediately. Widening applies to newly issued tokens. - Revoke (
x) deletes all access and refresh tokens of the connection at once. - Copy MCP URL (
u).
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:
- Protected resource metadata (RFC 9728):
/.well-known/oauth-protected-resource/v1/public/mcp, also served at the root path. An unauthenticated MCP request returns401withresource_metadataand the default scopes. - Authorization server metadata (RFC 8414):
/.well-known/oauth-authorization-server. The issuer is the public origin. Responses includeiss(RFC 9207). - Client registration: Client ID Metadata Documents (
client_idis an HTTPS URL) and dynamic client registration (RFC 7591) at/v1/public/mcp/oauth/register. Public clients usenone. Confidential clients receive a client secret, and devctrl stores only its digest. - Authorization code with PKCE
S256only. Theresourceparameter (RFC 8707) must name this MCP server when present. Callbacks are HTTPS, HTTP loopback on any port (RFC 8252), or a private-use application scheme. - Tokens: access tokens last one hour. Refresh tokens rotate on each use and
last up to 30 days. A connection expires after 90 days. Replaying an
authorization code or a used refresh token revokes the whole connection.
Token revocation (RFC 7009) is available at
/v1/public/mcp/oauth/revoke. - Transport: stateless Streamable HTTP POST with JSON responses.
GETandDELETEreturn405. Requests carrying anOriginother than the public origin are rejected.
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
- Authorization codes, access tokens, refresh tokens, client secrets, user codes
and browser secrets are stored only as SHA-256 digests in the controller
database (
external_mcp_*tables). The authorization code is created when the starting browser picks up the approval, and devctrl never stores it in plaintext. - OAuth and MCP routes are excluded from request logging. Audit events record approval, denial, permission changes, revocation, token replay and each tool call, attributed to the owner. Audit events never include tokens, codes or instruction text.
- Rate limits: client registration 30/hour, authorization starts 60/minute, token requests 300/minute in total and 60/minute per client, code reviews 10 per ten minutes per user, MCP requests 120/minute per connection with at most 4 concurrent requests per connection and 16 in total. Pending requests, registered clients, connections per user (50) and stored tokens are bounded.
- Client metadata documents are fetched over HTTPS only, from public addresses only. The resolved address is pinned. Redirects are not followed, and size and time are bounded.
- Every request rechecks the grant, the owner's account and Project ownership. A disabled user, a removed Project or a revoked grant stops access.
Limitations
- Released in 0.1.65 without being exercised against real hosted clients. Treat each client as unverified until you have connected it yourself.
- Consent uses a code entered in the console. It does not use an in-browser consent screen, so it works from the terminal TUI too. Like any device-code style flow, it relies on the user not entering a code that someone else sent.
- Self-registered client names are not verified. Client ID Metadata Documents identify the client by the URL that publishes it.
- The authorization page is localized from the browser's
Accept-Languageheader. Compatibility with each hosted client product, plan or organization policy must be verified separately with that real client.