# MCP server
Coder includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (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](#local-mcp-server)**:
Runs via the Coder CLI using stdio transport.
Ideal for local AI tools and IDE integrations.
* **[Remote MCP Server](#remote-mcp-server)**:
HTTP-based server exposed by your Coder deployment.
Supports OAuth2 authentication and is published to the MCP Registry.
## Local MCP Server [#local-mcp-server]
The local MCP server runs via the Coder CLI and uses stdio transport to communicate with AI tools.
### Setup [#setup]
Run the MCP server using the Coder CLI:
```sh
coder exp mcp server
```
### Client Configuration [#client-configuration]
Configure your MCP client to spawn the Coder CLI:
```json
{
"mcpServers": {
"coder": {
"command": "coder",
"args": ["exp", "mcp", "server"]
}
}
}
```
The CLI automatically uses your existing Coder authentication (from `coder login`).
### Claude Desktop Example [#claude-desktop-example]
Add to your Claude Desktop configuration file:
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"coder": {
"command": "coder",
"args": ["exp", "mcp", "server"]
}
}
}
```
Edit `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"coder": {
"command": "coder.exe",
"args": ["exp", "mcp", "server"]
}
}
}
```
## Remote 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](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports) 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 [#prerequisites]
The remote MCP HTTP endpoint requires the OAuth2 provider and the `mcp-server-http` experiment on your Coder deployment:
```sh
coder server --oauth2-provider-enable --experiments=mcp-server-http
```
Or set the environment variables:
```sh
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](/beta-docs/@main/admin/integrations/oauth2-provider/#enable-oauth2-provider).
That page does not cover the experiment; set it with the top-level [`experiments`](/beta-docs/@main/reference/cli/server/#--experiments) YAML key.
### MCP Registry [#mcp-registry]
Coder is published to the official [MCP Registry](https://github.com/modelcontextprotocol/registry) as `io.github.coder/coder`, enabling easy installation in supported MCP clients.
#### VS Code / GitHub Copilot [#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) [#claude-desktop-remote]
Add to your Claude Desktop configuration file (`claude_desktop_config.json`):
```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 [#manual-configuration]
For MCP clients that don't support the registry or OAuth2 discovery, configure the server manually with a session token:
```json
{
"mcpServers": {
"coder": {
"url": "https://coder.example.com/api/experimental/mcp/http",
"headers": {
"Coder-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 [#authentication]
The MCP server supports two authentication methods:
### OAuth2 (Recommended for Interactive Clients) [#oauth2-recommended-for-interactive-clients]
MCP clients that support [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (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`.
OAuth2 requires `CODER_OAUTH2_PROVIDER_ENABLE=true` on your Coder deployment.
[Dynamic Client Registration (DCR)](/beta-docs/@main/admin/integrations/oauth2-provider/#dynamic-client-registration) is off by default and must be enabled before clients can self-register.
### Session Token (For Programmatic Access) [#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](#manual-configuration) section.
## Available Tools [#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](https://github.com/coder/coder/blob/main/codersdk/toolsdk/toolsdk.go).
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](/beta-docs/@main/ai-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 [#available-prompts]
The MCP server also exposes [prompts](https://modelcontextprotocol.io/specification/2026-07-28/server/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 [#troubleshooting]
### "Unauthorized" errors [#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 [#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 [#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](/beta-docs/@main/admin/integrations/oauth2-provider/#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