MCP Integration - Claude Code

Model Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.

What is MCP?

MCP allows you to:

Connect to external services (databases, APIs, file systems)
Provide 10+ related tools from a single service
Handle OAuth and complex authentication flows
Bundle MCP servers with plugins for automatic setup

Configuration Methods

Plugins can bundle MCP servers in two ways:

Method 1: Dedicated .mcp.json (Recommended)

Create .mcp.json at plugin root:

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

Benefits:

Clear separation of concerns
Easier to maintain
Better for multiple servers

Method 2: Inline in plugin.json

Add mcpServers field to plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Benefits:

Single configuration file
Good for simple single-server plugins

MCP Server Types

stdio (Local Process)

Execute local MCP servers as child processes. Best for local tools and custom servers. Configuration:

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

Use cases:

File system access
Local database connections
Custom MCP servers
NPM-packaged MCP servers

Process management:

Claude Code spawns and manages the process
Communicates via stdin/stdout
Terminates when Claude Code exits

SSE (Server-Sent Events)

Connect to hosted MCP servers with OAuth support. Best for cloud services. Configuration:

{
  "asana": {
    "type": "sse",
    "url": "https://mcp.asana.com/sse"
  }
}

Use cases:

Official hosted MCP servers (Asana, GitHub, etc.)
Cloud services with MCP endpoints
OAuth-based authentication
No local installation needed

Authentication:

OAuth flows handled automatically
User prompted on first use
Tokens managed by Claude Code

HTTP (REST API)

Connect to RESTful MCP servers with token authentication. Configuration:

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Custom-Header": "value"
    }
  }
}

Use cases:

REST API-based MCP servers
Token-based authentication
Custom API backends
Stateless interactions

WebSocket (Real-time)

Connect to WebSocket MCP servers for real-time bidirectional communication. Configuration:

{
  "realtime-service": {
    "type": "websocket",
    "url": "wss://realtime.example.com/mcp"
  }
}

Use cases:

Real-time data streams
Bidirectional communication
Push notifications
Live updates

Environment Variables

$

Use for portable paths to bundled servers:

{
  "command": "node ${CLAUDE_PLUGIN_ROOT}/servers/custom-server.js"
}

Always use $ for paths to ensure plugin portability.

User Environment Variables

Access user’s environment variables:

{
  "env": {
    "DATABASE_URL": "${DATABASE_URL}",
    "API_KEY": "${API_KEY}",
    "DEBUG": "true"
  }
}

Users set these in .env file:

DATABASE_URL=postgresql://localhost/mydb
API_KEY=sk-...

Using MCP Tools

In Commands

Reference MCP tools in command files:

---
description: Query the database
---

Use the `database_query` tool from the database-tools MCP server to:
1. Query the users table
2. Filter by active status
3. Return results formatted as JSON

In Agents

List MCP tools in agent tools array:

---
name: database-analyst
tools: ["database_query", "database_schema", "Read", "Write"]
---

You are a database analyst with access to database tools...

MCP tool names are automatically available when the MCP server is configured.

Example Configurations

File System MCP Server

.mcp.json:

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

Tools provided:

read_file
write_file
list_directory
create_directory
delete_file

PostgreSQL MCP Server

.mcp.json:

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

Tools provided:

query
schema
tables
describe_table

GitHub MCP Server

.mcp.json:

{
  "github": {
    "type": "sse",
    "url": "https://mcp.github.com/sse"
  }
}

Tools provided:

create_issue
list_prs
create_pr
merge_pr
get_file
commit_changes

Custom API Server

.mcp.json:

{
  "company-api": {
    "type": "http",
    "url": "https://api.company.com/mcp",
    "headers": {
      "Authorization": "Bearer ${COMPANY_API_TOKEN}",
      "X-API-Version": "v2"
    }
  }
}

Custom MCP Servers

Creating a Custom Server

Bundle a custom MCP server with your plugin: Directory structure:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── servers/
│   └── custom-server.js
└── .mcp.json

Configuration:

{
  "custom-tools": {
    "command": "node ${CLAUDE_PLUGIN_ROOT}/servers/custom-server.js"
  }
}

Server implementation (servers/custom-server.js):

import { MCPServer } from '@modelcontextprotocol/sdk';

