## Problem VS Code discovers Coder's MCP endpoint as a path-qualified OAuth resource, but Coder advertises the deployment root. Accepting MCP-bound tokens also requires keeping REST-backed tool calls within the originating MCP resource rather than granting those tokens direct REST access. ## Fix - Publish path-aware protected resource metadata and authentication challenges; keep authorization-server metadata at the root. - Validate the MCP audience and delegate tool requests through a private in-process transport that retains identity, scopes, expiry, revocation, and streaming cancellation. - Reject unsupported MCP path aliases and validate SDK path components before URL resolution. - Add discovery, audience, authorization, endpoint-isolation, and transport lifecycle regression tests and update integration docs. ## Validation VS Code completed OAuth and returned the authenticated user through a real MCP tool. Official MCP SDK 1.30.1 completed discovery, registration, PKCE, tool execution, and refresh. These live checks preceded the final path hardening; the hardened paths are covered by automated regressions. Affected Go package tests, targeted race tests, backend/SDK lint, and targeted documentation checks passed during self-review. The exact PR commit was also checked separately from the uncommitted consent-scope fix. > [!NOTE] > Tokens are MCP-audience-bound, but grants still include `coder:all`; least-privilege scopes remain a separate requirement ([PLAT-639](https://linear.app/codercom/issue/PLAT-639)). Preview: https://coder.com/docs/@fix/mcp-internal-delegation/ai-coder/mcp-server <details> <summary>Implementation decisions and review context</summary> 1. Treat `/api/experimental/mcp/http` and its single-trailing-slash form as supported MCP resource paths; reject other aliases and descendants before route authentication. 2. Preserve deployment-root discovery and authorization-server metadata for existing REST integrations. 3. Bind private delegation to the authenticated API-key ID. Revalidate the original credential and enforce normal RBAC/scopes on every internal REST request; do not derive delegation from HTTP headers. 4. Keep internal HTTP, streaming, and WebSocket traffic in-process with no network fallback. Close the transport on outer-request cancellation and normal completion. 5. Validate workspace owner/name path segments before SDK URL construction, including tool-level tests that malformed arguments cannot select a different REST endpoint. 6. Keep compatibility and delegated tool execution together: discovery-only changes would allow authentication while leaving real MCP tool calls broken. </details> > 🤖 This PR was created with the help of Coder Agents, and needs a human review. 🧑💻
8.6 KiB
title
| title |
|---|
| MCP server |
Coder includes a built-in Model Context Protocol (MCP) server that provides AI assistants with tools and context about your Coder deployment. This enables AI-powered workflows for managing workspaces, templates, and development environments.
Coder supports two MCP server modes:
- Local MCP Server: Runs via the Coder CLI using stdio transport. Ideal for local AI tools and IDE integrations.
- Remote MCP Server: HTTP-based server exposed by your Coder deployment. Supports OAuth2 authentication and is published to the MCP Registry.
Local MCP Server
The local MCP server runs via the Coder CLI and uses stdio transport to communicate with AI tools.
Setup
Run the MCP server using the Coder CLI:
coder exp mcp server
Client Configuration
Configure your MCP client to spawn the Coder CLI:
{
"mcpServers": {
"coder": {
"command": "coder",
"args": ["exp", "mcp", "server"]
}
}
}
The CLI automatically uses your existing Coder authentication (from coder login).
Claude Desktop Example
Add to your Claude Desktop configuration file:
macOS
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"coder": {
"command": "coder",
"args": ["exp", "mcp", "server"]
}
}
}
Windows
Edit %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"coder": {
"command": "coder.exe",
"args": ["exp", "mcp", "server"]
}
}
}
Remote MCP Server
The remote MCP server is an HTTP endpoint exposed by your Coder deployment at
/api/experimental/mcp/http. This enables MCP clients to connect to Coder
without running the CLI locally.
The endpoint implements the
Streamable HTTP transport
in stateless mode: it supports MCP specification versions from 2024-11-05
through 2026-07-28, does not issue Mcp-Session-Id headers, and answers
GET and DELETE with 405 Method Not Allowed (there is no standalone
server-event stream or explicit session termination, both permitted by the
specification). The server exposes tools only; MCP resources, prompts,
structured tool output, elicitation, and the MCP Tasks extension are not
implemented.
Prerequisites
The remote MCP HTTP endpoint requires the OAuth2 provider and the mcp-server-http experiment on your Coder deployment:
coder server --oauth2-provider-enable --experiments=mcp-server-http
Or set the environment variables:
CODER_OAUTH2_PROVIDER_ENABLE=true
CODER_EXPERIMENTS=mcp-server-http
For the YAML and Helm forms of the provider setting, refer to Enable OAuth2 Provider.
That page does not cover the experiment; set it with the top-level experiments YAML key.
MCP Registry
Coder is published to the official MCP Registry
as io.github.coder/coder, enabling easy installation in supported MCP clients.
VS Code / GitHub Copilot
- Open VS Code Command Palette and run MCP: Add Server...
- Select From MCP Registry
- Search for "Coder" and select it
- Enter your Coder deployment hostname when prompted (e.g.,
coder.example.com) - VS Code will automatically handle OAuth2 authentication
Claude Desktop (Remote)
Add to your Claude Desktop configuration file (claude_desktop_config.json):
{
"mcpServers": {
"coder": {
"url": "https://coder.example.com/api/experimental/mcp/http"
}
}
}
Claude Desktop will automatically discover OAuth2 endpoints and prompt you to authenticate through your browser.
Manual Configuration
For MCP clients that don't support the registry or OAuth2 discovery, configure the server manually with a session token:
{
"mcpServers": {
"coder": {
"url": "https://coder.example.com/api/experimental/mcp/http",
"headers": {
"Coder-Session-Token": "<your-session-token>"
}
}
}
}
To create a session token:
- Navigate to your Coder deployment
- Go to Settings > Tokens
- Create a new token
- Add the token to your MCP client configuration
Authentication
The MCP server supports two authentication methods:
OAuth2 (Recommended for Interactive Clients)
MCP clients that support RFC 9728 (Protected Resource Metadata) can authenticate automatically using OAuth2. This enables a seamless connect-and-authenticate experience where users sign in through their browser without manually managing tokens.
The MCP endpoint's WWW-Authenticate header points to /.well-known/oauth-protected-resource/api/experimental/mcp/http through its resource_metadata parameter.
This metadata identifies the full MCP endpoint URL as the resource, for example, https://coder.example.com/api/experimental/mcp/http.
Note
OAuth2 requires
CODER_OAUTH2_PROVIDER_ENABLE=trueon your Coder deployment.Dynamic Client Registration (DCR) is off by default and must be enabled before clients can self-register.
Session Token (For Programmatic Access)
For clients that don't support OAuth2 discovery, or for programmatic access, use a session token as shown in the Manual Configuration section.
Available Tools
The MCP server exposes tools across several areas:
- Workspace management: list, inspect, create, and build workspaces
- Template operations: list, inspect, create, and manage templates and versions
- File operations: read, write, and edit files in a workspace
- Workspace interaction: run commands, manage background processes, forward ports, list apps, and read logs
- Coder Agents chats: create chats, send messages, read transcripts and status, interrupt, archive, and list available models
- User and system: authenticated user details, organization memberships, tar uploads, and task reporting
The full, authoritative set of tools, including their names, descriptions, and
arguments, is defined in Coder's
toolsdk package. Refer to it for the
current list, since the available tools can change between releases.
The workspace file and command tools (coder_workspace_read_file,
coder_workspace_write_file, coder_workspace_edit_files,
coder_workspace_execute, and the coder_workspace_process_* tools) share
their arguments and result formats with the matching
Coder Agents tools, with these differences:
- Each tool takes a
workspaceargument that selects the workspace to act on. - Invalid arguments and workspace agent errors are returned as MCP tool errors.
- A single call waits at most 5 minutes. Run longer commands with
run_in_backgroundand check on them withcoder_workspace_process_output. - Commands started through MCP are separate from Coder Agents chat processes, but anyone with SSH access to the workspace can list and signal them.
Available Prompts
The MCP server also exposes prompts for common Coder Agents chat workflows. Clients that support prompts surface them for you to invoke, for example as slash commands:
coder_agents_delegate: delegate a coding task to a Coder Agents chat and monitor it to completioncoder_agents_check: check the status and recent activity of an existing Coder Agents chat
Troubleshooting
"Unauthorized" errors
- Verify your session token is valid and not expired
- Check that the MCP server experiment is enabled on your deployment
- Ensure your user has appropriate permissions for the requested operations
Connection timeouts
- Verify your Coder deployment URL is correct and accessible
- Check network connectivity between your MCP client and the control plane
- Review the logs from
coderd, the process that runs the control plane, for any errors
OAuth2 authentication not working
- Ensure your Coder deployment has
CODER_OAUTH2_PROVIDER_ENABLE=trueset - If your client registers itself automatically, ensure Dynamic Client Registration is enabled
- Verify your MCP client supports RFC 9728 Protected Resource Metadata
- Check that your browser can reach the Coder authorization endpoint