MCP (Model Context Protocol) Integration

Purpose

This skill provides comprehensive guidance for integrating MCP servers with Claude, including proper configuration, fully qualified tool naming conventions, and skill integration patterns. MCP enables Claude to interact with external APIs, databases, and services through a standardized protocol.

When to Use This Skill

Use this skill when:

• Building external API integrations (databases, cloud services, custom APIs)
• Extending Claude's capabilities with custom tools
• Configuring MCP servers in .mcp.json
• Writing skills that reference MCP tools
• Setting up project-scoped or user-scoped MCP servers
• Bundling MCP servers within plugins
• Troubleshooting MCP tool discovery or invocation issues

Core Concepts

MCP Server Types

Local stdio servers:

• Run as local processes that communicate via standard input/output
• Command-based execution (Node.js, Python, compiled binaries)
• Suitable for most integrations

HTTP servers:

• Run as web services with HTTP endpoints
• Support remote deployment and scaling
• Useful for shared infrastructure

Scope Levels

Project scope:

• Configured in .mcp.json at project root
• Only available within the specific project
• Ideal for project-specific integrations

User scope:

• Configured in global user settings
• Available across all projects
• Suitable for general-purpose tools

MCP Configuration

Using claude mcp add Command

Add MCP servers using the CLI for quick setup:

# Add project-scoped server
claude mcp add --scope project ServerName

# Add user-scoped server
claude mcp add --scope user ServerName

The command will:

1. Create or update .mcp.json with server configuration
2. Prompt for required configuration values
3. Validate the server connection

Manual .mcp.json Configuration

Create or edit .mcp.json at project root for project-scoped servers:

{
  "servers": {
    "ServerName": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "${API_KEY}",
        "ENVIRONMENT": "production"
      }
    }
  }
}

Structure requirements:

• servers (object, required): Map of server names to configurations
• command (string, required): Executable command to start the server
• args (array, optional): Command-line arguments
• env (object, optional): Environment variables for the server process

Environment Variable Configuration

Using environment variables:

{
  "servers": {
    "BigQuery": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-bigquery"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "${GOOGLE_APPLICATION_CREDENTIALS}",
        "PROJECT_ID": "${BIGQUERY_PROJECT_ID}"
      }
    }
  }
}

Best practices:

• Reference sensitive credentials via environment variables
• Never hardcode API keys or secrets in .mcp.json
• Use ${VARIABLE_NAME} syntax for variable substitution
• Document required environment variables in project README

Plugin Bundling

Bundle MCP servers within plugins for distribution:

{
  "servers": {
    "CustomAPI": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/custom-api/index.js"],
      "env": {
        "API_KEY": "${CUSTOM_API_KEY}"
      }
    }
  }
}

Plugin bundling guidelines:

• Use ${CLAUDE_PLUGIN_ROOT} variable for plugin-relative paths
• Always use forward slashes (/) for cross-platform compatibility
• Include server dependencies in plugin package
• Document installation and configuration requirements

Fully Qualified Tool Names

Required Format

When referencing MCP tools in skills or instructions, ALWAYS use fully qualified names:

ServerName:tool_name

Why fully qualified names are required:

• Tools from different servers may have identical names
• Prevents ambiguity when multiple servers are active
• Enables Claude to route tool calls to the correct server
• Required for proper tool discovery and invocation

Examples

BigQuery integration:

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the BigQuery:bigquery_query tool to execute SQL queries.

GitHub integration:

Use the GitHub:create_issue tool to create issues.
Use the GitHub:list_pull_requests tool to fetch open PRs.

Multiple server integration:

First, use Slack:send_message to notify the team.
Then, use Jira:create_ticket to track the work.
Finally, use GitHub:create_pull_request to submit changes.

Tool Name Discovery

To discover available tools from an MCP server:

1. Check server documentation for tool catalog
2. Use server introspection capabilities if available
3. Consult server source code or API specifications
4. Reference skill documentation for common patterns

Skill Integration Patterns

Referencing MCP Tools in Skills

When writing skills that use MCP tools, provide clear guidance on tool usage:

## Querying the Database

To retrieve user data:

