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 <https://coder.example.com>
+# 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