MCP Integrator

Integrate Model Context Protocol (MCP) servers into Claude Code plugins to extend functionality with external tools and services.

When to Use This Skill

Use when:

• Adding MCP servers to plugins
• User requests "add MCP server" or "integrate external tool"
• Connecting plugins to external APIs/services
• Providing access to databases, filesystems, or web services

What is MCP?

Model Context Protocol (MCP) enables Claude Code to connect with external tools and services:

• Tools: Functions Claude can call
• Prompts: Reusable prompt templates
• Resources: External data sources

MCP servers provide these capabilities through a standardized protocol.

MCP Configuration Format

MCP servers are configured in .mcp.json:

{
  "mcpServers": {
    "server-name": {
      "command": "path/to/server",
      "args": ["--option", "value"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Instructions

Step 1: Identify MCP Server

Determine what server to integrate:

• Server type (command, SSE, WebSocket)
• Installation method (npm, pip, binary)
• Required configuration
• Environment variables needed
• Available tools/prompts

Step 2: Install MCP Server (If Needed)

Many MCP servers need installation:

NPM-based:

npm install -g @package/mcp-server

Python-based:

pip install mcp-server-package

Binary: Download and place in accessible location.

Step 3: Configure in .mcp.json

Add server configuration:

Basic configuration:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@package/mcp-server"]
    }
  }
}

With environment variables:

{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "env": {
        "API_KEY": "${API_KEY}",
        "BASE_URL": "https://api.example.com"
      }
    }
  }
}

Plugin-relative paths:

{
  "mcpServers": {
    "custom-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  }
}

Step 4: Use Environment Variables

Support user configuration:

With defaults:

{
  "env": {
    "API_KEY": "${API_KEY}",
    "BASE_URL": "${BASE_URL:-https://api.example.com}"
  }
}

Syntax:

• ${VAR} - Required variable
• ${VAR:-default} - Variable with default
• ${CLAUDE_PLUGIN_ROOT} - Plugin directory

Step 5: Document Requirements

In plugin README, document:

• Required environment variables
• Installation steps
• Configuration options
• Usage examples

MCP Server Types

Command-based Servers

Most common type - runs executable:

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

SSE Servers

Server-Sent Events:

{
  "sse-server": {
    "type": "sse",
    "url": "https://server.example.com/sse"
  }
}

HTTP Servers

REST API:

{
  "api-server": {
    "type": "http",
    "url": "${API_BASE_URL:-https://api.example.com}",
    "headers": {
      "Authorization": "Bearer ${API_KEY}"
    }
  }
}

Common MCP Servers

Filesystem Server

Access local files:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
  }
}

GitHub Server

GitHub API integration:

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

Database Server

Database access:

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}"
    }
  }
}

Web Search

Brave search integration:

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
    }
  }
}

Plugin-Bundled MCP Servers

Plugins can include custom MCP servers:

Directory Structure

my-plugin/
├── servers/
│   ├── custom-server.py
│   └── requirements.txt
└── .mcp.json

Configuration

{
  "mcpServers": {
    "custom": {
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/custom-server.py"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}/servers"
    }
  }
}

Installation

Document in README:

## Setup

Install server dependencies:

```bash
cd servers
pip install -r requirements.txt
```

Configure environment variables:

```bash
export CUSTOM_API_KEY=your-key
```

Environment Variable Expansion

Supported locations:

• command path
• args values
• env values
• url in SSE/HTTP servers
• cwd path

Not supported:

• JSON keys
• type field

Example:

{
  "dynamic-server": {
    "command": "${SERVER_BIN:-npx}",
    "args": ["${SERVER_PACKAGE}"],
    "env": {
      "CONFIG": "${CONFIG_PATH:-./config.json}"
    }
  }
}

OAuth Integration

Some servers require OAuth:

{
  "oauth-server": {
    "command": "npx",
    "args": ["-y", "@package/oauth-server"],
    "oauth": {
      "provider": "github",
      "scopes": ["repo", "user"]
    }
  }
}

Users authenticate via /mcp command.

Testing MCP Integration

Verify Server Loads

1. Install plugin
2. Run /mcp command
3. Check server appears and status is connected
4. Verify tools are available

Test Tools

> Use the [server-name] tool to [action]

Verify tool executes correctly.

Check Authentication

For OAuth servers:

1. Run /mcp
2. Authenticate if needed
3. Verify "Authenticated" status

Best Practices

1. Use environment variables: Don't hardcode credentials
2. Provide defaults: Use ${VAR:-default} syntax
3. Document requirements: List env vars in README
4. Use plugin root: ${CLAUDE_PLUGIN_ROOT} for paths
5. Test installation: Verify setup steps work
6. Handle errors: Graceful failures if server unavailable
7. Version servers: Specify exact versions when possible

Example Plugin with MCP

data-plugin/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json
├── servers/
│   ├── data-processor.py
│   └── requirements.txt
└── README.md

.mcp.json:

{
  "mcpServers": {
    "data-processor": {
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/data-processor.py"],
      "env": {
        "DATA_PATH": "${DATA_PATH:-./data}",
        "API_KEY": "${DATA_API_KEY}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

README.md:

## Environment Variables

Required:
- `DATA_API_KEY` - API key for data service
- `DATABASE_URL` - PostgreSQL connection string

Optional:
- `DATA_PATH` - Data directory (default: ./data)

## Setup

```bash
export DATA_API_KEY=your-key
export DATABASE_URL=postgresql://user:pass@host/db
```

Troubleshooting

Server not loading:

• Check command path is correct
• Verify server is installed
• Check environment variables are set
• Review server logs

Tools not available:

• Confirm server connected via /mcp
• Check server provides expected tools
• Verify permissions/authentication

Authentication fails:

• For OAuth: use /mcp to authenticate
• Check API keys are valid
• Verify environment variables

Environment variables not expanding:

• Use correct syntax: ${VAR} or ${VAR:-default}
• Check variables are exported
• Verify expansion is supported in field

Reference Documentation

• MCP Protocol: https://modelcontextprotocol.io
• Official MCP servers: https://github.com/modelcontextprotocol/servers
• Claude Code MCP docs: https://code.claude.com/docs/en/mcp