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

---
name: MCP Configuration Specialist
description: 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)

```json
{
  "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

```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

```json
{
  "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

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

### SSE (Deprecated)

**Note**: Prefer HTTP transport when available

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

## Environment Variables

### Plugin-Relative Paths

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

### User Environment Variables

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

### Default Values

```json
{
  "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

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

### API Integration

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

### Multi-Server Plugin

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

## Security Best Practices

### ✅ DO

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

### ❌ DON'T

```json
{
  "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

```markdown
## 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](../claude-plugins/skill.md) - Create complete plugins
- [MCP Builder](../../example-skills/mcp-builder/) - Build MCP servers

**Auxiliary Documentation:**
- [Real-World Examples](examples.md) - Complete plugin configurations
- [Configuration Reference](reference.md) - Detailed schema and options

**External:**
- [MCP Protocol Docs](https://modelcontextprotocol.io/)
- [Claude Code MCP Docs](https://docs.claude.com/en/docs/claude-code/mcp)

---

**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.