claude-plugins/claude-code/skills/mcp-config/skill.md

name, description

name	description
MCP Configuration Specialist	Configure MCP servers in Claude Code plugins and .mcp.json files. Use PROACTIVELY when users mention "MCP server", "configure MCP", "add MCP", ".mcp.json", "Model Context Protocol", or need to bundle MCP integrations in plugins. NOT for using existing MCP tools.

MCP Configuration in Claude Code Plugins

When to Use This Skill

Use this skill when:

• Configuring MCP servers in plugin .mcp.json files
• Adding MCP servers to plugin.json inline
• Setting up stdio, HTTP, or SSE transports
• Configuring environment variables and authentication
• Bundling MCP servers with plugins for distribution

Do NOT use this skill for:

• Using MCP tools (that's normal Claude Code usage)
• Creating MCP servers themselves (use mcp-builder skill)
• Installing MCP servers via CLI commands

Quick Start

1. Plugin MCP Configuration (.mcp.json at plugin root)

{
  "mcpServers": {
    "server-name": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "API_KEY": "${API_KEY}",
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

2. Inline in plugin.json

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

MCP Transport Types

Stdio (Local Process)

Best for: Local tools, file system access, custom scripts

{
  "my-local-server": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/servers/local.js"],
    "env": {
      "LOG_LEVEL": "info"
    }
  }
}

Common commands: node, python, npx, ${CLAUDE_PLUGIN_ROOT}/bin/server

Windows Note: Wrap npx with "cmd", ["/c", "npx", ...]

HTTP (Remote Server)

Best for: Cloud services, REST APIs, remote integrations

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

SSE (Deprecated)

Note: Prefer HTTP transport when available

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

Environment Variables

Plugin-Relative Paths

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

User Environment Variables

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

Default Values

{
  "url": "${API_BASE_URL:-https://api.example.com}/mcp",
  "env": {
    "LOG_LEVEL": "${LOG_LEVEL:-info}"
  }
}

Syntax: ${VAR} (required) or ${VAR:-default} (optional with fallback)

Common Patterns

Database Access

{
  "postgres-db": {
    "command": "npx",
    "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
  }
}

API Integration

{
  "company-api": {
    "type": "http",
    "url": "${API_BASE_URL}/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Workspace-ID": "${WORKSPACE_ID}"
    }
  }
}

Multi-Server Plugin

{
  "mcpServers": {
    "database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db",
      "env": {"DB_URL": "${DATABASE_URL}"}
    },
    "api": {
      "type": "http",
      "url": "${API_URL}/mcp"
    }
  }
}

Security Best Practices

✅ DO

{
  "env": {
    "API_KEY": "${API_KEY}",           // User environment
    "CONFIG": "${CLAUDE_PLUGIN_ROOT}"  // Plugin-relative
  }
}

❌ DON'T

{
  "env": {
    "API_KEY": "sk_live_1234567890",  // ❌ Hardcoded secret
    "PASSWORD": "my_password"         // ❌ Exposed credential
  }
}

Best practices:

1. Document required environment variables in README
2. Use placeholders in examples: ${API_KEY}
3. Never commit actual credentials
4. Validate required vars at runtime

Plugin Distribution

Directory Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json              # MCP configuration at root
├── servers/               # Optional bundled servers
│   └── custom-server.js
└── README.md              # Document env vars needed

README Documentation Template

## Required Environment Variables

Set these before enabling the plugin:

- `DATABASE_URL` - PostgreSQL connection string
- `API_KEY` - Your API authentication key

Example:
```bash
export DATABASE_URL="postgresql://user:pass@localhost/db"
export API_KEY="your-key-here"

## Testing & Troubleshooting

### Validate Configuration

```bash
# Check JSON syntax
cat .mcp.json | jq .

# Install and test
/plugin install /path/to/plugin@local
/mcp

# Verify environment variables
echo $DATABASE_URL

Common Issues

Problem	Solution
Server not starting	Check command path, ensure executable exists
Environment var not expanded	Verify syntax: ${VAR} not $VAR
Windows stdio failure	Add "cmd /c" wrapper for npx
Connection errors	Verify URL, check network/firewall
Server not found in /mcp	Restart Claude Code after plugin changes

Key Concepts

Configuration Scopes: Plugin MCP servers are project-scoped:

• Start automatically when plugin is enabled
• Require Claude Code restart to apply changes
• Managed through plugin installation (not /mcp commands)

Transport Selection:

• Stdio: Local processes, file system access
• HTTP: Cloud services, REST APIs (recommended)
• SSE: Legacy support (use HTTP instead)

Integration Points:

1. .mcp.json at plugin root (preferred for complex configs)
2. plugin.json → mcpServers field (inline for simple configs)

Additional Resources

Related Skills:

• Plugin Development - Create complete plugins
• MCP Builder - Build MCP servers

Auxiliary Documentation:

• Real-World Examples - Complete plugin configurations
• Configuration Reference - Detailed schema and options

External:

• MCP Protocol Docs
• Claude Code MCP Docs

---

Remember: Plugin MCP servers start automatically when enabled. Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths. Document required environment variables. Restart Claude Code to apply MCP changes.