docs: Fix markdown linting errors in MCP documentation

- Add language specifications to code blocks - Fix ordered list numbering issues - Ensure all markdown follows project style guidelines Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>
coder · matifali · Aug 8, 2025 · Aug 8, 2025 · Aug 8, 2025 · Aug 8, 2025
commit 92f6a323e9ebd8f56e08a7380a903003f8e5d8ca
diff --git a/docs/mcp/claude-desktop.md b/docs/mcp/claude-desktop.md
@@ -20,7 +20,7 @@ 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
@@ -36,7 +36,7 @@ If automatic configuration doesn't work, you can manually set up MCP:
    - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
    - **Linux**: `~/.config/Claude/claude_desktop_config.json`
 
-2. **Add Coder MCP server configuration**:
+1. **Add Coder MCP server configuration**:
    ```json
    {
      "mcpServers": {
@@ -49,7 +49,7 @@ If automatic configuration doesn't work, you can manually set up MCP:
    }
    ```
 
-3. **Restart Claude Desktop** to load the new configuration.
+1. **Restart Claude Desktop** to load the new configuration.
 
 ## Using Coder MCP with Claude Desktop
 
@@ -58,18 +58,21 @@ Once configured, Claude can interact with your Coder workspaces through MCP, pro
 ### 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
@@ -78,43 +81,44 @@ Once configured, Claude can interact with your Coder workspaces through MCP, pro
 ### 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
-2. Install FastAPI and dependencies
-3. Set up the basic project structure
+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
-2. Examine the application logs
-3. Verify the configuration
+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
-2. Analyze the code structure and patterns
-3. Identify potential improvements
+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
 
@@ -159,7 +163,7 @@ Customize the MCP server behavior for Claude Desktop:
     }
   }
 }
-```
+```txt
 
 ### Environment Variables
 
@@ -174,7 +178,7 @@ export CODER_MCP_TIMEOUT=120s
 
 # Start Claude Desktop with custom environment
 open -a "Claude Desktop"
-```
+```txt
 
 ## Troubleshooting
 
@@ -186,54 +190,59 @@ open -a "Claude Desktop"
    coder workspaces list
    ```
 
-2. **Test MCP server manually**:
+1. **Test MCP server manually**:
+
    ```bash
    coder exp mcp server --log-level debug
    ```
 
-3. **Check Claude Desktop configuration**:
+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
-2. **Check MCP server status**: Ensure the MCP server is running and accessible
-3. **Verify permissions**: Ensure Claude Desktop has necessary permissions to execute the Coder CLI
+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
-2. **Check network connectivity**: Verify stable connection to your Coder deployment
-3. **Monitor MCP timeouts**: Adjust timeout settings for long-running operations
+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
    ```
 
-2. **Check token expiration**: Verify your Coder authentication token is still valid
-3. **Verify permissions**: Ensure your user has appropriate workspace permissions
+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
@@ -270,7 +279,7 @@ resource "coder_workspace" "claude_dev" {
     echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   EOF
 }
-```
+```txt
 
 ### Automated Workflows
 
@@ -293,7 +302,7 @@ coder ssh my-project -- 'echo "Workspace ready"'
 coder ssh my-project -- 'git init && npm init -y'
 
 echo "Project setup complete!"
-```
+```txt
 
 ### Integration with Development Tools
 
@@ -315,8 +324,8 @@ Combine Claude Desktop with other development tools:
 For Claude Desktop-specific MCP issues:
 
 1. Check [Claude Desktop documentation](https://docs.anthropic.com/claude/docs/claude-desktop) for MCP support
-2. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues
-3. [Join our Discord](https://discord.gg/coder) for community 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
 

diff --git a/docs/mcp/cursor.md b/docs/mcp/cursor.md
@@ -20,7 +20,7 @@ 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
@@ -36,7 +36,7 @@ If automatic configuration doesn't work, you can manually set up MCP:
    - **Windows**: `%APPDATA%\Cursor\User\globalStorage\mcp.json`
    - **Linux**: `~/.config/Cursor/User/globalStorage/mcp.json`
 
-2. **Add Coder MCP server configuration**:
+1. **Add Coder MCP server configuration**:
    ```json
    {
      "mcpServers": {
@@ -50,7 +50,7 @@ If automatic configuration doesn't work, you can manually set up MCP:
    }
    ```
 
-3. **Restart Cursor** to load the new configuration.
+1. **Restart Cursor** to load the new configuration.
 
 ## Using Coder MCP in Cursor
 
@@ -59,41 +59,45 @@ 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
 
@@ -138,7 +142,7 @@ You can customize the MCP server behavior in your configuration:
     }
   }
 }
-```
+```txt
 
 ### Environment Variables
 
@@ -150,7 +154,7 @@ export CODER_MCP_LOG_LEVEL=debug
 
 # Increase timeout for long-running operations
 export CODER_MCP_TIMEOUT=120s
-```
+```txt
 
 ## Troubleshooting
 
@@ -161,50 +165,55 @@ export CODER_MCP_TIMEOUT=120s
    coder whoami
    ```
 
-2. **Test MCP server manually**:
+1. **Test MCP server manually**:
+
    ```bash
    coder exp mcp server --help
    ```
 
-3. **Verify Cursor configuration**:
+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
-2. **Restart Cursor**: Sometimes a full restart is needed
-3. **Check Cursor logs**: Look for MCP-related errors in Cursor's developer console
+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
-2. **Check authentication**: Re-authenticate if needed:
+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
-2. **Monitor resource usage**: Check workspace CPU and memory allocation
-3. **Adjust MCP timeout**: Increase timeout for slow operations
+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
@@ -230,7 +239,7 @@ resource "coder_workspace" "dev" {
     npm install -g @cursor/cli
   EOF
 }
-```
+```txt
 
 ### Integration with CI/CD
 
@@ -251,6 +260,6 @@ Use Cursor + Coder MCP for automated development workflows:
 For Cursor-specific MCP issues:
 
 1. Check [Cursor's MCP documentation](https://docs.cursor.com/mcp) (when available)
-2. [Contact Coder Support](https://coder.com/contact) for Coder MCP server issues
-3. [Join our Discord](https://discord.gg/coder) for community 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 GitHub