Agent Mcp Integration Guide

MCP Server Inventory

Complete Server List (8/8 Configured)

Specialist Agent MCP Integration

MCP-Enhanced Specialists (5/5 Complete)

1. dbt-expert

MCP Access: dbt-mcp, snowflake-mcp, github-mcp, sequential-thinking-mcp Tool Count: 40+ dbt tools, 26+ Snowflake tools

Primary Tools:

• Discovery API (5 tools): Model exploration, dependency analysis
• Semantic Layer (4 tools): Governed business metrics
• Administrative API (7 tools): Job orchestration, monitoring
• CLI Commands (8 tools): dbt run, test, build, compile
• SQL Execution (3 tools): DISABLED by default for security

Key Patterns:

• Model performance optimization: dbt-mcp + snowflake-mcp coordination
• Test failure analysis: Discovery API → Semantic Layer → SQL validation
• Impact analysis: get_model_parents + get_model_children for blast radius

Confidence: HIGH (0.92-0.95) for Discovery/Semantic/Admin tools

2. snowflake-expert

MCP Access: snowflake-mcp, dbt-mcp, sequential-thinking-mcp Tool Count: 26+ Snowflake tools

Primary Tools:

• Object Management (~10 tools): DDL operations, warehouse management
• Query Execution (1 tool): SQL with granular permission controls
• Semantic Views (~5 tools): Business metrics layer
• Cortex AI (optional): Search, Analyst, Agent capabilities

Key Patterns:

• Cost analysis: ACCOUNT_USAGE queries via run_snowflake_query
• Performance optimization: Query profiling + dbt-mcp model analysis
• Warehouse sizing: Utilization metrics → right-sizing recommendations

Confidence: HIGH (0.90-0.95) for core operations, MEDIUM (0.70-0.75) for Cortex

3. aws-expert

MCP Access: aws-api, aws-docs, sequential-thinking-mcp Tool Count: 6 tools across 2 MCP servers

Primary Tools:

• aws-api: call_aws (execute CLI), suggest_aws_commands (discover), get_execution_plan (experimental)
• aws-docs: read_documentation, search_documentation, recommend (related content)

Key Patterns:

• Infrastructure inventory: call_aws with READ_OPERATIONS_ONLY
• Documentation currency: Verify with aws-docs before recommending (post-training cutoff)
• Command discovery: suggest_aws_commands → call_aws execution

Critical Insight: aws-docs MCP provides current documentation (not just training data from January 2025) - essential for service limits, new features, best practices, security, API parameters

Confidence: HIGH (0.92) for aws-api, HIGH (0.92-0.95) for aws-docs

4. github-sleuth-expert

MCP Access: github-mcp, filesystem-mcp, sequential-thinking-mcp Tool Count: 28 GitHub tools, 13 filesystem tools

Primary Tools:

• Issue Management (6 tools): create, list, get, update, comment, search
• Pull Request Management (10 tools): create, review, merge, status, files
• Repository Management (9 tools): files, branches, commits, search
• Search & Discovery (3 tools): repos, code, users

Key Patterns:

• Cross-repo pattern analysis: search_issues across org
• Issue investigation: get_issue → search_issues (similar) → filesystem (code context)
• Repository context resolution: Always resolve owner/repo first

Known Issues: get_file_contents missing SHA (use push_files for updates)

Confidence: HIGH (0.88-0.95) for all operations except file updates (MEDIUM 0.65-0.70)

5. documentation-expert

MCP Access: filesystem-mcp, github-mcp, dbt-mcp Tool Count: 13 filesystem tools, 28 GitHub tools

Primary Tools:

• Filesystem Read (5 tools): read_text_file, read_multiple_files, get_file_info
• Filesystem Write (2 tools): write_file, edit_file (with dry run)
• Filesystem Search (3 tools): search_files, directory_tree, list_directory
• GitHub Documentation: push_files (batch updates), get_file_contents, search_code

Key Patterns:

• Knowledge base management: filesystem-mcp for knowledge/ directory
• Repository documentation: github-mcp for README, CONTRIBUTING, docs/
• Documentation quality: dbt-mcp for model documentation analysis

Confidence: HIGH (0.90-0.95) for filesystem, HIGH (0.85-0.88) for GitHub docs

MCP Tool Recommendation Pattern

Standard Recommendation Format

When specialist agents provide MCP tool recommendations to main Claude:

### RECOMMENDED MCP TOOL EXECUTION

**Tool**: mcp__<server>__<tool_name>
**Parameters**:
  - parameter1: "value1"
  - parameter2: value2
  - parameter3: [list, of, values]
**Expected Result**: Description of what this should return
**Success Criteria**: How to validate the operation succeeded
**Fallback**: Alternative approach if MCP unavailable
**Confidence**: HIGH (0.95) - Production-validated pattern

Example Recommendations

dbt-expert recommendation:

### RECOMMENDED MCP TOOL EXECUTION