const server = new MCPServer({
  name: 'custom-tools',
  version: '1.0.0'
});

server.tool('custom_operation', {
  description: 'Performs a custom operation',
  parameters: {
    input: { type: 'string', description: 'Input data' }
  },
  handler: async ({ input }) => {
    // Implementation
    return { result: `Processed: ${input}` };
  }
});

server.start();

Authentication Patterns

OAuth (SSE Servers)

Handled automatically by Claude Code:

{
  "oauth-service": {
    "type": "sse",
    "url": "https://service.com/mcp"
  }
}

User prompted on first use to authenticate.

Token-Based (HTTP Servers)

User provides token via environment variable:

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}

User sets in .env:

API_TOKEN=your_token_here

API Key (Query Parameter)

{
  "api-service": {
    "type": "http",
    "url": "https://api.example.com/mcp?key=${API_KEY}"
  }
}

Best Practices

Use Portable Paths

Always use $ for server paths

Environment Variables

Never hardcode credentials, use $ syntax

Dedicated Config

Use .mcp.json for cleaner separation

Document Tools

List available MCP tools in plugin README

Security Considerations

MCP servers have access to external services. Validate inputs and limit permissions.

Least privilege: Grant minimum necessary permissions
Input validation: Validate all user inputs before passing to MCP tools
Secure credentials: Use environment variables, never hardcode
HTTPS/WSS: Use secure protocols for network servers
Audit logs: Log MCP server operations for security review

Troubleshooting

Server Not Starting

Issue: MCP server fails to start Solutions:

Check command path with $
Verify server binary exists and is executable
Check environment variables are set
Review server logs: claude --debug

Tools Not Available

Issue: MCP tools don’t appear Solutions:

Verify server started successfully
Check server name matches configuration
Ensure server exposes tools correctly
Restart Claude Code session

Authentication Failures

Issue: OAuth or token authentication fails Solutions:

For OAuth: Clear cached credentials and re-authenticate
For tokens: Verify $ is set correctly
Check token hasn’t expired
Review authentication headers

Connection Timeouts

Issue: Network MCP servers timeout Solutions:

Check network connectivity
Verify URL is correct and accessible
Increase timeout if needed
Check firewall settings

Next Steps

MCP SDK Docs

Learn more about MCP protocol and creating servers

Example Servers

Browse official MCP server implementations

Plugin System

Bundled Plugins

Plugin Development

Documentation Index

​What is MCP?

​Configuration Methods

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

​Method 2: Inline in plugin.json

​MCP Server Types

​stdio (Local Process)

​SSE (Server-Sent Events)

​HTTP (REST API)

​WebSocket (Real-time)

​Environment Variables

​$

​User Environment Variables

​Using MCP Tools

​In Commands

​In Agents

​Example Configurations

​File System MCP Server

​PostgreSQL MCP Server

​GitHub MCP Server

​Custom API Server

​Custom MCP Servers

​Creating a Custom Server

​Authentication Patterns

​OAuth (SSE Servers)

​Token-Based (HTTP Servers)

​API Key (Query Parameter)

​Best Practices

Use Portable Paths

Environment Variables

Dedicated Config

Document Tools

​Security Considerations

​Troubleshooting

​Server Not Starting

​Tools Not Available

​Authentication Failures

​Connection Timeouts

​Next Steps

MCP SDK Docs

Example Servers

Build docs developers (and LLMs) love

What is MCP?

Configuration Methods

Method 1: Dedicated .mcp.json (Recommended)

Method 2: Inline in plugin.json

MCP Server Types

stdio (Local Process)

SSE (Server-Sent Events)

HTTP (REST API)

WebSocket (Real-time)

Environment Variables

$

User Environment Variables

Using MCP Tools

In Commands

In Agents

Example Configurations

File System MCP Server

PostgreSQL MCP Server

GitHub MCP Server

Custom API Server

Custom MCP Servers

Creating a Custom Server

Authentication Patterns

OAuth (SSE Servers)

Token-Based (HTTP Servers)

API Key (Query Parameter)

Best Practices

Security Considerations

Troubleshooting

Server Not Starting

Tools Not Available

Authentication Failures

Connection Timeouts

Next Steps