[Code Quality] Improve MCP server configuration documentation and examples

[github-actions]

Description

Analysis of 4,389 agent tasks shows that MCP/Gateway-related tasks (Cluster 2) have the lowest success rate at 61.4% and the highest iteration cycles with 4.5 average comments per PR. This indicates unclear requirements and insufficient documentation for MCP server configuration tasks.

Current Problems

1. Lowest success rate - 61.4% compared to 70%+ for other task types
2. High iteration cycles - 4.5 comments per PR indicates back-and-forth clarification
3. Complex changes - Average 29.8 files changed with 4.2 commits
4. Missing context - Configuration examples not readily available

Proposed Improvements

1. Add MCP Configuration Quick Start Guide

Create a dedicated guide showing common MCP server configuration patterns:

## Common MCP Server Configurations

### GitHub MCP Server (Default)
``````yaml
tools:
  github:
    mode: remote
    toolsets: [default]

Custom MCP Server with Docker

tools:
  my-custom-server:
    mode: local
    docker:
      image: my-org/my-mcp-server:latest
      environment:
        API_KEY: ${{ secrets.MY_API_KEY }}

#### 2. Add Architecture Diagrams
Include visual representations of:
- MCP gateway flow
- Local vs remote MCP servers
- Tool communication patterns

#### 3. Expand Troubleshooting Section
Add common issues and solutions:
- Connection failures
- Authentication errors
- Timeout issues
- Configuration validation

#### 4. Add Real-World Examples
Include complete working examples from actual workflows:
- Security scanning with MCP
- Data analysis with MCP
- Custom tool integration

### Files to Create/Update

- `docs/src/content/docs/guides/mcp-configuration.md` (new)
- `docs/src/content/docs/reference/mcp-servers.md` (update)
- `docs/src/content/docs/troubleshooting/mcp-issues.md` (new)

### Success Criteria

- [ ] MCP task success rate improves from 61.4% to >70%
- [ ] Average comments per MCP PR reduces from 4.5 to <3.0
- [ ] New quick start guide with 5+ configuration examples
- [ ] Architecture diagrams for 3 common scenarios
- [ ] Troubleshooting guide with 10+ common issues
- [ ] At least 3 real-world workflow examples

### Priority

**High** - Directly impacts 7.6% of all tasks (332 tasks) with measurable quality issues

### Source

Extracted from [Copilot Agent Prompt Clustering Analysis - January 2026](https://github.com/githubnext/gh-aw/discussions/12473)

### Estimated Effort

2-3 days - Documentation writing, diagram creation, example validation

### Metrics to Track

- **Before**: 61.4% success rate, 4.5 comments/PR, 29.8 files changed
- **After (Target)**: >70% success rate, <3.0 comments/PR, <20 files changed

### Keywords from Failed Tasks

Common keywords in MCP-related tasks: mcp, gateway, server, mcp server, configuration, github, add


<!-- gh-aw-tracker-id: discussion-task-miner -->




> AI generated by [Discussion Task Miner - Code Quality Improvement Agent](https://github.com/githubnext/gh-aw/actions/runs/21472184395)
> - [x] expires <!-- gh-aw-expires: 2026-02-12T09:15:49.165Z --> on Feb 12, 2026, 9:15 AM UTC

<!-- gh-aw-agentic-workflow: Discussion Task Miner - Code Quality Improvement Agent, gh-aw-tracker-id: discussion-task-miner, engine: copilot, run: https://github.com/githubnext/gh-aw/actions/runs/21472184395 -->

<!-- gh-aw-workflow-id: discussion-task-miner -->

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster