docs: Fix broken links in MCP documentation

blink-so[bot] · matifali · blink-so[bot] · commit e5f1ee6869d3 · 2025-08-08T13:33:48.000Z
- Fix relative paths to reference correct documentation files
- Update pkg.go.dev links to use valid version format
- Ensure all internal links point to existing files

Resolves linkspector issues identified in CI.

Co-authored-by: matifali &lt;10648092+matifali@users.noreply.github.com&gt;
diff --git a/docs/ai-coder/mcp-server.md b/docs/ai-coder/mcp-server.md
@@ -12,7 +12,7 @@ Coder's MCP server enables AI assistants to interact with Coder workspaces and i
 - **Agent Activity**: Monitor AI agent operations and history
 
 > [!NOTE]
-> See our [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2@latest/codersdk/toolsdk#pkg-variables) for a complete list of tools included in the MCP server.
+> See our [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk/toolsdk#pkg-variables) for a complete list of tools included in the MCP server.
 
 ## Architecture
 
@@ -27,6 +27,7 @@ Coder provides two MCP server modes to support different AI assistant architectu
 The local MCP server runs on your machine and communicates with AI assistants through standard input/output. This mode is ideal for desktop applications and local development tools.
 
 **Automatic Configuration**:
+
 ```sh
 # First authenticate with Coder
 coder login https://coder.example.com
@@ -37,6 +38,7 @@ coder exp mcp configure cursor
 ```
 
 **Manual Server Start**:
+
 ```sh
 # Start MCP server for manual configuration
 coder exp mcp server
@@ -49,6 +51,7 @@ coder exp mcp server
 The HTTP MCP server runs on your Coder deployment and provides web-based access for browser-based AI assistants.
 
 **Enable HTTP MCP Server**:
+
 ```sh
 # Enable experimental features
 CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
@@ -66,6 +69,7 @@ CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
 The Coder MCP server exposes a comprehensive set of tools through the Model Context Protocol. These tools are automatically available to any connected AI assistant.
 
 ### Workspace Tools
+
 - `list_workspaces` - List all accessible workspaces
 - `create_workspace` - Create new workspaces from templates
 - `start_workspace` - Start stopped workspaces
@@ -74,21 +78,24 @@ The Coder MCP server exposes a comprehensive set of tools through the Model Cont
 - `get_workspace_status` - Check workspace status and resource usage
 
 ### Command Execution Tools
+
 - `execute_command` - Run commands in workspace terminals
 - `get_command_output` - Retrieve command execution results
 - `list_processes` - List running processes in workspaces
 
 ### File System Tools
+
 - `read_file` - Read file contents from workspaces
 - `write_file` - Write files to workspace file systems
 - `list_directory` - List directory contents
 
 ### Template and Resource Tools
+
 - `list_templates` - List available workspace templates
 - `get_template_info` - Get detailed template information
 - `list_template_versions` - List template version history
 
-For the complete and up-to-date list of available tools, see the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2@latest/codersdk/toolsdk#pkg-variables).
+For the complete and up-to-date list of available tools, see the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk/toolsdk#pkg-variables).
 
 ## Configuration Options
 
@@ -125,12 +132,14 @@ export CODER_MCP_LOG_LEVEL=debug
 ## Security Considerations
 
 ### Authentication and Authorization
+
 - **Local Mode**: Uses Coder CLI credentials and user permissions
 - **HTTP Mode**: Requires OAuth2 authentication with proper scopes
 - **Permission Inheritance**: MCP operations inherit the authenticated user's Coder permissions
 - **Audit Logging**: All MCP operations are logged through Coder's audit system
 
 ### Best Practices
+
 - Regularly rotate authentication credentials
 - Monitor MCP usage through Coder's audit logs
 - Use workspace templates with appropriate security configurations
@@ -142,16 +151,19 @@ export CODER_MCP_LOG_LEVEL=debug
 ### Common Issues
 
 **MCP Server Won't Start**:
+
 - Verify Coder CLI authentication: `coder whoami`
 - Check experimental features are enabled for HTTP mode
 - Review server logs for error messages
 
 **AI Assistant Can't Connect**:
+
 - Verify MCP server is running and accessible
 - Check authentication credentials and permissions
 - Ensure network connectivity to Coder deployment
 
 **Permission Denied Errors**:
+
 - Verify user has appropriate workspace permissions
 - Check Coder RBAC settings
 - Ensure OAuth2 scopes are correctly configured (HTTP mode)
diff --git a/docs/mcp/claude-desktop.md b/docs/mcp/claude-desktop.md
@@ -333,5 +333,5 @@ For Claude Desktop-specific MCP issues:
 
 - [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
 - [Claude Desktop User Guide](https://docs.anthropic.com/claude/docs/claude-desktop)
-- [Coder CLI Reference](../../reference/cli.md)
-- [Workspace Templates Guide](../../tutorials/templates.md)
+- [Coder CLI Reference](../reference/cli/index.md)
+- [Workspace Templates Guide](../tutorials/template-from-scratch.md)
diff --git a/docs/mcp/index.md b/docs/mcp/index.md
@@ -112,7 +112,7 @@ Coder MCP inherits Coder's robust security model:
 
 ## Available Tools and Capabilities
 
-The Coder MCP server provides access to a comprehensive set of tools. See the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2@latest/codersdk/toolsdk#pkg-variables) for the complete list of available tools.
+The Coder MCP server provides access to a comprehensive set of tools. See the [toolsdk documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk/toolsdk#pkg-variables) for the complete list of available tools.
 
 ## Next Steps
 
diff --git a/docs/mcp/web-agents.md b/docs/mcp/web-agents.md
@@ -324,7 +324,7 @@ For enterprise deployments:
 - Learn about [AI coding best practices](../ai-coder/best-practices.md)
 - Set up [Coder Tasks](../ai-coder/tasks.md) for background operations
 - Review [security considerations](../ai-coder/security.md) for AI development
-- Check out [OAuth2 provider documentation](../../admin/integrations/oauth2-provider.md)
+- Check out [OAuth2 provider documentation](../admin/integrations/oauth2-provider.md)
 
 ## Support
 
@@ -339,6 +339,6 @@ For web agent MCP issues:
 ## Additional Resources
 
 - [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
-- [Coder OAuth2 Provider Guide](../../admin/integrations/oauth2-provider.md)
-- [Coder API Documentation](../../reference/api.md)
-- [Web Security Best Practices](../../admin/security.md)
+- [Coder OAuth2 Provider Guide](../admin/integrations/oauth2-provider.md)
+- [Coder API Documentation](../reference/api/index.md)
+- [Web Security Best Practices](../admin/security/index.md)
