diff --git a/docs/ai-coder/mcp-server.md b/docs/ai-coder/mcp-server.md index fdfadb4117d36..031b94238c8ce 100644 --- a/docs/ai-coder/mcp-server.md +++ b/docs/ai-coder/mcp-server.md @@ -1,58 +1,202 @@ -# MCP Server +# MCP Server Reference -Power users can configure [claude.ai](https://claude.ai), Claude Desktop, Cursor, or other external agents to interact with Coder in order to: +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). -- List workspaces -- Create/start/stop workspaces -- Run commands on workspaces -- Check in on agent activity +## Overview + +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: + +- **Workspace Management**: List, create, start, stop, and delete workspaces +- **Command Execution**: Run commands in remote workspaces +- **Resource Monitoring**: Check workspace status and resource usage +- **Agent Activity**: Monitor AI agent operations and history > [!NOTE] -> 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 +> 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 + +The Coder MCP server acts as a bridge between AI assistants and the Coder API, providing secure and controlled access to development environments. -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. +## Server Modes -## Local MCP server +Coder provides two MCP server modes to support different AI assistant architectures: -The Coder CLI has options to automatically configure MCP servers for you. On your local machine, run the following command: +### Local MCP Server (stdio) + +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 log in to Coder. -coder login +# First authenticate with Coder +coder login https://coder.example.com -# Configure your client with the Coder MCP -coder exp mcp configure claude-desktop # Configure Claude Desktop to interact with Coder -coder exp mcp configure cursor # Configure Cursor to interact with Coder +# Configure specific AI tools +coder exp mcp configure claude-desktop +coder exp mcp configure cursor ``` -For other agents, run the MCP server with this command: +**Manual Server Start**: ```sh +# Start MCP server for manual configuration coder exp mcp server ``` -> [!NOTE] -> 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. +**Authentication**: Uses your Coder CLI credentials and inherits your user permissions. -## Remote MCP server +### Remote MCP Server (HTTP) -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. +The HTTP MCP server runs on your Coder deployment and provides web-based access for browser-based AI assistants. -To enable this feature, activate the `oauth2` and `mcp-server-http` experiments using an environment variable or a CLI flag: +**Enable HTTP MCP Server**: ```sh +# Enable experimental features CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server -# or -coder server --experiments=oauth2,mcp-server-http ``` -The Coder server will expose the MCP server at: +**Endpoint**: `https://your-coder-deployment.com/api/experimental/mcp/http` -```txt -https://coder.example.com/api/experimental/mcp/http -``` +**Authentication**: Uses OAuth2 for secure web-based authentication. > [!NOTE] -> At this time, the remote MCP server is not compatible with web-based ChatGPT. +> 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. + +## Available Tools + +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 +- `stop_workspace` - Stop running workspaces +- `delete_workspace` - Delete workspaces +- `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/codersdk/toolsdk#pkg-variables). + +## Configuration Options + +### Local MCP Server Options + +Customize the local MCP server behavior: + +```sh +# Enable debug logging +coder exp mcp server --log-level debug + +# Set custom timeout +coder exp mcp server --timeout 60s + +# Specify workspace filter +coder exp mcp server --workspace-filter "owner:me" +``` + +### HTTP MCP Server Options + +Configure the HTTP MCP server through environment variables: + +```sh +# Set custom timeout for HTTP requests +export CODER_MCP_HTTP_TIMEOUT=120s + +# Configure rate limiting +export CODER_MCP_HTTP_RATE_LIMIT=100 + +# Enable detailed logging +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 +- Implement proper secret management in workspaces +- Review AI assistant access patterns regularly + +## Troubleshooting + +### 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) + +### Debug Mode + +Enable debug logging for troubleshooting: + +```sh +# Local MCP server +coder exp mcp server --log-level debug + +# HTTP MCP server +CODER_MCP_LOG_LEVEL=debug CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server +``` + +## Getting Started + +For step-by-step setup instructions with specific AI tools and IDEs, see: + +- [MCP Overview](../mcp/index.md) - Introduction and concepts +- [VSCode Setup](../mcp/vscode.md) - Visual Studio Code integration +- [Cursor Setup](../mcp/cursor.md) - Cursor AI editor integration +- [Zed Setup](../mcp/zed.md) - Zed editor integration +- [WindSurf Setup](../mcp/windsurf.md) - WindSurf AI environment integration +- [Claude Desktop Setup](../mcp/claude-desktop.md) - Claude Desktop integration +- [Web Agents Setup](../mcp/web-agents.md) - Browser-based AI assistants + +## Support + +For technical support with Coder MCP: -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. +- [Contact Coder Support](https://coder.com/contact) +- [Join our Discord Community](https://discord.gg/coder) +- [Report Issues on GitHub](https://github.com/coder/coder/issues) +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) diff --git a/docs/manifest.json b/docs/manifest.json index ce03ef0ff2de1..f9b10a9ea2862 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -875,10 +875,47 @@ ] }, { - "title": "MCP Server", - "description": "Connect to agents Coder with a MCP server", - "path": "./ai-coder/mcp-server.md", - "state": ["beta"] + "title": "Model Context Protocol (MCP)", + "description": "Connect AI assistants to Coder with Model Context Protocol", + "path": "./mcp/index.md", + "state": ["beta"], + "children": [ + { + "title": "VSCode", + "description": "Set up Coder MCP with Visual Studio Code", + "path": "./mcp/vscode.md" + }, + { + "title": "Cursor", + "description": "Set up Coder MCP with Cursor AI editor", + "path": "./mcp/cursor.md" + }, + { + "title": "Zed", + "description": "Set up Coder MCP with Zed editor", + "path": "./mcp/zed.md" + }, + { + "title": "WindSurf", + "description": "Set up Coder MCP with WindSurf AI environment", + "path": "./mcp/windsurf.md" + }, + { + "title": "Claude Desktop", + "description": "Set up Coder MCP with Claude Desktop", + "path": "./mcp/claude-desktop.md" + }, + { + "title": "Web-based Agents", + "description": "Set up Coder MCP with web-based AI agents", + "path": "./mcp/web-agents.md" + }, + { + "title": "MCP Server Reference", + "description": "Technical reference for Coder MCP server", + "path": "./ai-coder/mcp-server.md" + } + ] } ] }, diff --git a/docs/mcp/claude-desktop.md b/docs/mcp/claude-desktop.md new file mode 100644 index 0000000000000..adbb1d406845f --- /dev/null +++ b/docs/mcp/claude-desktop.md @@ -0,0 +1,337 @@ +# Using Coder MCP with Claude Desktop + +This guide shows you how to set up Coder's Model Context Protocol (MCP) server with Claude Desktop, Anthropic's desktop AI assistant. + +## Prerequisites + +- Claude Desktop installed +- Coder CLI installed and authenticated +- Active Coder deployment + +## Setup + +### Automatic Configuration (Recommended) + +The Coder CLI can automatically configure MCP for Claude Desktop: + +```bash +# First, authenticate with your Coder deployment +coder login https://coder.example.com + +# Configure Claude Desktop to use Coder MCP +coder exp mcp configure claude-desktop +```txt + +This command will: +- Locate your Claude Desktop configuration file +- Add the Coder MCP server configuration +- Set up the necessary authentication + +### Manual Configuration + +If automatic configuration doesn't work, you can manually set up MCP: + +1. **Locate Claude Desktop's configuration file**: + - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + - **Linux**: `~/.config/Claude/claude_desktop_config.json` + +1. **Add Coder MCP server configuration**: + ```json + { + "mcpServers": { + "coder": { + "command": "coder", + "args": ["exp", "mcp", "server"], + "env": {} + } + } + } + ``` + +1. **Restart Claude Desktop** to load the new configuration. + +## Using Coder MCP with Claude Desktop + +Once configured, Claude can interact with your Coder workspaces through MCP, providing powerful AI assistance for your development workflows. + +### Available Capabilities + +**Workspace Management**: + +- List and inspect your Coder workspaces +- Create new workspaces from templates +- Start, stop, and manage workspace lifecycle +- Monitor workspace status and resource usage + +**Development Operations**: + +- Execute commands in remote workspaces +- Run build scripts, tests, and deployment processes +- Install packages and manage dependencies +- Access workspace terminals and file systems + +**AI-Assisted Development**: + +- Analyze code in your actual development environments +- Generate code that works with your specific workspace setup +- Debug issues using live workspace context +- Provide recommendations based on your actual infrastructure + +### Example Interactions + +**Project setup and initialization**: + +```txt +You: "I need to set up a new Python web application with FastAPI. Can you create a workspace and set up the project structure?" + +Claude: I'll help you create a new Coder workspace and set up a FastAPI project. Let me: +1. Create a new workspace using a Python template +1. Install FastAPI and dependencies +1. Set up the basic project structure +4. Create a simple API endpoint to get you started + +[Claude uses MCP to create workspace, install dependencies, and set up project] +```txt + +**Debugging and troubleshooting**: +```txt +You: "My application in the backend workspace is failing to start. Can you help me debug it?" + +Claude: I'll help you debug the startup issue. Let me: +1. Check the workspace status +1. Examine the application logs +1. Verify the configuration +4. Identify and fix the issue + +[Claude uses MCP to access workspace, check logs, and diagnose the problem] +```txt + +**Code review and optimization**: +```txt +You: "Can you review the code in my frontend workspace and suggest improvements?" + +Claude: I'll review your frontend code and provide suggestions. Let me: +1. Access your workspace and examine the codebase +1. Analyze the code structure and patterns +1. Identify potential improvements +4. Suggest specific optimizations + +[Claude uses MCP to access code and provide detailed review] +```txt + +## Claude Desktop-Specific Features + +### Conversational Development +Claude Desktop's conversational interface combined with Coder MCP enables: +- Natural language interaction with your development environments +- Context-aware responses based on your actual workspace state +- Iterative development conversations that maintain workspace context + +### Multi-Workspace Coordination +Claude can help coordinate work across multiple Coder workspaces: +- Manage microservice architectures spanning multiple workspaces +- Coordinate frontend and backend development +- Handle complex deployment scenarios across environments + +### Documentation and Learning +Use Claude with Coder MCP for: +- Generating documentation based on your actual codebase +- Learning about your specific development setup +- Getting explanations of complex workspace configurations + +## Configuration Options + +### Advanced MCP Settings + +Customize the MCP server behavior for Claude Desktop: + +```json +{ + "mcpServers": { + "coder": { + "command": "coder", + "args": [ + "exp", "mcp", "server", + "--log-level", "info", + "--timeout", "60s" + ], + "env": { + "CODER_MCP_LOG_LEVEL": "info", + "CODER_MCP_TIMEOUT": "60s" + } + } + } +} +```txt + +### Environment Variables + +Set environment variables to customize MCP behavior: + +```bash +# Enable debug logging +export CODER_MCP_LOG_LEVEL=debug + +# Increase timeout for long operations +export CODER_MCP_TIMEOUT=120s + +# Start Claude Desktop with custom environment +open -a "Claude Desktop" +```txt + +## Troubleshooting + +### MCP Server Not Connecting + +1. **Verify Coder CLI authentication**: + ```bash + coder whoami + coder workspaces list + ``` + +1. **Test MCP server manually**: + + ```bash + coder exp mcp server --log-level debug + ``` + +1. **Check Claude Desktop configuration**: + - Verify the configuration file exists and has correct syntax + - Ensure the file path is correct for your operating system + - Check Claude Desktop's logs for MCP-related errors + +### Claude Not Recognizing MCP Tools + +1. **Restart Claude Desktop**: A full restart is often needed after configuration changes +1. **Check MCP server status**: Ensure the MCP server is running and accessible +1. **Verify permissions**: Ensure Claude Desktop has necessary permissions to execute the Coder CLI + +### Performance Issues + +1. **Optimize workspace resources**: Ensure workspaces have adequate resources +1. **Check network connectivity**: Verify stable connection to your Coder deployment +1. **Monitor MCP timeouts**: Adjust timeout settings for long-running operations + +### Authentication Problems + +1. **Re-authenticate with Coder**: + + ```bash + coder login https://coder.example.com + ``` + +1. **Check token expiration**: Verify your Coder authentication token is still valid +1. **Verify permissions**: Ensure your user has appropriate workspace permissions + +## Best Practices + +### Security + +- Keep your Coder CLI credentials secure and up to date +- Use workspace templates with appropriate security configurations +- Regularly review Claude's access to your workspaces +- Enable audit logging for compliance and monitoring +- Implement proper secret management in workspaces + +### Effective AI Interaction + +- Be specific about which workspace you want Claude to work with +- Provide context about your project goals and constraints +- Ask Claude to explain its actions when working with your workspaces +- Use iterative conversations to refine development tasks + +### Development Workflow + +- Create standardized workspace templates for different project types +- Use consistent naming conventions for workspaces and projects +- Establish clear boundaries for what Claude should and shouldn't modify +- Implement version control best practices for AI-assisted changes + +## Advanced Usage + +### Custom Workspace Templates + +Create Coder templates optimized for AI-assisted development: + +```hcl +# Terraform template for AI-assisted development +resource "coder_workspace" "claude_dev" { + name = "claude-development" + + # Optimized for AI development workflows + cpu = 4 + memory = 8192 + + # Pre-install development tools + startup_script = <<-EOF + # Install common development tools + apt-get update && apt-get install -y git curl wget + + # Install language-specific tools + curl -fsSL https://deb.nodesource.com/setup_18.x | bash - + apt-get install -y nodejs + + # Install Python and pip + apt-get install -y python3 python3-pip + + # Set up development environment + echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc + EOF +} +```txt + +### Automated Workflows + +Use Claude with Coder MCP for automated development workflows: + +```bash +# Example: Automated project setup script +#!/bin/bash + +# This script can be executed by Claude through MCP +echo "Setting up new project workspace..." + +# Create workspace +coder create my-project --template web-development + +# Wait for workspace to be ready +coder ssh my-project -- 'echo "Workspace ready"' + +# Initialize project +coder ssh my-project -- 'git init && npm init -y' + +echo "Project setup complete!" +```txt + +### Integration with Development Tools + +Combine Claude Desktop with other development tools: +- Use Claude to generate code that integrates with your existing CI/CD pipelines +- Have Claude help set up monitoring and logging in your Coder workspaces +- Use Claude to generate documentation that reflects your actual workspace setup + +## Next Steps + +- Explore [Coder Templates](https://registry.coder.com) for different development stacks +- Learn about [AI coding best practices](../ai-coder/best-practices.md) with Coder +- Set up [Coder Tasks](../ai-coder/tasks.md) for background AI operations +- Review [security considerations](../ai-coder/security.md) for AI development +- Check out Claude's [advanced features](https://docs.anthropic.com/claude/docs) for development workflows + +## Support + +For Claude Desktop-specific MCP issues: + +1. Check [Claude Desktop documentation](https://docs.anthropic.com/claude/docs/claude-desktop) for MCP support +1. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues +1. [Join our Discord](https://discord.gg/coder) for community support +4. [Report bugs](https://github.com/coder/coder/issues) on the Coder GitHub repository +5. Contact [Anthropic Support](https://support.anthropic.com/) for Claude Desktop-specific issues + +## Additional Resources + +- [Model Context Protocol Documentation](https://modelcontextprotocol.io/) +- [Claude Desktop User Guide](https://docs.anthropic.com/claude/docs/claude-desktop) +- [Coder CLI Reference](../reference/cli/index.md) +- [Workspace Templates Guide](../tutorials/template-from-scratch.md) diff --git a/docs/mcp/cursor.md b/docs/mcp/cursor.md new file mode 100644 index 0000000000000..2b172c1c9e49e --- /dev/null +++ b/docs/mcp/cursor.md @@ -0,0 +1,265 @@ +# Using Coder MCP with Cursor + +This guide shows you how to set up Coder's Model Context Protocol (MCP) server with Cursor, the AI-first code editor. + +## Prerequisites + +- Cursor installed +- Coder CLI installed and authenticated +- Active Coder deployment + +## Setup + +### Automatic Configuration (Recommended) + +The Coder CLI can automatically configure MCP for Cursor: + +```bash +# First, authenticate with your Coder deployment +coder login https://coder.example.com + +# Configure Cursor to use Coder MCP +coder exp mcp configure cursor +```txt + +This command will: +- Locate your Cursor configuration directory +- Add the Coder MCP server to Cursor's MCP configuration +- Set up the necessary authentication + +### Manual Configuration + +If automatic configuration doesn't work, you can manually set up MCP: + +1. **Locate Cursor's MCP configuration file**: + - **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/mcp.json` + - **Windows**: `%APPDATA%\Cursor\User\globalStorage\mcp.json` + - **Linux**: `~/.config/Cursor/User/globalStorage/mcp.json` + +1. **Add Coder MCP server configuration**: + ```json + { + "mcpServers": { + "coder": { + "type": "stdio", + "command": "coder", + "args": ["exp", "mcp", "server"], + "env": {} + } + } + } + ``` + +1. **Restart Cursor** to load the new configuration. + +## Using Coder MCP in Cursor + +Once configured, Cursor's AI can interact with your Coder workspaces through MCP. + +### Available Capabilities + +**Workspace Management**: + +- List all your Coder workspaces +- Create new workspaces from templates +- Start, stop, and delete workspaces +- Check workspace status and resource usage + +**Command Execution**: + +- Run commands in any workspace +- Execute build scripts and tests +- Install dependencies and packages +- Manage development processes + +**Environment Interaction**: + +- Access workspace file systems +- Monitor running processes +- Check environment variables and configuration + +### Example Interactions + +**Creating a development environment**: + +```txt +You: "I need a new React workspace for my frontend project" +Cursor AI: Creates a new Coder workspace using a React template, installs dependencies, and sets up the development environment +```txt + +**Running tests across workspaces**: +```txt +You: "Run the test suite in my backend workspace" +Cursor AI: Connects to your backend workspace via MCP and executes the test commands, showing results +```txt + +**Managing multiple environments**: +```txt +You: "Show me the status of all my workspaces and start the ones that are stopped" +Cursor AI: Lists workspace statuses and starts any stopped workspaces +```txt + +## Cursor-Specific Features + +### AI Chat Integration +Cursor's AI chat can now reference and interact with your Coder workspaces: +- Ask questions about workspace configurations +- Get help with environment-specific issues +- Receive suggestions based on your actual development setup + +### Code Context Enhancement +With MCP, Cursor can: +- Access live code from your Coder workspaces +- Understand your actual development environment +- Provide more accurate suggestions and completions + +### Multi-Workspace Development +Cursor can help manage complex projects spanning multiple Coder workspaces: +- Coordinate changes across frontend and backend workspaces +- Manage microservice deployments +- Handle cross-workspace dependencies + +## Configuration Options + +### Custom MCP Server Settings + +You can customize the MCP server behavior in your configuration: + +```json +{ + "mcpServers": { + "coder": { + "type": "stdio", + "command": "coder", + "args": [ + "exp", "mcp", "server", + "--log-level", "debug", + "--timeout", "60s" + ], + "env": { + "CODER_MCP_LOG_LEVEL": "debug" + } + } + } +} +```txt + +### Environment Variables + +Set environment variables to customize MCP behavior: + +```bash +# Set log level for debugging +export CODER_MCP_LOG_LEVEL=debug + +# Increase timeout for long-running operations +export CODER_MCP_TIMEOUT=120s +```txt + +## Troubleshooting + +### MCP Server Not Connecting + +1. **Check Coder CLI authentication**: + ```bash + coder whoami + ``` + +1. **Test MCP server manually**: + + ```bash + coder exp mcp server --help + ``` + +1. **Verify Cursor configuration**: + - Check that the MCP configuration file exists + - Ensure the file has correct JSON syntax + - Restart Cursor after making changes + +### Cursor AI Not Recognizing MCP + +1. **Check Cursor version**: Ensure you're using a version that supports MCP +1. **Restart Cursor**: Sometimes a full restart is needed +1. **Check Cursor logs**: Look for MCP-related errors in Cursor's developer console + +### Permission Issues + +1. **Verify Coder permissions**: Ensure your user can create and manage workspaces +1. **Check authentication**: Re-authenticate if needed: + + ```bash + coder login https://coder.example.com + ``` + +### Performance Issues + +1. **Optimize workspace templates**: Use lightweight templates for faster startup +1. **Monitor resource usage**: Check workspace CPU and memory allocation +1. **Adjust MCP timeout**: Increase timeout for slow operations + +## Best Practices + +### Security + +- Keep your Coder CLI credentials secure +- Use workspace templates with appropriate security configurations +- Regularly review AI assistant access patterns +- Enable audit logging for compliance requirements + +### Performance + +- Use Coder workspace templates optimized for your development stack +- Consider workspace resource allocation based on AI workload requirements +- Implement workspace auto-stop policies to manage costs + +### Development Workflow + +- Create project-specific workspace templates +- Use consistent naming conventions for workspaces +- Leverage Coder's collaboration features for team development +- Set up automated workspace provisioning for common project types + +## Advanced Usage + +### Custom Workspace Templates + +Create Coder templates optimized for AI-assisted development: + +```hcl +# Example Terraform template for AI development +resource "coder_workspace" "dev" { + # AI-optimized configuration + cpu = 4 + memory = 8192 + + # Pre-install AI development tools + startup_script = <<-EOF + # Install AI development dependencies + pip install openai anthropic + npm install -g @cursor/cli + EOF +} +```txt + +### Integration with CI/CD + +Use Cursor + Coder MCP for automated development workflows: +- AI-assisted code review in Coder workspaces +- Automated testing and deployment through MCP +- Intelligent environment provisioning based on project needs + +## Next Steps + +- Explore [Coder Templates](https://registry.coder.com) for AI development +- Learn about [AI coding best practices](../ai-coder/best-practices.md) +- Set up [Coder Tasks](../ai-coder/tasks.md) for background AI operations +- Review [security considerations](../ai-coder/security.md) for AI development + +## Support + +For Cursor-specific MCP issues: + +1. Check [Cursor's MCP documentation](https://docs.cursor.com/mcp) (when available) +1. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues +1. [Join our Discord](https://discord.gg/coder) for community support +4. [Report bugs](https://github.com/coder/coder/issues) on GitHub diff --git a/docs/mcp/index.md b/docs/mcp/index.md new file mode 100644 index 0000000000000..f6947e7e0c8ec --- /dev/null +++ b/docs/mcp/index.md @@ -0,0 +1,130 @@ +# Model Context Protocol (MCP) with Coder + +The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. Coder provides a comprehensive MCP server that allows AI agents to interact with your development environments, workspaces, and infrastructure. + +## What is Coder MCP? + +Coder MCP is a server implementation that exposes Coder's functionality through the Model Context Protocol, enabling AI assistants to: + +- **Manage Workspaces**: List, create, start, stop, and delete development workspaces +- **Execute Commands**: Run commands directly in your Coder workspaces +- **Monitor Activity**: Check on agent activity and workspace status +- **Access Resources**: Interact with your cloud development environments securely + +## Benefits of Using Coder MCP + +### Secure Remote Development + +- Keep your code and secrets in controlled, isolated environments +- Leverage powerful cloud resources without local machine limitations +- Maintain consistent development environments across your team + +### Enhanced AI Productivity + +- AI agents can directly interact with your actual development environment +- No need to copy code or context - agents work with live workspaces +- Seamless integration with existing Coder infrastructure + +### Enterprise-Ready + +- Built on Coder's enterprise-grade security and compliance features +- Fine-grained access controls and audit logging +- Self-hosted solution that keeps your data in your infrastructure + +## How It Works + +Coder MCP acts as a bridge between AI assistants and your Coder deployment: + +1. **AI Assistant** connects to Coder MCP server +2. **MCP Server** authenticates and authorizes requests +3. **Coder API** executes operations on workspaces and infrastructure +4. **Results** are returned to the AI assistant for further processing + +```mermaid +graph LR + A[AI Assistant] --> B[Coder MCP Server] + B --> C[Coder API] + C --> D[Workspaces] + C --> E[Infrastructure] +```txt + +## Supported AI Tools and IDEs + +Coder MCP works with various AI assistants and development environments: + +- **[VSCode](./vscode.md)** - Microsoft Visual Studio Code with AI extensions +- **[Cursor](./cursor.md)** - AI-first code editor +- **[Zed](./zed.md)** - High-performance collaborative code editor +- **[WindSurf](./windsurf.md)** - AI-powered development environment +- **[Claude Desktop](./claude-desktop.md)** - Anthropic's desktop AI assistant +- **[Web-based Agents](./web-agents.md)** - Browser-based AI assistants like claude.ai + +## Getting Started + +### Prerequisites + +- A running Coder deployment +- Coder CLI installed and authenticated +- An AI assistant or IDE that supports MCP + +### Quick Setup + +1. **Configure your AI tool**: Choose your preferred AI assistant or IDE from the list above +2. **Set up MCP connection**: Follow the specific guide for your chosen tool +3. **Start coding**: Your AI assistant can now interact with your Coder workspaces + +### Local MCP Server + +For local development and testing: + +```bash +# Authenticate with your Coder deployment +coder login https://coder.example.com + +# Start the MCP server +coder exp mcp server +```txt + +### Remote MCP Server + +For web-based AI assistants, enable the HTTP MCP server: + +```bash +# Enable experimental features +CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server +```txt + +The MCP server will be available at: +```txt +https://coder.example.com/api/experimental/mcp/http +```txt + +## Security and Authentication + +Coder MCP inherits Coder's robust security model: + +- **OAuth2 Authentication**: Secure token-based authentication for web agents +- **CLI Authentication**: Uses your existing Coder CLI credentials for local tools +- **Role-Based Access**: Respects your Coder RBAC permissions +- **Audit Logging**: All MCP operations are logged for compliance + +> **Note**: The MCP server operates with the same permissions as the authenticated user. Fine-grained MCP-specific permissions are in development. + +## 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/codersdk/toolsdk#pkg-variables) for the complete list of available tools. + +## Next Steps + +- Choose your preferred AI tool and follow its setup guide +- Explore the [best practices](../ai-coder/best-practices.md) for AI coding with Coder +- Learn about [security considerations](../ai-coder/security.md) when using AI agents +- Check out [Coder Tasks](../ai-coder/tasks.md) for background AI agent execution + +## Support and Feedback + +Coder MCP is currently in beta. For questions, issues, or feature requests: + +- [Contact Coder Support](https://coder.com/contact) +- [Join our Discord Community](https://discord.gg/coder) +- [Report Issues on GitHub](https://github.com/coder/coder/issues) diff --git a/docs/mcp/vscode.md b/docs/mcp/vscode.md new file mode 100644 index 0000000000000..0e0d9d81223b5 --- /dev/null +++ b/docs/mcp/vscode.md @@ -0,0 +1,190 @@ +# Using Coder MCP with Visual Studio Code + +This guide shows you how to set up Coder's Model Context Protocol (MCP) server with Visual Studio Code and AI extensions like GitHub Copilot, Codeium, or other AI assistants. + +## Prerequisites + +- Visual Studio Code installed +- Coder CLI installed and authenticated +- An AI extension that supports MCP (varies by extension) + +## Setup Methods + +### Method 1: Automatic Configuration (Recommended) + +The Coder CLI can automatically configure MCP for supported VS Code extensions: + +```bash +# First, authenticate with your Coder deployment +coder login https://coder.example.com + +# Configure MCP for VS Code (when supported) +coder exp mcp configure vscode +```txt + +> **Note**: Automatic configuration support varies by AI extension. Check with your specific AI extension's documentation for MCP support. + +### Method 2: Manual Configuration + +For extensions that support custom MCP servers, you can manually configure the connection: + +1. **Start the Coder MCP server**: + ```bash + coder exp mcp server + ``` + + The server will start on `stdio` by default and display connection details. + +1. **Configure your AI extension**: + - Open VS Code settings (Ctrl/Cmd + ,) + - Search for your AI extension's MCP settings + - Add the Coder MCP server configuration + +### Method 3: Using VS Code Settings + +Some AI extensions allow MCP configuration through VS Code's settings.json: + +```json +{ + "your-ai-extension.mcpServers": { + "coder": { + "command": "coder", + "args": ["exp", "mcp", "server"], + "env": {} + } + } +} +```txt + +## Supported AI Extensions + +### GitHub Copilot +GitHub Copilot's MCP support is evolving. Check the [GitHub Copilot documentation](https://docs.github.com/en/copilot) for the latest MCP integration options. + +### Codeium +Codeium may support MCP through their VS Code extension. Refer to [Codeium's documentation](https://codeium.com/vscode_tutorial) for MCP setup instructions. + +### Continue.dev +Continue.dev has experimental MCP support. See their [MCP documentation](https://docs.continue.dev/walkthroughs/mcp) for setup details. + +## Using Coder MCP in VS Code + +Once configured, your AI assistant can interact with Coder through MCP: + +### Available Commands + +- **List workspaces**: View all your Coder workspaces +- **Create workspace**: Create new development environments +- **Start/Stop workspaces**: Manage workspace lifecycle +- **Execute commands**: Run commands in your workspaces +- **Check status**: Monitor workspace and agent activity + +### Example Interactions + +**Creating a new workspace**: +```txt +User: "Create a new Python workspace for my machine learning project" +AI: Uses Coder MCP to create a workspace with Python and ML tools +```txt + +**Running commands**: +```txt +User: "Run the tests in my backend workspace" +AI: Executes test commands in the specified Coder workspace +```txt + +**Checking workspace status**: +```txt +User: "What's the status of my workspaces?" +AI: Lists all workspaces with their current state and resource usage +```txt + +## Troubleshooting + +### MCP Server Not Starting + +1. **Check Coder CLI authentication**: + ```bash + coder whoami + ``` + +1. **Verify MCP server manually**: + + ```bash + coder exp mcp server --help + ``` + +2. **Check VS Code extension logs**: + - Open VS Code Developer Tools (Help > Toggle Developer Tools) + - Check the Console for MCP-related errors + +### AI Extension Not Connecting + +1. **Verify MCP support**: Ensure your AI extension supports MCP +2. **Check configuration**: Review your extension's MCP settings +3. **Restart VS Code**: Sometimes a restart is needed after configuration changes + +### Permission Issues + +1. **Check Coder permissions**: Ensure your user has appropriate workspace permissions +1. **Verify authentication**: Re-authenticate with Coder if needed: + + ```bash + coder login https://coder.example.com + ``` + +## Best Practices + +### Security + +- Keep your Coder CLI credentials secure +- Regularly rotate authentication tokens +- Review AI assistant permissions and access patterns + +### Performance + +- Use workspace templates optimized for AI development +- Consider workspace resource allocation for AI workloads +- Monitor workspace usage and costs + +### Development Workflow + +- Create dedicated workspaces for different projects +- Use Coder's workspace templates for consistent environments +- Leverage Coder's collaboration features for team AI development + +## Advanced Configuration + +### Custom MCP Server Options + +You can customize the MCP server behavior: + +```bash +# Start MCP server with custom options +coder exp mcp server --log-level debug --timeout 30s +```txt + +### Environment Variables + +Configure MCP behavior through environment variables: + +```bash +export CODER_MCP_LOG_LEVEL=debug +export CODER_MCP_TIMEOUT=60s +coder exp mcp server +```txt + +## Next Steps + +- Explore [Coder Templates](https://registry.coder.com) optimized for AI development +- Learn about [AI coding best practices](../ai-coder/best-practices.md) with Coder +- Set up [Coder Tasks](../ai-coder/tasks.md) for background AI agent execution +- Review [security considerations](../ai-coder/security.md) for AI development + +## Support + +For VS Code-specific MCP issues: + +1. Check your AI extension's documentation for MCP support +1. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues +2. [Report bugs](https://github.com/coder/coder/issues) on the Coder GitHub repository diff --git a/docs/mcp/web-agents.md b/docs/mcp/web-agents.md new file mode 100644 index 0000000000000..946bbcba0bca6 --- /dev/null +++ b/docs/mcp/web-agents.md @@ -0,0 +1,344 @@ +# Using Coder MCP with Web-Based AI Agents + +This guide shows you how to set up Coder's Model Context Protocol (MCP) server with web-based AI agents like claude.ai, ChatGPT, and other browser-based AI assistants. + +## Prerequisites + +- A running Coder deployment with experimental features enabled +- Coder CLI installed and authenticated +- A web browser with access to AI assistant platforms + +## Setup + +### Enable HTTP MCP Server + +Web-based AI agents require the HTTP MCP server, which is currently experimental: + +```bash +# Enable experimental features on your Coder server +CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server + +# Or using CLI flags +coder server --experiments=oauth2,mcp-server-http +```txt + +### Access the MCP Server + +Once enabled, the HTTP MCP server will be available at: + +```txt +https://your-coder-deployment.com/api/experimental/mcp/http +```txt + +### Authentication Setup + +Web-based agents authenticate using OAuth2: + +1. **Navigate to your Coder deployment's OAuth2 settings** +1. **Create a new OAuth2 application** for your AI agent +2. **Configure the redirect URI** based on your AI agent's requirements +4. **Note the client ID and client secret** for configuration + +## Supported Web-Based AI Agents + +### Claude.ai (Anthropic) + +Claude.ai supports MCP through its web interface: + +1. **Open claude.ai** in your browser +1. **Go to Settings** > **Integrations** > **MCP Servers** +2. **Add a new MCP server**: + - **Name**: Coder + - **URL**: `https://your-coder-deployment.com/api/experimental/mcp/http` + - **Authentication**: OAuth2 +4. **Complete OAuth2 authentication** when prompted + +### ChatGPT (OpenAI) + +> **Note**: ChatGPT's MCP support is limited and may not be compatible with the HTTP MCP server at this time. + +For ChatGPT integration: +1. Check OpenAI's documentation for current MCP support +1. Use custom GPTs with API integrations as an alternative +2. Consider using the OpenAI API with local MCP tools + +### Other Web-Based Agents + +For other web-based AI agents that support MCP: + +1. **Check the agent's MCP documentation** for setup instructions +1. **Use the HTTP MCP endpoint**: `https://your-coder-deployment.com/api/experimental/mcp/http` +2. **Configure OAuth2 authentication** using your Coder deployment's OAuth2 settings + +## Using Coder MCP with Web Agents + +Once configured, web-based AI agents can interact with your Coder workspaces through the HTTP MCP server. + +### Available Capabilities + +**Workspace Operations**: +- List and filter your Coder workspaces +- Create new workspaces from templates +- Start, stop, and manage workspace lifecycle +- Monitor workspace status and resource usage + +**Remote Command Execution**: +- Execute commands in any accessible workspace +- Run build scripts, tests, and deployment commands +- Install packages and manage dependencies +- Access workspace file systems and configurations + +**Development Assistance**: +- Analyze code in your actual development environments +- Generate code that works with your specific setup +- Debug issues using live workspace context +- Provide infrastructure-aware recommendations + +### Example Interactions + +**Project initialization**: +```txt +You: "I need to create a new React workspace and set up a modern web application with TypeScript and Tailwind CSS." + +AI Agent: I'll help you create a new Coder workspace and set up your React application. Let me: +1. Create a new workspace using a Node.js template +1. Initialize a new React project with TypeScript +2. Install and configure Tailwind CSS +4. Set up the basic project structure + +[Agent uses HTTP MCP to create workspace and execute setup commands] +```txt + +**Cross-workspace development**: +```txt +You: "Deploy my frontend changes to staging and update the backend API documentation to reflect the new endpoints." + +AI Agent: I'll coordinate the deployment across your workspaces: +1. Build and deploy frontend changes from your frontend workspace +1. Update API documentation in your backend workspace +2. Verify the deployment is successful +4. Run integration tests to ensure everything works together + +[Agent uses HTTP MCP to coordinate across multiple workspaces] +```txt + +**Infrastructure management**: +```txt +You: "Check the status of all my workspaces and optimize resource allocation." + +AI Agent: I'll analyze your workspace usage and optimize resources: +1. List all workspaces with their current status +1. Check resource utilization (CPU, memory, storage) +2. Identify underutilized or overloaded workspaces +4. Suggest resource optimization strategies + +[Agent uses HTTP MCP to gather workspace metrics and provide recommendations] +```txt + +## Configuration Options + +### OAuth2 Configuration + +Configure OAuth2 settings for web agent authentication: + +```yaml +# Example OAuth2 configuration +oauth2: + github: + client_id: "your-client-id" + client_secret: "your-client-secret" + redirect_url: "https://your-coder-deployment.com/api/v2/oauth2/github/callback" + scopes: + - "read:user" + - "user:email" +```txt + +### HTTP MCP Server Settings + +Customize the HTTP MCP server behavior: + +```bash +# Environment variables for HTTP MCP server +export CODER_MCP_HTTP_TIMEOUT=120s +export CODER_MCP_HTTP_MAX_REQUESTS=100 +export CODER_MCP_HTTP_RATE_LIMIT=10 + +# Start server with custom settings +CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server +```txt + +### CORS Configuration + +Configure CORS for web agent access: + +```bash +# Allow specific origins for web agents +export CODER_ACCESS_URL="https://your-coder-deployment.com" +export CODER_WILDCARD_ACCESS_URL="*.your-domain.com" +```txt + +## Security Considerations + +### Authentication and Authorization + +- **OAuth2 Security**: Use strong client secrets and secure redirect URIs +- **Token Management**: Implement proper token rotation and expiration +- **Scope Limitation**: Grant minimal necessary permissions to AI agents +- **Audit Logging**: Enable comprehensive logging for all MCP operations + +### Network Security + +- **HTTPS Only**: Ensure all MCP communication uses HTTPS +- **Firewall Rules**: Restrict access to the MCP endpoint as needed +- **Rate Limiting**: Implement rate limiting to prevent abuse +- **IP Allowlisting**: Consider restricting access to known AI agent IPs + +### Data Protection + +- **Sensitive Data**: Be cautious about exposing sensitive workspace data +- **Access Controls**: Use Coder's RBAC to limit workspace access +- **Data Retention**: Understand how AI agents handle and store data +- **Compliance**: Ensure setup meets your organization's compliance requirements + +## Troubleshooting + +### HTTP MCP Server Not Starting + +1. **Check experimental features**: + ```bash + coder server --help | grep experiments + ``` + +1. **Verify server configuration**: + + ```bash + curl -I https://your-coder-deployment.com/api/experimental/mcp/http + ``` + +2. **Check server logs** for MCP-related errors + +### OAuth2 Authentication Issues + +1. **Verify OAuth2 configuration**: + - Check client ID and secret + - Verify redirect URIs + - Ensure proper scopes are configured + +1. **Test OAuth2 flow manually**: + + ```bash + curl -X POST https://your-coder-deployment.com/api/v2/oauth2/authorize + ``` + +### Web Agent Connection Problems + +1. **Check CORS settings**: Ensure the web agent's domain is allowed +2. **Verify network connectivity**: Test access to the MCP endpoint +3. **Review browser console**: Check for JavaScript errors or network issues +4. **Test with curl**: Verify the endpoint is accessible: + + ```bash + curl -H "Authorization: Bearer your-token" \ + https://your-coder-deployment.com/api/experimental/mcp/http + ``` + +### Performance Issues + +1. **Monitor server resources**: Check CPU, memory, and network usage +2. **Optimize workspace allocation**: Ensure adequate resources for workspaces +3. **Implement caching**: Use appropriate caching strategies for MCP responses +4. **Rate limiting**: Adjust rate limits based on usage patterns + +## Best Practices + +### Security + +- Regularly rotate OAuth2 credentials +- Monitor and audit AI agent access patterns +- Implement proper secret management +- Use least-privilege access principles +- Keep Coder deployment and dependencies updated + +### Performance + +- Monitor MCP server performance and resource usage +- Implement appropriate rate limiting and throttling +- Use efficient workspace templates +- Consider geographic distribution for global teams + +### Operational + +- Document AI agent configurations and access patterns +- Implement monitoring and alerting for MCP operations +- Establish incident response procedures +- Regular backup and disaster recovery testing + +## Advanced Usage + +### Custom Web Agent Integration + +For custom web applications that need MCP integration: + +```javascript +// Example JavaScript integration +const mcpClient = { + baseUrl: 'https://your-coder-deployment.com/api/experimental/mcp/http', + token: 'your-oauth2-token', + + async listWorkspaces() { + const response = await fetch(`${this.baseUrl}/workspaces`, { + headers: { + 'Authorization': `Bearer ${this.token}`, + 'Content-Type': 'application/json' + } + }); + return response.json(); + }, + + async executeCommand(workspaceId, command) { + const response = await fetch(`${this.baseUrl}/workspaces/${workspaceId}/execute`, { + method: 'POST', + headers: { + 'Authorization': `Bearer ${this.token}`, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ command }) + }); + return response.json(); + } +}; +```txt + +### Enterprise Integration + +For enterprise deployments: + +- Integrate with existing SSO providers +- Implement custom authentication flows +- Set up monitoring and compliance reporting +- Configure high availability and load balancing + +## Next Steps + +- Explore [Coder Templates](https://registry.coder.com) for web development +- 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) + +## Support + +For web agent MCP issues: + +1. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues +1. [Join our Discord](https://discord.gg/coder) for community support +2. [Report bugs](https://github.com/coder/coder/issues) on GitHub +4. Check your AI agent's documentation for platform-specific MCP support +5. Review the [Model Context Protocol specification](https://modelcontextprotocol.io/) + +## Additional Resources + +- [Model Context Protocol Documentation](https://modelcontextprotocol.io/) +- [Coder OAuth2 Provider Guide](../admin/integrations/oauth2-provider.md) +- [Coder API Documentation](../reference/api/index.md) +- [Web Security Best Practices](../admin/security/index.md) diff --git a/docs/mcp/windsurf.md b/docs/mcp/windsurf.md new file mode 100644 index 0000000000000..b9ad79f38382e --- /dev/null +++ b/docs/mcp/windsurf.md @@ -0,0 +1,316 @@ +# Using Coder MCP with WindSurf + +This guide shows you how to set up Coder's Model Context Protocol (MCP) server with WindSurf, the AI-powered development environment. + +## Prerequisites + +- WindSurf installed +- Coder CLI installed and authenticated +- Active Coder deployment + +## Setup + +### Automatic Configuration (Recommended) + +The Coder CLI can automatically configure MCP for WindSurf: + +```bash +# First, authenticate with your Coder deployment +coder login https://coder.example.com + +# Configure WindSurf to use Coder MCP +coder exp mcp configure windsurf +```txt + +This command will: +- Locate your WindSurf configuration directory +- Add the Coder MCP server to WindSurf's MCP settings +- Set up the necessary authentication + +### Manual Configuration + +If automatic configuration doesn't work, you can manually set up MCP: + +1. **Locate WindSurf's MCP configuration**: + - **macOS**: `~/Library/Application Support/WindSurf/User/globalStorage/mcp.json` + - **Windows**: `%APPDATA%\WindSurf\User\globalStorage\mcp.json` + - **Linux**: `~/.config/WindSurf/User/globalStorage/mcp.json` + +1. **Add Coder MCP server configuration**: + ```json + { + "mcpServers": { + "coder": { + "type": "stdio", + "command": "coder", + "args": ["exp", "mcp", "server"], + "env": {} + } + } + } + ``` + +1. **Restart WindSurf** to load the new configuration. + +## Using Coder MCP in WindSurf + +Once configured, WindSurf's AI can interact with your Coder workspaces through MCP, enhancing its already powerful AI capabilities. + +### Available Capabilities + +**Workspace Management**: + +- List and organize your Coder workspaces +- Create new workspaces from templates +- Start, stop, and manage workspace lifecycle +- Monitor workspace status and resource utilization + +**AI-Enhanced Development**: + +- Execute commands in remote Coder workspaces +- Run AI-assisted code generation in cloud environments +- Perform automated testing and deployment +- Access powerful cloud resources for AI workloads + +**Environment Integration**: + +- Access workspace file systems and configurations +- Manage environment variables and secrets +- Monitor running processes and services +- Integrate with Coder's security and compliance features + +### Example Interactions + +**AI-powered project setup**: + +```txt +You: "Create a new Next.js workspace with TypeScript and set up a modern web app structure" +WindSurf AI: Creates a Coder workspace, installs Next.js with TypeScript, sets up project structure, and configures development environment +```txt + +**Intelligent code generation**: +```txt +You: "Generate a REST API for user management in my backend workspace" +WindSurf AI: Connects to your backend workspace, analyzes existing code, and generates API endpoints with proper error handling and validation +```txt + +**Cross-workspace development**: +```txt +You: "Deploy my frontend changes and update the backend API to match" +WindSurf AI: Coordinates changes across multiple Coder workspaces, ensuring consistency between frontend and backend +```txt + +## WindSurf-Specific Features + +### Enhanced AI Context +With Coder MCP, WindSurf's AI gains access to: +- Live code from your actual development environments +- Real-time workspace status and configuration +- Actual project dependencies and environment setup +- Historical workspace usage patterns + +### Cloud-Powered AI Development +Combining WindSurf's AI with Coder's cloud infrastructure: +- Run AI workloads on powerful cloud resources +- Scale development environments based on AI processing needs +- Access GPU-enabled workspaces for machine learning projects +- Leverage enterprise-grade security for AI development + +### Collaborative AI Development +WindSurf + Coder enables: +- Team collaboration on AI-assisted projects +- Shared workspace templates for consistent AI development +- Centralized management of AI development environments +- Audit trails for AI-generated code and changes + +## Configuration Options + +### Advanced MCP Settings + +Customize the MCP server for optimal WindSurf integration: + +```json +{ + "mcpServers": { + "coder": { + "type": "stdio", + "command": "coder", + "args": [ + "exp", "mcp", "server", + "--log-level", "info", + "--timeout", "60s" + ], + "env": { + "CODER_MCP_LOG_LEVEL": "info", + "CODER_MCP_TIMEOUT": "60s" + } + } + } +} +```txt + +### Environment Variables + +Optimize MCP for AI workloads: + +```bash +# Enable detailed logging for AI operations +export CODER_MCP_LOG_LEVEL=debug + +# Increase timeout for long-running AI tasks +export CODER_MCP_TIMEOUT=300s + +# Set custom workspace preferences +export CODER_MCP_DEFAULT_TEMPLATE=ai-development +```txt + +## Troubleshooting + +### MCP Server Connection Issues + +1. **Verify Coder CLI setup**: + ```bash + coder version + coder whoami + coder workspaces list + ``` + +1. **Test MCP server independently**: + + ```bash + coder exp mcp server --log-level debug + ``` + +1. **Check WindSurf configuration**: + - Verify MCP configuration file syntax + - Ensure WindSurf has necessary permissions + - Check WindSurf's developer console for errors + +### AI Performance Issues + +1. **Optimize workspace resources**: + - Ensure adequate CPU and memory for AI workloads + - Consider GPU-enabled workspaces for ML tasks + - Monitor workspace resource utilization + +1. **Network optimization**: + - Check network latency to Coder deployment + - Ensure stable internet connection + - Consider workspace location relative to your location + +### WindSurf AI Not Using MCP + +1. **Verify MCP integration**: Ensure WindSurf recognizes the MCP server +1. **Check AI model settings**: Some AI models may need explicit MCP enablement +1. **Restart WindSurf**: Full restart may be needed after configuration changes + +## Best Practices + +### Security + +- Secure Coder CLI credentials and authentication tokens +- Use workspace templates with appropriate security configurations +- Regularly audit AI assistant access to sensitive workspaces +- Enable comprehensive audit logging for compliance +- Implement proper secret management in workspaces + +### Performance + +- Use workspace templates optimized for AI development +- Allocate appropriate resources based on AI workload requirements +- Implement intelligent workspace auto-stop policies +- Monitor and optimize MCP timeout settings for AI operations +- Consider workspace caching strategies for frequently used environments + +### AI Development Workflow + +- Create specialized workspace templates for different AI use cases +- Use consistent naming conventions for AI projects and workspaces +- Implement version control best practices for AI-generated code +- Set up automated testing for AI-generated components +- Establish code review processes for AI-assisted development + +## Advanced Usage + +### AI-Optimized Workspace Templates + +Create Coder templates specifically for AI development with WindSurf: + +```hcl +# Terraform template for AI development +resource "coder_workspace" "ai_dev" { + name = "windsurf-ai-development" + + # High-performance configuration for AI workloads + cpu = 8 + memory = 16384 + + # GPU support for ML workloads + gpu_enabled = true + gpu_type = "nvidia-t4" + + # Pre-install AI development stack + startup_script = <<-EOF + # Install AI/ML frameworks + pip install torch tensorflow transformers + pip install openai anthropic langchain + + # Install development tools + npm install -g typescript @types/node + + # Set up Jupyter for experimentation + pip install jupyter jupyterlab + EOF +} +```txt + +### Integration with AI Workflows + +Set up automated AI development workflows: + +```bash +# Example: Automated model training workflow +#!/bin/bash + +# Create workspace for training +coder create ml-training --template ai-gpu + +# Start training job +coder ssh ml-training -- python train_model.py + +# Monitor training progress +coder ssh ml-training -- tensorboard --logdir ./logs +```txt + +### Team AI Development + +Implement team-wide AI development practices: +- Share AI-optimized workspace templates +- Establish common AI development environments +- Implement collaborative model development workflows +- Set up centralized model and dataset management + +## Next Steps + +- Explore [AI-optimized Coder Templates](https://registry.coder.com) for machine learning +- Learn about [AI coding best practices](../ai-coder/best-practices.md) with Coder +- Set up [Coder Tasks](../ai-coder/tasks.md) for background AI model training +- Review [security considerations](../ai-coder/security.md) for AI development +- Check out WindSurf's [AI features documentation](https://windsurf.ai/docs) for advanced usage + +## Support + +For WindSurf-specific MCP issues: + +1. Check [WindSurf's documentation](https://windsurf.ai/docs) for MCP support details +1. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues +1. [Join our Discord](https://discord.gg/coder) for community support and AI development discussions +4. [Report bugs](https://github.com/coder/coder/issues) on the Coder GitHub repository +5. Check WindSurf's support channels for WindSurf-specific issues + +## Additional Resources + +- [WindSurf AI Development Guide](https://windsurf.ai/docs/ai-development) +- [Coder AI Templates](https://registry.coder.com/templates?category=ai) +- [MCP Protocol Specification](https://modelcontextprotocol.io/) +- [AI Development Best Practices](../ai-coder/best-practices.md) diff --git a/docs/mcp/zed.md b/docs/mcp/zed.md new file mode 100644 index 0000000000000..7e79a2fc7602f --- /dev/null +++ b/docs/mcp/zed.md @@ -0,0 +1,300 @@ +# Using Coder MCP with Zed + +This guide shows you how to set up Coder's Model Context Protocol (MCP) server with Zed, the high-performance collaborative code editor. + +## Prerequisites + +- Zed installed +- Coder CLI installed and authenticated +- Active Coder deployment + +## Setup + +### Automatic Configuration (Recommended) + +The Coder CLI can automatically configure MCP for Zed: + +```bash +# First, authenticate with your Coder deployment +coder login https://coder.example.com + +# Configure Zed to use Coder MCP +coder exp mcp configure zed +```txt + +This command will: +- Locate your Zed configuration directory +- Add the Coder MCP server to Zed's settings +- Configure the necessary authentication + +### Manual Configuration + +If automatic configuration doesn't work, you can manually set up MCP: + +1. **Open Zed settings**: + - Press `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows) + - Or go to `Zed > Settings` in the menu + +1. **Add MCP server configuration**: + ```json + { + "experimental": { + "mcp": { + "servers": { + "coder": { + "command": "coder", + "args": ["exp", "mcp", "server"], + "env": {} + } + } + } + } + } + ``` + +1. **Save settings** and restart Zed. + +### Alternative: Configuration File + +You can also edit Zed's configuration file directly: + +- **macOS**: `~/Library/Application Support/Zed/settings.json` +- **Linux**: `~/.config/zed/settings.json` +- **Windows**: `%APPDATA%\Zed\settings.json` + +## Using Coder MCP in Zed + +Once configured, Zed's AI assistant can interact with your Coder workspaces through MCP. + +### Available Capabilities + +**Workspace Operations**: + +- List and filter your Coder workspaces +- Create workspaces from templates +- Start, stop, and manage workspace lifecycle +- Monitor workspace resource usage and status + +**Development Commands**: + +- Execute commands in remote workspaces +- Run build scripts, tests, and deployment commands +- Install packages and manage dependencies +- Access workspace terminals and processes + +**Environment Management**: + +- Access workspace file systems and configurations +- Monitor running services and applications +- Manage environment variables and secrets + +### Example Interactions + +**Setting up a new project**: + +```txt +You: "Create a Rust workspace for my new CLI tool project" +Zed AI: Creates a Coder workspace with Rust toolchain, sets up cargo project structure, and configures development environment +```txt + +**Running development tasks**: +```txt +You: "Build and test my application in the backend workspace" +Zed AI: Executes cargo build and cargo test in your specified Coder workspace, showing output and results +```txt + +**Managing multiple environments**: +```txt +You: "Check which workspaces are running and their resource usage" +Zed AI: Lists all workspaces with their status, CPU, memory usage, and uptime +```txt + +## Zed-Specific Features + +### AI Assistant Integration +Zed's AI assistant can now: +- Reference live code from your Coder workspaces +- Understand your actual development environment setup +- Provide context-aware suggestions based on your workspace configuration + +### Collaborative Development +With Zed's collaboration features and Coder MCP: +- Share Coder workspaces with team members through Zed +- Collaborate on code in remote development environments +- Coordinate development across multiple workspaces + +### Performance Optimization +Zed's high-performance architecture combined with Coder: +- Fast interaction with remote workspaces +- Efficient handling of large codebases in Coder environments +- Optimized AI responses using live workspace context + +## Configuration Options + +### Advanced MCP Settings + +Customize the MCP server behavior: + +```json +{ + "experimental": { + "mcp": { + "servers": { + "coder": { + "command": "coder", + "args": [ + "exp", "mcp", "server", + "--log-level", "info", + "--timeout", "30s" + ], + "env": { + "CODER_MCP_LOG_LEVEL": "info", + "CODER_MCP_TIMEOUT": "30s" + } + } + } + } + } +} +```txt + +### Environment Variables + +Configure MCP behavior through environment variables: + +```bash +# Enable debug logging +export CODER_MCP_LOG_LEVEL=debug + +# Set custom timeout +export CODER_MCP_TIMEOUT=60s + +# Start Zed with custom environment +zed +```txt + +## Troubleshooting + +### MCP Server Not Starting + +1. **Verify Coder CLI installation**: + ```bash + coder version + coder whoami + ``` + +1. **Test MCP server manually**: + + ```bash + coder exp mcp server --help + ``` + +1. **Check Zed configuration**: + - Ensure JSON syntax is correct in settings + - Verify the MCP configuration is in the right location + - Check Zed's developer console for errors + +### Zed Not Recognizing MCP + +1. **Check Zed version**: Ensure you're using a version with MCP support +1. **Verify experimental features**: Make sure MCP is enabled in experimental settings +1. **Restart Zed**: A full restart may be needed after configuration changes + +### Connection Issues + +1. **Check network connectivity**: Ensure you can reach your Coder deployment +1. **Verify authentication**: Re-authenticate with Coder: + + ```bash + coder login https://coder.example.com + ``` + +1. **Check firewall settings**: Ensure MCP traffic isn't blocked + +### Performance Issues + +1. **Optimize workspace resources**: Ensure adequate CPU and memory allocation +1. **Check network latency**: High latency can affect MCP performance +1. **Monitor workspace load**: Heavy workspace usage can slow MCP responses + +## Best Practices + +### Security + +- Secure your Coder CLI credentials and tokens +- Use workspace templates with appropriate security configurations +- Regularly audit AI assistant access to workspaces +- Enable Coder's audit logging for compliance + +### Performance + +- Use lightweight workspace templates for faster operations +- Optimize workspace resource allocation based on project needs +- Implement workspace auto-stop policies to manage costs +- Monitor and tune MCP timeout settings + +### Development Workflow + +- Create standardized workspace templates for different project types +- Use consistent naming conventions for workspaces and projects +- Leverage Zed's collaboration features with Coder workspaces +- Set up automated workspace provisioning workflows + +## Advanced Usage + +### Custom Workspace Templates + +Create Coder templates optimized for Zed development: + +```hcl +# Terraform template for Zed + AI development +resource "coder_workspace" "zed_dev" { + name = "zed-development" + + # Optimized for AI development + cpu = 4 + memory = 8192 + + # Pre-configure development tools + startup_script = <<-EOF + # Install language servers for Zed + rustup component add rust-analyzer + npm install -g typescript-language-server + + # Set up AI development dependencies + pip install openai anthropic langchain + EOF +} +```txt + +### Integration with Zed Extensions + +Combine Coder MCP with Zed extensions: +- Use language server extensions with Coder workspace environments +- Integrate version control extensions with Coder's Git support +- Combine AI coding assistants with Coder's remote development capabilities + +### Team Collaboration + +Set up team workflows with Zed and Coder: +- Share workspace templates across the team +- Use Zed's collaboration features with shared Coder workspaces +- Implement code review workflows using both platforms + +## Next Steps + +- Explore [Coder Templates](https://registry.coder.com) optimized for your tech stack +- Learn about [AI coding best practices](../ai-coder/best-practices.md) with Coder +- Set up [Coder Tasks](../ai-coder/tasks.md) for background AI operations +- Review [security considerations](../ai-coder/security.md) for AI development +- Check out Zed's [collaboration features](https://zed.dev/docs/collaboration) with Coder + +## Support + +For Zed-specific MCP issues: + +1. Check [Zed's documentation](https://zed.dev/docs) for MCP support details +1. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues +1. [Join our Discord](https://discord.gg/coder) for community support +4. [Report bugs](https://github.com/coder/coder/issues) on the Coder GitHub repository +5. Check [Zed's GitHub](https://github.com/zed-industries/zed) for Zed-specific issues pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy