mcp-server-addition

name	mcp-server-addition
description	Comprehensive checklist for integrating new MCP servers into the specialist and role agent ecosystem. Ensures complete integration including configuration, validation, specialist updates, documentation, and testing.
disable-model-invocation	false

MCP Server Addition Protocol

Purpose: Checklist for adding new MCP servers to ensure complete integration Created: 2025-10-08 (Learning from Week 7-8 MCP integration) Status: Production Protocol

---

Overview

When adding a new MCP server to DA Agent Hub, follow this comprehensive protocol to ensure the MCP server is properly integrated into the specialist and role agent ecosystem.

---

Phase 1: MCP Server Setup & Validation (2-3 hours)

Step 1: Configure MCP Server

Location: .claude/mcp.json

Actions:

• Add MCP server configuration with authentication
• Configure security restrictions (read-only by default when possible)
• Set up credential management (1Password environment variables)
• Test MCP server connection (claude mcp list)

Example:

{
  "mcpServers": {
    "new-mcp-server": {
      "command": "uvx",
      "args": ["package-name"],
      "env": {
        "API_TOKEN": "${NEW_MCP_TOKEN}",
        "READ_ONLY": "true"
      },
      "disabled": false
    }
  }
}

---

Step 2: Research MCP Server Tools

Duration: 1-2 hours (depending on server complexity)

Actions:

• Inventory all available MCP tools
• Document tool parameters and usage
• Identify security considerations
• Test critical tools (3-5 most common operations)
• Document known issues and limitations
• Assign confidence levels (HIGH/MEDIUM/LOW)

Output: Create comprehensive documentation Location: knowledge/mcp-servers/<server-name>/

Contents:

• Tool inventory with descriptions
• Authentication and security notes
• Usage examples for common operations
• Known issues and workarounds
• Confidence scoring

---

Step 3: Validate MCP Tools

Duration: 30-60 minutes

Actions:

• Test 3-5 critical tools
• Verify authentication works
• Confirm security restrictions enforced
• Document test results
• Update confidence scores based on testing

Output: Validation report Location: projects/active/.../WEEK*_MCP_VALIDATION.md

---

Phase 2: Specialist Agent Integration (1-2 hours)

Step 4: Update Specialist Agent(s)

Identify which specialists need this MCP server

Actions:

• Add MCP tool inventory to specialist agent file
• Document tool selection framework (when to use which tool)
• Add MCP recommendation pattern examples
• Include security notes and authentication
• Add confidence levels for each tool category
• Document integration patterns with other MCP servers

Location: .claude/agents/specialists/<specialist-name>.md

Section to Add:

## MCP Tools

### <server-name> Tools

**Tool Category 1** (X tools):
- tool_name_1: Description, confidence level
- tool_name_2: Description, confidence level

**Tool Category 2** (Y tools):
- tool_name_3: Description, confidence level

### Tool Selection Framework
- Use tool_1 when: [criteria]
- Use tool_2 when: [criteria]

### MCP Recommendation Pattern
[Example of how specialist recommends MCP tool usage]

### Confidence Levels
| Tool Category | Confidence | Notes |
|---------------|------------|-------|
| Category 1 | HIGH (0.92) | Production-validated |
| Category 2 | MEDIUM (0.70) | Requires validation |

### Security Notes
- Authentication: [method]
- Restrictions: [read-only, permissions]
- Known issues: [workarounds]

---

Phase 3: Role Agent Integration (1-2 hours)

Step 5: Identify Affected Role Agents

Determine which roles should have direct access vs specialist delegation

Questions to answer:

• Which roles work in this domain regularly? (direct access)
• Which roles occasionally need this tool? (specialist delegation)
• What's the confidence threshold for direct use? (typically ≥0.85)

Examples:

• dbt-mcp: analytics-engineer (direct), bi-developer (minimal), others (delegate)
• aws-api: data-engineer (minimal), ui-ux (delegate only)
• slack-mcp: project-manager (heavy), business-analyst (moderate)

---

Step 6: Update Role Agents

For each affected role agent

Actions:

• Add MCP Tool Access section (if not exists)
• Document primary MCP servers for this role
• Define "When to Use MCP Tools Directly" (confidence ≥0.85)
• Define "When to Delegate to Specialists" (confidence <0.60)
• Add usage examples (copy-paste ready)
• Update "When to Handle Directly" checklist (add simple MCP queries)

Location: .claude/agents/roles/<role-name>.md

Template:

## MCP Tool Access

### Primary MCP Servers
**Direct Access**: <server-name>, [other servers]
**Purpose**: [What role uses these MCP tools for]

### When to Use MCP Tools Directly (Confidence ≥0.85)

**<server-name>** ([Usage Level: Heavy/Moderate/Minimal]):
- ✅ Tool 1: Common operation description
- ✅ Tool 2: Common operation description

**Example**:
[Copy-paste ready code example]

### When to Delegate to Specialists (Confidence <0.60 OR Complex Operations)

**<specialist-name>** ([Domain]):
- ❌ Complex operation type 1
- ❌ Complex operation type 2

---

Phase 4: Documentation & Patterns (2-3 hours)

Step 7: Create Quick Reference Card

Purpose: Fast lookup for common MCP tool operations

Actions:

• Create quick reference card
• Document most common operations (80/20 principle)
• Add 3-5 common workflows
• Include troubleshooting guide (common issues)
• Add confidence levels
• Document when to delegate to specialist

Location: .claude/skills/reference-knowledge/<server-name>-quick-reference/SKILL.md

Structure:

• 🚀 Most Common Operations (by category)
• 🎯 Common Workflows (multi-step real-world patterns)
• ⚠️ Important Notes (security, performance, authentication)
• 🔧 Troubleshooting (common issues with solutions)
• 📊 Confidence Levels (tool reliability ratings)
• 🎓 When to Delegate (direct use vs specialist)