**Tool**: mcp__dbt-mcp__get_model_details
**Parameters**:
  - model_name: "fct_orders"
**Expected Result**: Compiled SQL, column definitions, dependencies
**Success Criteria**: Returns model metadata with all fields populated
**Fallback**: Read compiled SQL from target/ directory if MCP unavailable
**Confidence**: HIGH (0.95) - Core discovery operation

snowflake-expert recommendation:

### RECOMMENDED MCP TOOL EXECUTION

**Tool**: mcp__snowflake-mcp__run_snowflake_query
**Parameters**:
  - statement: "SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.WAREHOUSE_METERING_HISTORY WHERE START_TIME >= DATEADD(day, -7, CURRENT_TIMESTAMP()) ORDER BY CREDITS_USED DESC LIMIT 10"
**Expected Result**: Top 10 warehouses by credit usage (last 7 days)
**Success Criteria**: Query returns warehouse names with credit totals
**Fallback**: Direct snowflake-connector-python if MCP unavailable
**Confidence**: HIGH (0.90) - Standard cost analysis query

aws-expert recommendation:

### RECOMMENDED MCP TOOL EXECUTION

**Tool**: mcp__aws-api__call_aws
**Parameters**:
  - cli_command: "aws ecs describe-services --cluster my-cluster --services my-service --region us-west-2"
**Expected Result**: ECS service configuration and status
**Success Criteria**: Returns service ARN, status, task definition details
**Fallback**: AWS Console if MCP unavailable
**Confidence**: HIGH (0.92) - Standard infrastructure query

Confidence Scoring Framework

Confidence Levels

• HIGH (0.85-0.95): Production-validated, straightforward operations, minimal risk
• MEDIUM (0.65-0.84): Multi-step workflows, workarounds required, some uncertainty
• LOW (0.40-0.64): Experimental features, edge cases, significant limitations
• RESEARCH NEEDED (<0.40): Novel use cases requiring investigation

Confidence Factors

Increases Confidence:

• ✅ Production-validated in real projects
• ✅ Official tool with stable API
• ✅ Clear documentation and examples
• ✅ Security controls in place
• ✅ Known limitations documented

Decreases Confidence:

• ❌ Experimental or beta features
• ❌ Known bugs or missing functionality
• ❌ Workarounds required
• ❌ Can modify data without safeguards
• ❌ Limited testing or validation

Security & Authentication Summary

Authentication by MCP Server

Security Best Practices

dbt-mcp:

• ✅ Keep DISABLE_SQL=true unless explicitly needed
• ✅ Use Service Token for read-only operations
• ✅ Only enable PAT for SQL execution users

snowflake-mcp:

• ✅ Read-only by default (SELECT, DESCRIBE, USE)
• ✅ Write operations explicitly disabled
• ✅ Password injected at runtime (not in config)
• ✅ Granular SQL permission control via YAML

aws-api:

• ✅ READ_OPERATIONS_ONLY=true restricts to read-only
• ✅ No shell operators (pipes, redirection, etc.)
• ✅ Absolute paths only
• ✅ Command validation before execution

github:

• ✅ Scoped OAuth tokens (minimal required scopes)
• ✅ Rate limit awareness (5000 req/hour, search 30 req/min)
• ✅ Exponential backoff on HTTP 429

filesystem:

• ✅ Directory whitelist (da-agent-hub only)
• ✅ Directory traversal prevention
• ✅ No delete capability

Cross-Tool Integration Patterns

Pattern 1: dbt + Snowflake Coordination

Use Case: Optimize slow dbt model

Workflow:

1. dbt-mcp: Get model details, compiled SQL, dependencies
2. snowflake-mcp: Execute query profile analysis
3. dbt-expert: Analyze results, design optimization
4. snowflake-mcp: Validate optimized query performance
5. dbt-mcp: Update model configuration

Confidence: HIGH (0.92) - Production-validated pattern

Pattern 2: AWS Infrastructure + Documentation

Use Case: Deploy new AWS service

Workflow:

1. aws-docs: Search for current best practices
2. aws-docs: Read specific service documentation
3. aws-expert: Design infrastructure based on current docs
4. aws-api: Validate existing infrastructure state
5. aws-expert: Provide deployment recommendations

Confidence: HIGH (0.90) - Documentation currency critical

Pattern 3: GitHub Issue Investigation

Use Case: Analyze recurring dbt error across repositories

Workflow:

1. github-mcp: Search issues across org for error pattern
2. github-mcp: Get detailed issue information for matches
3. filesystem-mcp: Read local repository code context
4. dbt-expert (if dbt-related): Analyze model/test failures
5. github-sleuth-expert: Synthesize findings, recommend fix

Confidence: HIGH (0.88) - Cross-tool coordination

Pattern 4: Documentation Quality Analysis

Use Case: Assess and improve documentation across projects

Workflow:

