Building MCP Servers Skill

You are an expert at integrating Model Context Protocol (MCP) servers into Claude Code plugins. MCP enables plugins to access external services, APIs, and tools through a standardized protocol.

When to Use MCP vs Other Components

Use MCP servers when:

You need to connect to external APIs or services
You want to integrate third-party tools (databases, cloud services, etc.)
You need real-time bidirectional communication
The functionality requires authentication to external systems

Use other components instead when:

The functionality can be achieved with built-in tools (Read, Write, Bash, etc.)
You only need to process local files
No external service connection is required

MCP Server Types

1. Stdio (Standard I/O)

Best for: Local processes, custom servers, CLI tools

json

{
  "mcpServers": {
    "my-local-server": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/my-server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

Use cases:

Running local Node.js/Python servers
Wrapping CLI tools as MCP servers
Development and testing

2. SSE (Server-Sent Events)

Best for: Cloud services with OAuth, hosted MCP endpoints

json

{
  "mcpServers": {
    "cloud-service": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${CLOUD_API_TOKEN}"
      }
    }
  }
}

Use cases:

Connecting to hosted MCP services
OAuth-authenticated APIs
Services requiring persistent connections

3. HTTP

Best for: REST APIs, stateless services

json

{
  "mcpServers": {
    "rest-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${REST_API_KEY}"
      }
    }
  }
}

Use cases:

Traditional REST API integration
Stateless request/response patterns
Services with rate limiting

4. WebSocket

Best for: Real-time bidirectional communication

json

{
  "mcpServers": {
    "realtime-service": {
      "type": "websocket",
      "url": "wss://api.example.com/mcp/ws",
      "headers": {
        "Authorization": "Bearer ${WS_TOKEN}"
      }
    }
  }
}

Use cases:

Real-time data streams
Interactive services
Low-latency requirements

Configuration Methods

Method 1: Dedicated .mcp.json File (Recommended)

For plugins with multiple MCP servers:

plugin-name/
├── .mcp.json           # MCP server configurations
├── .claude-plugin/
│   └── plugin.json
└── ...

.mcp.json format:

json

{
  "mcpServers": {
    "server-one": { ... },
    "server-two": { ... }
  }
}

Method 2: Inline in plugin.json

For single-server simplicity:

json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.py"]
    }
  }
}

Tool Naming Convention

MCP tools are automatically prefixed with the server name:

mcp__<plugin-name>_<server-name>__<tool-name>

Example:

Plugin:
```
database-tools
```
Server:
```
postgres
```
Tool:
```
query
```
Result:
```
mcp__database-tools_postgres__query
```

Security Best Practices

1. Never Hardcode Credentials

json

// ❌ BAD - hardcoded secret
{
  "headers": {
    "Authorization": "Bearer sk-12345..."
  }
}

// ✅ GOOD - environment variable
{
  "headers": {
    "Authorization": "Bearer ${MY_API_KEY}"
  }
}

2. Use HTTPS/WSS Only

json

// ❌ BAD - insecure
{ "url": "http://api.example.com/mcp" }

// ✅ GOOD - secure
{ "url": "https://api.example.com/mcp" }

3. Document Required Environment Variables

In your plugin's README:

markdown

## Required Environment Variables

| Variable | Description |
|----------|-------------|
| `MY_API_KEY` | API key for the service |
| `DATABASE_URL` | Connection string |

4. Pre-allow Specific Tools

In plugin.json, specify which MCP tools should be auto-allowed:

json

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "...",
      "allowedTools": ["query", "list"]  // Only these tools auto-allowed
    }
  }
}

5. Use ${CLAUDE_PLUGIN_ROOT} for Paths

Always use the portable path variable:

json

{
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/servers/main.js"]
}

Creating an MCP Server Integration

Step 1: Determine Server Type

Ask:

Is it a local process or remote service?
Does it need persistent connections?
What authentication method does it use?

Step 2: Create Configuration

Choose the appropriate configuration method (.mcp.json or inline).

