Skip to content

docs: Add comprehensive MCP documentation section #19255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: Add comprehensive MCP documentation section #19255

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a36a72e
docs: Add comprehensive MCP documentation section
blink-so[bot] Aug 8, 2025
92f6a32
docs: Fix markdown linting errors in MCP documentation
blink-so[bot] Aug 8, 2025
e5f1ee6
docs: Fix broken links in MCP documentation
blink-so[bot] Aug 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
docs: Fix broken links in MCP documentation 
- Fix relative paths to reference correct documentation files
- Update pkg.go.dev links to use valid version format
- Ensure all internal links point to existing files

Resolves linkspector issues identified in CI.

Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>
  • Loading branch information
@blink-so @matifali
blink-so[bot] and matifali committed Aug 8, 2025
commit e5f1ee6869d308d439a417da8126369a16d5a653
16 changes: 14 additions & 2 deletions docs/ai-coder/mcp-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Coder's MCP server enables AI assistants to interact with Coder workspaces and i
- **Agent Activity**: Monitor AI agent operations and history

> [!NOTE]
> 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.
> See our [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk/toolsdk#pkg-variables) for a complete list of tools included in the MCP server.

## Architecture

Expand All @@ -27,6 +27,7 @@ Coder provides two MCP server modes to support different AI assistant architectu
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.

**Automatic Configuration**:

```sh
# First authenticate with Coder
coder login https://coder.example.com
Expand All @@ -37,6 +38,7 @@ coder exp mcp configure cursor
```

**Manual Server Start**:

```sh
# Start MCP server for manual configuration
coder exp mcp server
Expand All @@ -49,6 +51,7 @@ coder exp mcp server
The HTTP MCP server runs on your Coder deployment and provides web-based access for browser-based AI assistants.

**Enable HTTP MCP Server**:

```sh
# Enable experimental features
CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

double check if mcp-server-http is a valid experiment.

Expand All @@ -66,6 +69,7 @@ CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
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.

### Workspace Tools

- `list_workspaces` - List all accessible workspaces
- `create_workspace` - Create new workspaces from templates
- `start_workspace` - Start stopped workspaces
Expand All @@ -74,21 +78,24 @@ The Coder MCP server exposes a comprehensive set of tools through the Model Cont
- `get_workspace_status` - Check workspace status and resource usage

### Command Execution Tools

- `execute_command` - Run commands in workspace terminals
- `get_command_output` - Retrieve command execution results
- `list_processes` - List running processes in workspaces

### File System Tools

- `read_file` - Read file contents from workspaces
- `write_file` - Write files to workspace file systems
- `list_directory` - List directory contents

### Template and Resource Tools

- `list_templates` - List available workspace templates
- `get_template_info` - Get detailed template information
- `list_template_versions` - List template version history

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).
For the complete and up-to-date list of available tools, see the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk/toolsdk#pkg-variables).

## Configuration Options

Expand Down Expand Up @@ -125,12 +132,14 @@ export CODER_MCP_LOG_LEVEL=debug
## Security Considerations

### Authentication and Authorization

- **Local Mode**: Uses Coder CLI credentials and user permissions
- **HTTP Mode**: Requires OAuth2 authentication with proper scopes
- **Permission Inheritance**: MCP operations inherit the authenticated user's Coder permissions
- **Audit Logging**: All MCP operations are logged through Coder's audit system

### Best Practices

- Regularly rotate authentication credentials
- Monitor MCP usage through Coder's audit logs
- Use workspace templates with appropriate security configurations
Expand All @@ -142,16 +151,19 @@ export CODER_MCP_LOG_LEVEL=debug
### Common Issues

**MCP Server Won't Start**:

- Verify Coder CLI authentication: `coder whoami`
- Check experimental features are enabled for HTTP mode
- Review server logs for error messages

**AI Assistant Can't Connect**:

- Verify MCP server is running and accessible
- Check authentication credentials and permissions
- Ensure network connectivity to Coder deployment

**Permission Denied Errors**:

- Verify user has appropriate workspace permissions
- Check Coder RBAC settings
- Ensure OAuth2 scopes are correctly configured (HTTP mode)
Expand Down
4 changes: 2 additions & 2 deletions docs/mcp/claude-desktop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -333,5 +333,5 @@ For Claude Desktop-specific MCP issues:

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Claude Desktop User Guide](https://docs.anthropic.com/claude/docs/claude-desktop)
- [Coder CLI Reference](../../reference/cli.md)
- [Workspace Templates Guide](../../tutorials/templates.md)
- [Coder CLI Reference](../reference/cli/index.md)
- [Workspace Templates Guide](../tutorials/template-from-scratch.md)
2 changes: 1 addition & 1 deletion docs/mcp/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Coder MCP inherits Coder's robust security model:

## Available Tools and Capabilities

The Coder MCP server provides access to a comprehensive set of tools. See the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2@latest/codersdk/toolsdk#pkg-variables) for the complete list of available tools.
The Coder MCP server provides access to a comprehensive set of tools. See the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk/toolsdk#pkg-variables) for the complete list of available tools.

## Next Steps

Expand Down
8 changes: 4 additions & 4 deletions docs/mcp/web-agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,7 +324,7 @@ For enterprise deployments:
- Learn about [AI coding best practices](../ai-coder/best-practices.md)
- Set up [Coder Tasks](../ai-coder/tasks.md) for background operations
- Review [security considerations](../ai-coder/security.md) for AI development
- Check out [OAuth2 provider documentation](../../admin/integrations/oauth2-provider.md)
- Check out [OAuth2 provider documentation](../admin/integrations/oauth2-provider.md)

## Support

Expand All @@ -339,6 +339,6 @@ For web agent MCP issues:
## Additional Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Coder OAuth2 Provider Guide](../../admin/integrations/oauth2-provider.md)
- [Coder API Documentation](../../reference/api.md)
- [Web Security Best Practices](../../admin/security.md)
- [Coder OAuth2 Provider Guide](../admin/integrations/oauth2-provider.md)
- [Coder API Documentation](../reference/api/index.md)
- [Web Security Best Practices](../admin/security/index.md)
Loading