---

Step 8: Document Cross-Tool Integration Patterns

Purpose: Show how new MCP server combines with existing servers

Actions:

• Identify 1-3 cross-tool integration patterns
• Document step-by-step workflow
• Include real-world example (production-validated if possible)
• Define tool-specific responsibilities
• Add troubleshooting for integration issues
• Document success metrics

Location: .claude/skills/reference-knowledge/cross-tool-integration-<pattern-name>/SKILL.md

Required Patterns (1-3 depending on MCP complexity):

1. Primary integration: How new MCP combines with most-used existing MCP
2. Secondary integration (if applicable): Alternative workflow pattern
3. Specialist coordination (if applicable): How specialists use multiple MCPs together

Example Patterns:

• dbt + Snowflake: Model optimization
• AWS + Docs: Infrastructure deployment
• GitHub + Investigation: Cross-repo error analysis
• NEW SERVER: [server] + [existing-server]: [workflow name]

---

Step 9: Update Central MCP Integration Guide

Location: .claude/skills/reference-knowledge/agent-mcp-integration-guide/SKILL.md

Actions:

• Add server to MCP Server Inventory table
• Add specialist(s) to Specialist Agent MCP Integration section
• Document cross-tool integration pattern
• Update role agent MCP access table
• Add known issues/limitations (if any)
• Update maintenance & verification checklist

---

Phase 5: Validation & Testing (1-2 hours)

Step 10: Execute Integration Pattern Test

Purpose: Validate cross-tool pattern works as documented

Actions:

• Execute documented integration pattern step-by-step
• Use actual MCP tool calls (not just documentation)
• Document any issues or adjustments needed
• Validate success metrics achieved
• Update pattern documentation with findings

Example: If added tableau-mcp

# Test: Tableau + dbt + Snowflake optimization pattern
1. mcp__tableau-mcp__get_dashboard_details (identify slow dashboard)
2. mcp__dbt-mcp__get_model_details (understand data source)
3. mcp__snowflake-mcp__run_query (analyze query performance)
4. Delegate to tableau-expert (optimization recommendations)
5. Validate improvement

---

Step 11: Production Validation (Optional - Highly Recommended)

Purpose: Validate MCP integration with real use case

Actions:

• Identify small, low-risk production use case
• Execute using MCP integration patterns
• Measure actual business impact
• Document learnings and pattern refinements
• Update confidence scores based on production validation

Example: Use new MCP server to solve actual Issue from GitHub backlog

---

Phase 6: Knowledge Capture (30-60 minutes)

Step 12: Update Project Context

Location: projects/active/.../context.md

Actions:

• Add MCP server to Active MCP list
• Document new specialist(s) created/updated
• Update specialist count (track progress toward 17+ goal)
• Record any blockers or known issues
• Update next actions

---

Step 13: Create Completion Documentation

Purpose: Record what was accomplished for future reference

Actions:

• Create WEEK*__COMPLETE.md file
• Document deliverables (research, specialists, roles, patterns)
• Record metrics (time, quality, coverage)
• Capture key discoveries and learnings
• Provide next steps recommendations

Location: projects/active/.../WEEK*_<MILESTONE>_COMPLETE.md

---

Checklist Summary

Quick Validation - Did you complete all critical steps?

Configuration & Research

• MCP server configured in .mcp.json
• Credentials set up (1Password environment variables)
• MCP server connection tested
• Complete tool inventory documented
• 3-5 critical tools validated
• Security considerations documented

Integration

• Specialist agent(s) updated with MCP tools
• Tool selection framework documented
• Confidence levels assigned
• Role agent(s) updated with direct access patterns
• Delegation patterns defined
• Usage examples provided (copy-paste ready)

Documentation

• Quick reference card created
• 1-3 cross-tool integration patterns documented
• Central MCP Integration Guide updated
• Known issues and workarounds documented
• Troubleshooting guide included

Validation

• Integration pattern tested with actual MCP calls
• Production validation (if possible)
• Confidence scores validated through testing
• Project context updated
• Completion documentation created

---

Time Estimates

Phase 1 (Setup & Validation): 2-3 hours Phase 2 (Specialist Integration): 1-2 hours Phase 3 (Role Integration): 1-2 hours Phase 4 (Documentation): 2-3 hours Phase 5 (Validation): 1-2 hours Phase 6 (Knowledge Capture): 30-60 minutes

Total: 8-13 hours for complete MCP server integration

Faster if:

• MCP server has good documentation (reduce research time)
• Tool inventory is small (<10 tools)
• Only 1-2 specialists affected
• Few role agents need direct access

Slower if:

• Poor documentation (require experimentation)
• Large tool inventory (>40 tools like dbt-mcp)
• Multiple specialists need updates
• Complex cross-tool integration patterns

---

Success Criteria

Complete integration achieved when:

• ✅ MCP server operational and validated
• ✅ At least 1 specialist has complete tool inventory
• ✅ Affected role agents have direct access patterns
• ✅ Quick reference card created
• ✅ At least 1 cross-tool integration pattern documented
• ✅ Central MCP Integration Guide updated
• ✅ Integration pattern tested with actual MCP calls

---

Related Resources

• MCP Integration Guide: .claude/skills/reference-knowledge/agent-mcp-integration-guide/SKILL.md
• Quick Reference Template: Use existing cards as template
• Integration Pattern Template: Use Week 7 Day 5 patterns as template
• Specialist Template: .claude/agents/specialists/specialist-template.md
• Role Template: .claude/agents/roles/role-template.md

---

Created: 2025-10-08 Learning from: Week 7-8 MCP integration experience Purpose: Ensure complete, consistent MCP server integration