[plan] Create MCP configuration best practices documentation

[github-actions]

Objective

Create comprehensive documentation for MCP server configuration patterns, addressing the 30+ toolset variations and 95 workflows missing explicit mode specification. Establish canonical patterns for common use cases.

Context

From the MCP Server Integration Quality analysis:

• 95/166 workflows (57%) are missing explicit MCP mode specification
• 30+ variations of GitHub toolset patterns exist with no clear standard
• Developers face decision paralysis when configuring MCP servers

Approach

1. Create new documentation file at docs/src/content/docs/reference/mcp-configuration-patterns.md
2. Structure with mode selection guide, toolset patterns, examples, and troubleshooting
3. Add validation warning for missing mode configuration
4. Link from existing documentation

Documentation Structure

Mode Selection Guide

• When to use mode: remote (hosted MCP servers, production workflows)
• When to use mode: local (Docker-based, development, custom servers)
• Default behavior explanation
• Performance and security considerations

GitHub Toolset Patterns

Canonical patterns for common use cases:

# Pattern 1: Basic (recommended for most workflows)
github:
  mode: remote
  toolsets: [default]

# Pattern 2: Repository management
github:
  mode: remote
  toolsets: [repos, issues, pull_requests]

# Pattern 3: Code security
github:
  mode: remote
  toolsets: [repos, code_security]

# Pattern 4: Full access (use sparingly)
github:
  mode: remote
  toolsets: [all]

What to Document

• What [default] toolset includes (link to GitHub MCP server docs)
• List all available toolsets with descriptions
• Explain ordering doesn't matter (deduplicated internally)
• Common configuration examples
• Troubleshooting guide
• Migration guide for workflows missing mode

Code Changes

Add validation warning in pkg/workflow/mcp_config_validation.go:

if mcpServer.Mode == "" {
    warnings = append(warnings, fmt.Sprintf(
        "MCP server '%s' missing 'mode' specification. Defaulting to 'remote'. Consider explicitly setting mode for clarity. See: docs/reference/mcp-configuration-patterns",
        serverName))
}

Files to Create/Modify

• Create: docs/src/content/docs/reference/mcp-configuration-patterns.md
• Update: pkg/workflow/mcp_config_validation.go (add validation warning)
• Update: docs/src/content/docs/setup/mcp-server.md (add link to patterns guide)
• Update: AGENTS.md (add reference in MCP section)
• Update: docs/src/content/docs/guides/getting-started-mcp.md (add link)

Acceptance Criteria

• Documentation covers remote vs local mode selection criteria
• GitHub toolset patterns documented with use case examples
• Decision tree for choosing toolsets included
• Examples for common scenarios (basic, advanced, custom)
• Migration guide for workflows missing mode specification
• Validation warning added for missing mode configuration
• Documentation linked from relevant existing docs
• make agent-finish passes without errors

Related

• Discussion: 🎯 Repository Quality: MCP Server Integration Quality #11508 (MCP Server Integration Quality)
• Priority: High
• Effort: Medium

AI generated by Plan Command for discussion #11508