Skip to content

Commit a36a72e

Browse files
blink-so[bot]matifali
blink-so[bot]
and
matifali
committed
docs: Add comprehensive MCP documentation section
Adds a new dedicated MCP section to the documentation with: - Landing page explaining Coder MCP and its benefits - Setup guides for VSCode, Cursor, Zed, WindSurf, Claude Desktop, and web agents - Updated manifest.json to organize MCP docs as a dedicated section - Enhanced mcp-server.md as technical reference with better organization This provides users with clear, IDE-specific guidance for setting up Model Context Protocol integration with their AI assistants. Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>
1 parent afb54f6 commit a36a72e

File tree

9 files changed

+2035
-34
lines changed

9 files changed

+2035
-34
lines changed

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

Lines changed: 162 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,190 @@
1-
# MCP Server
1+
# MCP Server Reference
22

3-
Power users can configure [claude.ai](https://claude.ai), Claude Desktop, Cursor, or other external agents to interact with Coder in order to:
3+
This page provides technical reference information for Coder's Model Context Protocol (MCP) server implementation. For setup guides with specific AI tools and IDEs, see the [MCP documentation](../mcp/index.md).
44

5-
- List workspaces
6-
- Create/start/stop workspaces
7-
- Run commands on workspaces
8-
- Check in on agent activity
5+
## Overview
6+
7+
Coder's MCP server enables AI assistants to interact with Coder workspaces and infrastructure through the standardized Model Context Protocol. The server provides tools for:
8+
9+
- **Workspace Management**: List, create, start, stop, and delete workspaces
10+
- **Command Execution**: Run commands in remote workspaces
11+
- **Resource Monitoring**: Check workspace status and resource usage
12+
- **Agent Activity**: Monitor AI agent operations and history
913

1014
> [!NOTE]
11-
> See our [toolsdk](https://pkg.go.dev/github.com/coder/coder/v2@v2.24.1/codersdk/toolsdk#pkg-variables) documentation for a full list of tools included in the MCP server
15+
> See our [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2@latest/codersdk/toolsdk#pkg-variables) for a complete list of tools included in the MCP server.
16+
17+
## Architecture
1218

13-
In this model, any custom agent could interact with a remote Coder workspace, or Coder can be used in a remote pipeline or a larger workflow.
19+
The Coder MCP server acts as a bridge between AI assistants and the Coder API, providing secure and controlled access to development environments.
1420

15-
## Local MCP server
21+
## Server Modes
1622

17-
The Coder CLI has options to automatically configure MCP servers for you. On your local machine, run the following command:
23+
Coder provides two MCP server modes to support different AI assistant architectures:
1824

25+
### Local MCP Server (stdio)
26+
27+
The local MCP server runs on your machine and communicates with AI assistants through standard input/output. This mode is ideal for desktop applications and local development tools.
28+
29+
**Automatic Configuration**:
1930
```sh
20-
# First log in to Coder.
21-
coder login <https://coder.example.com>
31+
# First authenticate with Coder
32+
coder login https://coder.example.com
2233

23-
# Configure your client with the Coder MCP
24-
coder exp mcp configure claude-desktop # Configure Claude Desktop to interact with Coder
25-
coder exp mcp configure cursor # Configure Cursor to interact with Coder
34+
# Configure specific AI tools
35+
coder exp mcp configure claude-desktop
36+
coder exp mcp configure cursor
2637
```
2738

28-
For other agents, run the MCP server with this command:
29-
39+
**Manual Server Start**:
3040
```sh
41+
# Start MCP server for manual configuration
3142
coder exp mcp server
3243
```
3344

45+
**Authentication**: Uses your Coder CLI credentials and inherits your user permissions.
46+
47+
### Remote MCP Server (HTTP)
48+
49+
The HTTP MCP server runs on your Coder deployment and provides web-based access for browser-based AI assistants.
50+
51+
**Enable HTTP MCP Server**:
52+
```sh
53+
# Enable experimental features
54+
CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
55+
```
56+
57+
**Endpoint**: `https://your-coder-deployment.com/api/experimental/mcp/http`
58+
59+
**Authentication**: Uses OAuth2 for secure web-based authentication.
60+
3461
> [!NOTE]
35-
> The MCP server is authenticated with the same identity as your Coder CLI and can perform any action on the user's behalf. Fine-grained permissions are in development. [Contact us](https://coder.com/contact) if this use case is important to you.
62+
> Both server modes operate with the authenticated user's permissions. Fine-grained MCP-specific permissions are in development. [Contact us](https://coder.com/contact) if this is important for your use case.
63+
64+
## Available Tools
65+
66+
The Coder MCP server exposes a comprehensive set of tools through the Model Context Protocol. These tools are automatically available to any connected AI assistant.
67+
68+
### Workspace Tools
69+
- `list_workspaces` - List all accessible workspaces
70+
- `create_workspace` - Create new workspaces from templates
71+
- `start_workspace` - Start stopped workspaces
72+
- `stop_workspace` - Stop running workspaces
73+
- `delete_workspace` - Delete workspaces
74+
- `get_workspace_status` - Check workspace status and resource usage
3675

37-
## Remote MCP server
76+
### Command Execution Tools
77+
- `execute_command` - Run commands in workspace terminals
78+
- `get_command_output` - Retrieve command execution results
79+
- `list_processes` - List running processes in workspaces
3880

39-
Coder can expose an MCP server via HTTP. This is useful for connecting web-based agents, like https://claude.ai/, to Coder. This is an experimental feature and is subject to change.
81+
### File System Tools
82+
- `read_file` - Read file contents from workspaces
83+
- `write_file` - Write files to workspace file systems
84+
- `list_directory` - List directory contents
4085

41-
To enable this feature, activate the `oauth2` and `mcp-server-http` experiments using an environment variable or a CLI flag:
86+
### Template and Resource Tools
87+
- `list_templates` - List available workspace templates
88+
- `get_template_info` - Get detailed template information
89+
- `list_template_versions` - List template version history
90+
91+
For the complete and up-to-date list of available tools, see the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2@latest/codersdk/toolsdk#pkg-variables).
92+
93+
## Configuration Options
94+
95+
### Local MCP Server Options
96+
97+
Customize the local MCP server behavior:
4298

4399
```sh
44-
CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
45-
# or
46-
coder server --experiments=oauth2,mcp-server-http
100+
# Enable debug logging
101+
coder exp mcp server --log-level debug
102+
103+
# Set custom timeout
104+
coder exp mcp server --timeout 60s
105+
106+
# Specify workspace filter
107+
coder exp mcp server --workspace-filter "owner:me"
47108
```
48109

49-
The Coder server will expose the MCP server at:
110+
### HTTP MCP Server Options
111+
112+
Configure the HTTP MCP server through environment variables:
113+
114+
```sh
115+
# Set custom timeout for HTTP requests
116+
export CODER_MCP_HTTP_TIMEOUT=120s
117+
118+
# Configure rate limiting
119+
export CODER_MCP_HTTP_RATE_LIMIT=100
50120

51-
```txt
52-
https://coder.example.com/api/experimental/mcp/http
121+
# Enable detailed logging
122+
export CODER_MCP_LOG_LEVEL=debug
53123
```
54124

55-
> [!NOTE]
56-
> At this time, the remote MCP server is not compatible with web-based ChatGPT.
125+
## Security Considerations
126+
127+
### Authentication and Authorization
128+
- **Local Mode**: Uses Coder CLI credentials and user permissions
129+
- **HTTP Mode**: Requires OAuth2 authentication with proper scopes
130+
- **Permission Inheritance**: MCP operations inherit the authenticated user's Coder permissions
131+
- **Audit Logging**: All MCP operations are logged through Coder's audit system
132+
133+
### Best Practices
134+
- Regularly rotate authentication credentials
135+
- Monitor MCP usage through Coder's audit logs
136+
- Use workspace templates with appropriate security configurations
137+
- Implement proper secret management in workspaces
138+
- Review AI assistant access patterns regularly
139+
140+
## Troubleshooting
141+
142+
### Common Issues
143+
144+
**MCP Server Won't Start**:
145+
- Verify Coder CLI authentication: `coder whoami`
146+
- Check experimental features are enabled for HTTP mode
147+
- Review server logs for error messages
148+
149+
**AI Assistant Can't Connect**:
150+
- Verify MCP server is running and accessible
151+
- Check authentication credentials and permissions
152+
- Ensure network connectivity to Coder deployment
153+
154+
**Permission Denied Errors**:
155+
- Verify user has appropriate workspace permissions
156+
- Check Coder RBAC settings
157+
- Ensure OAuth2 scopes are correctly configured (HTTP mode)
158+
159+
### Debug Mode
160+
161+
Enable debug logging for troubleshooting:
162+
163+
```sh
164+
# Local MCP server
165+
coder exp mcp server --log-level debug
166+
167+
# HTTP MCP server
168+
CODER_MCP_LOG_LEVEL=debug CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
169+
```
170+
171+
## Getting Started
172+
173+
For step-by-step setup instructions with specific AI tools and IDEs, see:
174+
175+
- [MCP Overview](../mcp/index.md) - Introduction and concepts
176+
- [VSCode Setup](../mcp/vscode.md) - Visual Studio Code integration
177+
- [Cursor Setup](../mcp/cursor.md) - Cursor AI editor integration
178+
- [Zed Setup](../mcp/zed.md) - Zed editor integration
179+
- [WindSurf Setup](../mcp/windsurf.md) - WindSurf AI environment integration
180+
- [Claude Desktop Setup](../mcp/claude-desktop.md) - Claude Desktop integration
181+
- [Web Agents Setup](../mcp/web-agents.md) - Browser-based AI assistants
182+
183+
## Support
184+
185+
For technical support with Coder MCP:
57186

58-
Users can authenticate applications to use the remote MCP server with [OAuth2](../admin/integrations/oauth2-provider.md). An authenticated application can perform any action on the user's behalf. Fine-grained permissions are in development.
187+
- [Contact Coder Support](https://coder.com/contact)
188+
- [Join our Discord Community](https://discord.gg/coder)
189+
- [Report Issues on GitHub](https://github.com/coder/coder/issues)
190+
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)

‎docs/manifest.json

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -875,10 +875,47 @@
875875
]
876876
},
877877
{
878-
"title": "MCP Server",
879-
"description": "Connect to agents Coder with a MCP server",
880-
"path": "./ai-coder/mcp-server.md",
881-
"state": ["beta"]
878+
"title": "Model Context Protocol (MCP)",
879+
"description": "Connect AI assistants to Coder with Model Context Protocol",
880+
"path": "./mcp/index.md",
881+
"state": ["beta"],
882+
"children": [
883+
{
884+
"title": "VSCode",
885+
"description": "Set up Coder MCP with Visual Studio Code",
886+
"path": "./mcp/vscode.md"
887+
},
888+
{
889+
"title": "Cursor",
890+
"description": "Set up Coder MCP with Cursor AI editor",
891+
"path": "./mcp/cursor.md"
892+
},
893+
{
894+
"title": "Zed",
895+
"description": "Set up Coder MCP with Zed editor",
896+
"path": "./mcp/zed.md"
897+
},
898+
{
899+
"title": "WindSurf",
900+
"description": "Set up Coder MCP with WindSurf AI environment",
901+
"path": "./mcp/windsurf.md"
902+
},
903+
{
904+
"title": "Claude Desktop",
905+
"description": "Set up Coder MCP with Claude Desktop",
906+
"path": "./mcp/claude-desktop.md"
907+
},
908+
{
909+
"title": "Web-based Agents",
910+
"description": "Set up Coder MCP with web-based AI agents",
911+
"path": "./mcp/web-agents.md"
912+
},
913+
{
914+
"title": "MCP Server Reference",
915+
"description": "Technical reference for Coder MCP server",
916+
"path": "./ai-coder/mcp-server.md"
917+
}
918+
]
882919
}
883920
]
884921
},

0 commit comments

Comments
 (0)