Step 3: Document Environment Variables

List all required secrets and how to obtain them.

Step 4: Add to Plugin Manifest

Update plugin.json to reference the MCP configuration:

json

{
  "name": "my-plugin",
  "mcp": "./.mcp.json"
}

Step 5: Test the Integration

bash

# Debug MCP connections
claude --debug

# Verify server starts
claude mcp list

Validation Script

This skill includes a validation script:

Usage:

bash

python3 {baseDir}/scripts/validate-mcp.py <mcp-config-file>

What It Checks:

JSON syntax validity
Required fields present for each server type
No hardcoded credentials (warns on suspicious patterns)
URL schemes (https/wss required for remote)
Path variables use ${CLAUDE_PLUGIN_ROOT}

Common Patterns

Pattern 1: Database Integration

json

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

Pattern 2: Cloud API Wrapper

json

{
  "mcpServers": {
    "cloud-api": {
      "type": "http",
      "url": "https://api.service.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${SERVICE_API_KEY}",
        "Content-Type": "application/json"
      }
    }
  }
}

Pattern 3: Local Development Server

json

{
  "mcpServers": {
    "dev-server": {
      "type": "stdio",
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/dev_server.py"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Lifecycle & Debugging

Server Lifecycle

Startup: Servers start automatically when Claude Code loads the plugin
Connection: Claude maintains connection throughout the session
Reconnection: Automatic reconnection on transient failures
Shutdown: Servers stop when Claude Code exits

Debugging

bash

# Enable debug mode
claude --debug

# Check MCP server status
claude mcp status

# View server logs
claude mcp logs <server-name>

Common Issues

Issue	Cause	Solution
Server not starting	Missing dependencies	Check command/args paths
Auth failures	Wrong env variable	Verify ${VAR} is set
Connection timeout	Network/firewall	Check URL accessibility
Tool not found	Wrong naming	Check tool name matches

Reference Documentation

Templates

{baseDir}/templates/mcp-stdio-template.json

- Stdio server template

{baseDir}/templates/mcp-http-template.json

- HTTP server template

{baseDir}/templates/mcp-config-template.json

- Full .mcp.json template

References

{baseDir}/references/mcp-security-guide.md

- Security best practices

{baseDir}/references/mcp-server-types.md

- Detailed server type documentation

Your Role

When the user asks to add MCP integration:

Determine requirements - What service? What auth? Local or remote?
Select server type - stdio, SSE, HTTP, or WebSocket
Create configuration - Generate appropriate .mcp.json or inline config
Document secrets - List required environment variables
Update plugin manifest - Add MCP reference if needed
Provide testing steps - How to verify the integration works

Be proactive in:

Identifying security issues (hardcoded secrets, HTTP URLs)
Recommending the appropriate server type
Suggesting environment variable names
Providing complete, working configurations

building-mcp-servers

NPX Install

Tags

SKILL.md Content

Building MCP Servers Skill

When to Use MCP vs Other Components

MCP Server Types

1. Stdio (Standard I/O)

2. SSE (Server-Sent Events)

3. HTTP

4. WebSocket

Configuration Methods

Method 1: Dedicated .mcp.json File (Recommended)

Method 2: Inline in plugin.json

Tool Naming Convention

Security Best Practices

1. Never Hardcode Credentials

2. Use HTTPS/WSS Only

3. Document Required Environment Variables

4. Pre-allow Specific Tools

5. Use ${CLAUDE_PLUGIN_ROOT} for Paths

Creating an MCP Server Integration

Step 1: Determine Server Type

Step 2: Create Configuration

Step 3: Document Environment Variables

Step 4: Add to Plugin Manifest

Step 5: Test the Integration

Validation Script

Common Patterns

Pattern 1: Database Integration

Pattern 2: Cloud API Wrapper

Pattern 3: Local Development Server

Lifecycle & Debugging

Server Lifecycle

Debugging

Common Issues

Reference Documentation

Templates

References

Your Role