1. filesystem-mcp: Search for all .md files in knowledge base
2. filesystem-mcp: Read multiple files for pattern analysis
3. github-mcp: Search code repos for README files
4. dbt-mcp: Analyze dbt model documentation coverage
5. documentation-expert: Synthesize quality report, recommend improvements

Confidence: HIGH (0.90) - Documentation standards enforcement

Role Agent MCP Access Patterns

Recommended MCP Access by Role

Delegation Guidelines

When role agents should use MCP tools directly:

• ✅ Simple, straightforward operations within their domain
• ✅ Standard queries with confidence ≥ 0.85
• ✅ Proven patterns from previous successful use
• ✅ Time-sensitive operations requiring immediate action

When role agents should delegate to specialists:

• ❌ Complex operations requiring deep domain expertise (confidence <0.60)
• ❌ Cross-system coordination (multiple MCP servers)
• ❌ Novel use cases without established patterns
• ❌ Operations with high risk or business impact
• ❌ Optimization requiring performance analysis

Known Issues & Limitations

Issue #1: github get_file_contents Missing SHA

Server: github-mcp Impact: Cannot reliably update files with create_or_update_file Workaround: Use push_files for batch updates OR list_commits to get SHA Confidence: MEDIUM (0.60) - Functional workaround Tracking: https://github.com/github/github-mcp-server/issues/595

Issue #2: dbt SQL Execution Security

Server: dbt-mcp Impact: SQL execution tools can MODIFY data Mitigation: DISABLED by default via DISABLE_SQL=true, requires PAT Confidence: MEDIUM (0.65-0.70) when enabled - requires validation Recommendation: Keep disabled unless explicitly needed

Issue #3: Snowflake Cortex Tools Optional

Server: snowflake-mcp Impact: Cortex AI tools require explicit setup in Snowflake Mitigation: Document when Cortex features are available Confidence: MEDIUM (0.70-0.75) - Requires Cortex service configuration

Issue #4: aws-api READ_OPERATIONS_ONLY

Server: aws-api Impact: Cannot modify infrastructure via MCP (read-only mode) Mitigation: Design pattern - specialists recommend, human implements Confidence: Appropriate restriction - aws-expert provides guidance, not execution

Future MCP Integration Opportunities

High-Priority Additions

1. tableau-mcp (if available)

   • BI dashboard metadata
   • Data source analysis
   • Performance optimization
   • Primary User: tableau-expert, bi-developer-role

2. prefect-mcp (custom integration)

   • Flow orchestration
   • Deployment management
   • Run monitoring
   • Primary User: prefect-expert, data-engineer-role

3. orchestra-mcp (custom integration)

   • Pipeline orchestration
   • Workflow dependencies
   • Resource management
   • Primary User: orchestra-expert, data-engineer-role

Medium-Priority Additions

4. dbt Cloud Admin API (enhanced dbt-mcp)

   • Environment management
   • User/group administration
   • Account-level configuration
   • Primary User: dba-role, data-architect-role

5. Confluence MCP (knowledge management)

   • Team documentation
   • Meeting notes
   • Runbook management
   • Primary User: documentation-expert, business-analyst-role

Maintenance & Updates

When to Update This Guide

• New MCP server added to .mcp.json
• Specialist agent MCP tools updated
• New integration patterns validated in production
• Known issues resolved or new issues discovered
• Confidence scores change based on production validation

Update Protocol

1. Research: Comprehensive tool inventory and documentation
2. Document: Create detailed capability reference
3. Integrate: Update specialist agent files with MCP tools section
4. Test: Validate patterns with actual MCP calls
5. Update Guide: Add to this consolidated reference
6. Communicate: Update team on new capabilities

Verification Checklist

• All MCP servers documented with complete tool inventory
• Specialist agents updated with their MCP access
• Confidence scores assigned based on validation
• Known issues documented with workarounds
• Integration patterns validated in production
• Authentication and security documented
• Role agent delegation patterns defined

Quick Reference

MCP Server Status Check

claude mcp list

Test MCP Tool Availability

# Test dbt-mcp
mcp__dbt-mcp__list_metrics

# Test snowflake-mcp
mcp__snowflake-mcp__list_objects object_type="table" database_name="ANALYTICS_DW"

# Test aws-api
mcp__aws-api__call_aws cli_command="aws sts get-caller-identity"

# Test github
mcp__github__search_repositories query="org:your-org" perPage=5

Documentation Locations

• MCP Research: knowledge/mcp-servers/
• Specialist Agents: .claude/agents/specialists/
• Role Agents: .claude/agents/roles/
• Integration Patterns: .claude/rules/ and .claude/skills/reference-knowledge/
• This Guide: .claude/skills/reference-knowledge/agent-mcp-integration-guide/SKILL.md

Guide created: 2025-10-08 Author: Claude Code - MCP Integration Research Purpose: Complete MCP integration reference for DA Agent Hub agents