1. Use the Database:get_schema tool to understand table structure
2. Construct the appropriate query
3. Use the Database:execute_query tool to run the query
4. Parse and format the results for the user

Error Handling

Include error handling guidance in skills:

## Error Recovery

If BigQuery:bigquery_query fails:

1. Check the error message for query syntax issues
2. Verify table names using BigQuery:bigquery_schema
3. Confirm project permissions and quotas
4. Retry with corrected query or simplified scope

Authentication Patterns

Document authentication requirements:

## Prerequisites

Before using Salesforce tools, ensure:

- `SALESFORCE_CLIENT_ID` environment variable is set
- `SALESFORCE_CLIENT_SECRET` environment variable is set
- OAuth flow has been completed for user authorization
- Server is configured in .mcp.json with proper credentials

Common MCP Server Examples

BigQuery Server

{
  "servers": {
    "BigQuery": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-bigquery"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "${GOOGLE_APPLICATION_CREDENTIALS}",
        "PROJECT_ID": "${BIGQUERY_PROJECT_ID}"
      }
    }
  }
}

Available tools:

• BigQuery:bigquery_schema - Retrieve table schemas
• BigQuery:bigquery_query - Execute SQL queries

GitHub Server

{
  "servers": {
    "GitHub": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Available tools:

• GitHub:create_issue - Create GitHub issues
• GitHub:list_pull_requests - List pull requests
• GitHub:create_pull_request - Create pull requests
• GitHub:get_repository - Get repository information

Slack Server

{
  "servers": {
    "Slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

Available tools:

• Slack:send_message - Send messages to channels
• Slack:list_channels - List available channels
• Slack:get_channel_history - Retrieve channel message history

Best Practices

Configuration Management

1. Separate secrets from configuration

   • Use environment variables for all sensitive data
   • Commit .mcp.json to version control (without secrets)
   • Document required environment variables

2. Use appropriate scope

   • Project scope for project-specific integrations
   • User scope for general-purpose tools
   • Plugin bundling for distributable integrations

3. Validate server connectivity

   • Test MCP server startup and tool discovery
   • Verify authentication and permissions
   • Handle connection failures gracefully

Tool Naming Consistency

1. Always use fully qualified names

   • Never reference tools without server prefix
   • Use consistent server naming across projects
   • Document server name in skill metadata

2. Namespace organization

   • Group related tools under single server name
   • Use descriptive server names (e.g., "BigQuery" not "BQ")
   • Avoid generic names like "API" or "Database"

Skill Documentation

1. Document prerequisites

   • Required environment variables
   • Authentication setup steps
   • MCP server installation instructions

2. Provide concrete examples

   • Show actual tool invocations
   • Include expected inputs and outputs
   • Demonstrate error handling patterns

3. Reference tool capabilities

   • List available tools from the server
   • Describe each tool's purpose and parameters
   • Link to server documentation

Troubleshooting

Server Not Starting

Symptoms: MCP tools not available, server connection errors

Solutions:

1. Verify command path is correct and executable exists
2. Check args array for proper argument formatting
3. Ensure required environment variables are set
4. Review server logs for startup errors

Tool Not Found

Symptoms: "Tool not found" errors when invoking tools

Solutions:

1. Verify fully qualified name format: ServerName:tool_name
2. Check server name matches .mcp.json configuration
3. Confirm server started successfully and tools are registered
4. Review server documentation for correct tool names

Authentication Failures

Symptoms: Permission denied, authentication errors

Solutions:

1. Verify environment variables contain valid credentials
2. Check API keys/tokens have required permissions
3. Confirm OAuth flows are completed if required
4. Review server documentation for authentication requirements

Related Skills and Agents

Recommended agents:

• mcp-server-architect - Design and implement custom MCP servers
• agent-architect - Design skills that integrate MCP tools

Related documentation:

• Chapter 4: Tool Documentation (Section 3: MCP)
• Chapter 11: Agent & Skill Catalog (mcp-server-architect)

Reference Files

For detailed examples and advanced patterns, see:

• references/mcp-server-examples.md - Additional MCP server configurations
• references/authentication-patterns.md - Advanced authentication setups