coder/docs/ai-coder/mcp-server.md

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

1. Open VS Code Command Palette and run MCP: Add Server...
2. Select From MCP Registry
3. Search for "Coder" and select it
4. Enter your Coder deployment hostname when prompted (e.g., coder.example.com)
5. 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:

1. Navigate to your Coder deployment
2. Go to Settings > Tokens
3. Create a new token
4. 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=true on 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, and tar uploads

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 workspace argument 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_background and check on them with coder_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 completion
• coder_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=true set
• 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