MCP skill
This commit is contained in:
movq
@@ -77,6 +77,8 @@ mkdir -p commands agents skills hooks
|
||||
|
||||
### 1. Commands (commands/)
|
||||
|
||||
**→ [See claude-commands skill for full guide](../claude-commands/skill.md)**
|
||||
|
||||
```markdown
|
||||
# commands/review.md
|
||||
---
|
||||
@@ -92,6 +94,8 @@ Review $ARGUMENTS for:
|
||||
|
||||
### 2. Agents (agents/)
|
||||
|
||||
**→ [See claude-subagents skill for full guide](../claude-subagents/skill.md)**
|
||||
|
||||
```markdown
|
||||
# agents/code-reviewer.md
|
||||
---
|
||||
@@ -105,16 +109,18 @@ You are a code review specialist...
|
||||
|
||||
### 3. Skills (skills/)
|
||||
|
||||
**→ [See claude-skills skill for full guide](../claude-skills/skill.md)**
|
||||
|
||||
```
|
||||
skills/
|
||||
└── my-skill/
|
||||
└── SKILL.md # With frontmatter
|
||||
└── skill.md # With frontmatter
|
||||
```
|
||||
|
||||
See claude-skills skill for details.
|
||||
|
||||
### 4. Hooks (hooks/hooks.json)
|
||||
|
||||
**→ [See claude-hooks skill for full guide](../claude-hooks/skill.md)**
|
||||
|
||||
```json
|
||||
{
|
||||
"PostToolUse": [{
|
||||
@@ -129,6 +135,8 @@ See claude-skills skill for details.
|
||||
|
||||
### 5. MCP Servers (.mcp.json)
|
||||
|
||||
**→ [See mcp-config skill for full guide](../mcp-config/skill.md)**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
@@ -275,13 +283,17 @@ api-plugin/
|
||||
|
||||
## Additional Resources
|
||||
|
||||
**Need more?**
|
||||
- [Plugin Examples](examples.md) - Complete working plugins
|
||||
- [Component Templates](templates.md) - Ready-to-use structures
|
||||
**Component Skills:**
|
||||
- [Commands Guide](../claude-commands/skill.md) - Create slash commands
|
||||
- [Subagents Guide](../claude-subagents/skill.md) - Configure specialized agents
|
||||
- [Skills Guide](../claude-skills/skill.md) - Build contextual knowledge skills
|
||||
- [Hooks Guide](../claude-hooks/skill.md) - Automate with event-driven hooks
|
||||
- [MCP Config Guide](../mcp-config/skill.md) - Integrate MCP servers
|
||||
- [Memory Guide](../claude-memory/skill.md) - Manage persistent memory
|
||||
|
||||
**External Resources:**
|
||||
- [Official Docs](https://docs.claude.com/en/docs/claude-code/plugins)
|
||||
- [Commands Guide](../claude-commands/SKILL.md)
|
||||
- [Hooks Guide](../claude-hooks/SKILL.md)
|
||||
- [Skills Guide](../claude-skills/SKILL.md)
|
||||
- [MCP Protocol](https://modelcontextprotocol.io/)
|
||||
|
||||
💡 **Tip**: Start with one component type, test thoroughly, then expand. Plugins organize related functionality.
|
||||
|
||||
|
||||
358
claude-code/skills/mcp-config/examples.md
Normal file
358
claude-code/skills/mcp-config/examples.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# Real-World MCP Configuration Examples
|
||||
|
||||
Complete plugin configurations for common integration scenarios.
|
||||
|
||||
## GitHub Integration Plugin
|
||||
|
||||
Full-featured GitHub integration with authentication:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"type": "http",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${GITHUB_TOKEN}",
|
||||
"Accept": "application/vnd.github.v3+json"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Required Environment Variables:**
|
||||
- `GITHUB_TOKEN` - Personal access token with repo permissions
|
||||
|
||||
**Plugin Structure:**
|
||||
```
|
||||
github-plugin/
|
||||
├── .claude-plugin/plugin.json
|
||||
├── .mcp.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Database Tools Plugin
|
||||
|
||||
Multi-database support with PostgreSQL and Redis:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"postgres": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
|
||||
"env": {
|
||||
"PGPASSWORD": "${DB_PASSWORD}"
|
||||
}
|
||||
},
|
||||
"redis": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/redis-server",
|
||||
"env": {
|
||||
"REDIS_URL": "${REDIS_URL:-redis://localhost:6379}",
|
||||
"REDIS_DB": "${REDIS_DB:-0}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Required Environment Variables:**
|
||||
- `DATABASE_URL` - PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/db`)
|
||||
- `DB_PASSWORD` - Database password
|
||||
- `REDIS_URL` - Redis connection string (optional, defaults to localhost)
|
||||
- `REDIS_DB` - Redis database number (optional, defaults to 0)
|
||||
|
||||
## Multi-Environment API Plugin
|
||||
|
||||
Supports staging and production environments:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"api": {
|
||||
"type": "http",
|
||||
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${API_TOKEN}",
|
||||
"X-Environment": "${ENVIRONMENT:-production}",
|
||||
"X-Version": "v2",
|
||||
"X-Client-ID": "${CLIENT_ID}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Environment Configuration:**
|
||||
|
||||
Production:
|
||||
```bash
|
||||
export API_BASE_URL="https://api.example.com"
|
||||
export API_TOKEN="prod_token_here"
|
||||
export ENVIRONMENT="production"
|
||||
export CLIENT_ID="client_prod_id"
|
||||
```
|
||||
|
||||
Staging:
|
||||
```bash
|
||||
export API_BASE_URL="https://staging.api.example.com"
|
||||
export API_TOKEN="staging_token_here"
|
||||
export ENVIRONMENT="staging"
|
||||
export CLIENT_ID="client_staging_id"
|
||||
```
|
||||
|
||||
## Monitoring and Observability Plugin
|
||||
|
||||
Integrates with Sentry and custom logging:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"sentry": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.sentry.dev/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${SENTRY_TOKEN}"
|
||||
}
|
||||
},
|
||||
"logs": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/log-aggregator",
|
||||
"args": ["--endpoint", "${LOG_ENDPOINT}"],
|
||||
"env": {
|
||||
"LOG_LEVEL": "${LOG_LEVEL:-info}",
|
||||
"LOG_FORMAT": "json"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Cloud Services Plugin
|
||||
|
||||
AWS, Azure, and GCP integrations:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"aws": {
|
||||
"command": "aws-mcp-server",
|
||||
"env": {
|
||||
"AWS_REGION": "${AWS_REGION:-us-east-1}",
|
||||
"AWS_PROFILE": "${AWS_PROFILE:-default}"
|
||||
}
|
||||
},
|
||||
"azure": {
|
||||
"type": "http",
|
||||
"url": "${AZURE_ENDPOINT}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${AZURE_TOKEN}",
|
||||
"Subscription-ID": "${AZURE_SUBSCRIPTION_ID}"
|
||||
}
|
||||
},
|
||||
"gcp": {
|
||||
"command": "gcloud",
|
||||
"args": ["mcp", "serve", "--project", "${GCP_PROJECT_ID}"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Local Development Tools Plugin
|
||||
|
||||
File watchers, linters, and formatters:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"file-watcher": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/watcher",
|
||||
"args": ["--watch", "${WATCH_PATH:-.}", "--ignore", "node_modules"]
|
||||
},
|
||||
"linter": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "eslint", "--format", "json", "--stdin"],
|
||||
"env": {
|
||||
"ESLINT_USE_FLAT_CONFIG": "true"
|
||||
}
|
||||
},
|
||||
"formatter": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "prettier", "--stdin-filepath", "file.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Windows Version:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"linter": {
|
||||
"command": "cmd",
|
||||
"args": ["/c", "npx", "-y", "eslint", "--format", "json", "--stdin"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing and CI/CD Plugin
|
||||
|
||||
Integrates with test runners and deployment tools:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"test-runner": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/servers/test-server",
|
||||
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/test-config.json"],
|
||||
"env": {
|
||||
"TEST_ENV": "${TEST_ENV:-development}",
|
||||
"COVERAGE_THRESHOLD": "${COVERAGE_THRESHOLD:-80}"
|
||||
}
|
||||
},
|
||||
"deployment": {
|
||||
"type": "http",
|
||||
"url": "${DEPLOY_ENDPOINT}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${DEPLOY_TOKEN}",
|
||||
"X-Pipeline-ID": "${PIPELINE_ID}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Documentation Generator Plugin
|
||||
|
||||
Generates and maintains documentation:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"docs-generator": {
|
||||
"command": "node",
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/docs-gen.js"],
|
||||
"env": {
|
||||
"DOCS_OUTPUT": "${DOCS_OUTPUT:-./docs}",
|
||||
"DOCS_FORMAT": "${DOCS_FORMAT:-markdown}",
|
||||
"INCLUDE_EXAMPLES": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Protocol Handler Plugin
|
||||
|
||||
For proprietary internal systems:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"internal-system": {
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/bin/internal-mcp-server",
|
||||
"args": [
|
||||
"--endpoint", "${INTERNAL_ENDPOINT}",
|
||||
"--cert", "${CLAUDE_PLUGIN_ROOT}/certs/client.pem",
|
||||
"--key", "${CLAUDE_PLUGIN_ROOT}/certs/client-key.pem"
|
||||
],
|
||||
"env": {
|
||||
"INTERNAL_API_KEY": "${INTERNAL_API_KEY}",
|
||||
"TLS_VERIFY": "true",
|
||||
"REQUEST_TIMEOUT": "${REQUEST_TIMEOUT:-30000}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Microservices Communication Plugin
|
||||
|
||||
Service mesh integration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"service-mesh": {
|
||||
"type": "http",
|
||||
"url": "${MESH_GATEWAY_URL}/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${MESH_TOKEN}",
|
||||
"X-Service-Name": "${SERVICE_NAME}",
|
||||
"X-Namespace": "${NAMESPACE:-default}"
|
||||
}
|
||||
},
|
||||
"service-discovery": {
|
||||
"command": "consul",
|
||||
"args": ["mcp", "serve", "-address", "${CONSUL_ADDRESS}"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tips for Real-World Configurations
|
||||
|
||||
1. **Always document required environment variables** in your plugin's README
|
||||
2. **Provide sensible defaults** using `${VAR:-default}` syntax
|
||||
3. **Use `${CLAUDE_PLUGIN_ROOT}`** for bundled servers and assets
|
||||
4. **Group related servers** in a single plugin
|
||||
5. **Test with both local and remote transports** before distribution
|
||||
6. **Include environment variable validation** in your MCP servers
|
||||
7. **Provide example configurations** for common deployment scenarios
|
||||
|
||||
## Common Configuration Mistakes to Avoid
|
||||
|
||||
❌ **Hardcoded credentials**
|
||||
```json
|
||||
{
|
||||
"env": {"API_KEY": "sk_live_abc123"} // Never do this!
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Environment variables**
|
||||
```json
|
||||
{
|
||||
"env": {"API_KEY": "${API_KEY}"}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
❌ **Absolute paths**
|
||||
```json
|
||||
{
|
||||
"command": "/Users/yourname/projects/plugin/server.js" // Won't work for others
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Plugin-relative paths**
|
||||
```json
|
||||
{
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/server.js"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
❌ **Missing Windows compatibility**
|
||||
```json
|
||||
{
|
||||
"command": "npx", // Fails on Windows
|
||||
"args": ["-y", "package"]
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Windows-compatible**
|
||||
```json
|
||||
{
|
||||
"command": "cmd",
|
||||
"args": ["/c", "npx", "-y", "package"]
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Main MCP Configuration Guide](skill.md)
|
||||
- [Configuration Reference](reference.md)
|
||||
- [MCP Protocol Documentation](https://modelcontextprotocol.io/)
|
||||
545
claude-code/skills/mcp-config/reference.md
Normal file
545
claude-code/skills/mcp-config/reference.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# MCP Configuration Reference
|
||||
|
||||
Complete schema and technical reference for MCP server configuration in Claude Code plugins.
|
||||
|
||||
## Configuration Schema
|
||||
|
||||
### Stdio Server Configuration
|
||||
|
||||
```typescript
|
||||
{
|
||||
command: string // Required: Executable path or command name
|
||||
args?: string[] // Optional: Command-line arguments
|
||||
env?: Record<string, string> // Optional: Environment variables
|
||||
}
|
||||
```
|
||||
|
||||
**Field Details:**
|
||||
|
||||
- **`command`**: The executable to run. Can be:
|
||||
- System command: `"node"`, `"python"`, `"npx"`
|
||||
- Absolute path: `"/usr/local/bin/my-server"`
|
||||
- Plugin-relative: `"${CLAUDE_PLUGIN_ROOT}/servers/my-server"`
|
||||
|
||||
- **`args`**: Array of arguments passed to the command
|
||||
- Order matters
|
||||
- Supports variable expansion: `["--config", "${CONFIG_PATH}"]`
|
||||
|
||||
- **`env`**: Environment variables for the process
|
||||
- Inherits user's environment by default
|
||||
- Additional vars override/extend inherited ones
|
||||
- Supports variable expansion: `{"KEY": "${USER_KEY}"}`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"my-server": {
|
||||
"command": "node",
|
||||
"args": ["${CLAUDE_PLUGIN_ROOT}/dist/server.js", "--port", "8080"],
|
||||
"env": {
|
||||
"NODE_ENV": "production",
|
||||
"LOG_LEVEL": "${LOG_LEVEL:-info}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### HTTP Server Configuration
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: "http" // Required: Transport type
|
||||
url: string // Required: HTTP(S) endpoint URL
|
||||
headers?: Record<string, string> // Optional: HTTP headers
|
||||
}
|
||||
```
|
||||
|
||||
**Field Details:**
|
||||
|
||||
- **`type`**: Must be `"http"` for HTTP transport
|
||||
|
||||
- **`url`**: The MCP endpoint URL
|
||||
- Must be valid HTTP(S) URL
|
||||
- Supports variable expansion: `"${API_BASE_URL}/mcp"`
|
||||
- Should end in `/mcp` by convention
|
||||
|
||||
- **`headers`**: HTTP headers sent with requests
|
||||
- Common uses: Authentication, API keys, custom metadata
|
||||
- Supports variable expansion: `{"Authorization": "Bearer ${TOKEN}"}`
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"api-server": {
|
||||
"type": "http",
|
||||
"url": "https://api.example.com/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer ${API_TOKEN}",
|
||||
"X-Client-Version": "1.0.0",
|
||||
"Accept": "application/json"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SSE Server Configuration (Deprecated)
|
||||
|
||||
```typescript
|
||||
{
|
||||
type: "sse" // Required: Transport type
|
||||
url: string // Required: SSE endpoint URL
|
||||
headers?: Record<string, string> // Optional: HTTP headers
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: SSE transport is deprecated. Use HTTP transport instead when available.
|
||||
|
||||
**Field Details:**
|
||||
|
||||
- **`type`**: Must be `"sse"` for Server-Sent Events transport
|
||||
- **`url`**: The SSE endpoint URL
|
||||
- **`headers`**: HTTP headers (same as HTTP transport)
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"legacy-server": {
|
||||
"type": "sse",
|
||||
"url": "https://api.example.com/sse",
|
||||
"headers": {
|
||||
"X-API-Key": "${API_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variable Expansion
|
||||
|
||||
### Syntax
|
||||
|
||||
| Pattern | Behavior | Example |
|
||||
|---------|----------|---------|
|
||||
| `${VAR}` | Required variable (error if not set) | `${API_KEY}` |
|
||||
| `${VAR:-default}` | Optional with fallback value | `${PORT:-8080}` |
|
||||
| `${CLAUDE_PLUGIN_ROOT}` | Plugin directory path (special) | `${CLAUDE_PLUGIN_ROOT}/bin` |
|
||||
|
||||
### Expansion Locations
|
||||
|
||||
Environment variables can be expanded in:
|
||||
|
||||
- **Stdio servers**:
|
||||
- `command` field
|
||||
- `args` array elements
|
||||
- `env` object values
|
||||
|
||||
- **HTTP/SSE servers**:
|
||||
- `url` field
|
||||
- `headers` object values
|
||||
|
||||
### Special Variables
|
||||
|
||||
#### `${CLAUDE_PLUGIN_ROOT}`
|
||||
|
||||
- **Type**: Plugin-specific
|
||||
- **Value**: Absolute path to plugin directory
|
||||
- **Use case**: Reference bundled servers, configs, assets
|
||||
- **Example**: `"${CLAUDE_PLUGIN_ROOT}/servers/db-server"`
|
||||
|
||||
#### User Environment Variables
|
||||
|
||||
All variables from user's shell environment are available:
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"PATH": "${PATH}", // User's PATH
|
||||
"HOME": "${HOME}", // User's home directory
|
||||
"DATABASE_URL": "${DATABASE_URL}" // Custom user variable
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Expansion Examples
|
||||
|
||||
**Basic expansion:**
|
||||
```json
|
||||
{
|
||||
"url": "${API_BASE_URL}/mcp"
|
||||
}
|
||||
```
|
||||
With `API_BASE_URL=https://api.example.com`, becomes:
|
||||
```
|
||||
https://api.example.com/mcp
|
||||
```
|
||||
|
||||
**Default values:**
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"LOG_LEVEL": "${LOG_LEVEL:-info}",
|
||||
"PORT": "${PORT:-3000}"
|
||||
}
|
||||
}
|
||||
```
|
||||
Without environment variables set, becomes:
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"LOG_LEVEL": "info",
|
||||
"PORT": "3000"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Plugin-relative paths:**
|
||||
```json
|
||||
{
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
|
||||
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
|
||||
}
|
||||
```
|
||||
With plugin at `/home/user/.claude/plugins/my-plugin`, becomes:
|
||||
```
|
||||
command: /home/user/.claude/plugins/my-plugin/bin/server
|
||||
args: ["--config", "/home/user/.claude/plugins/my-plugin/config.json"]
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### .mcp.json (Recommended)
|
||||
|
||||
**Location**: Plugin root directory
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"server-name-1": { /* config */ },
|
||||
"server-name-2": { /* config */ }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Advantages**:
|
||||
- Separates concerns (MCP config separate from plugin metadata)
|
||||
- Easier to maintain complex configurations
|
||||
- Can be shared/reused across plugins
|
||||
- Better for multiple MCP servers
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"database": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
|
||||
},
|
||||
"api": {
|
||||
"type": "http",
|
||||
"url": "${API_BASE_URL}/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### plugin.json (Inline)
|
||||
|
||||
**Location**: `.claude-plugin/plugin.json`
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"mcpServers": {
|
||||
"server-name": { /* config */ }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Advantages**:
|
||||
- Single file for simple plugins
|
||||
- All configuration in one place
|
||||
- No additional files needed
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"name": "simple-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "A simple plugin with one MCP server",
|
||||
"mcpServers": {
|
||||
"api": {
|
||||
"type": "http",
|
||||
"url": "https://api.example.com/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Choosing Between .mcp.json and inline:**
|
||||
- Use `.mcp.json` for 2+ servers or complex configs
|
||||
- Use inline for single simple server
|
||||
- Both methods are functionally identical
|
||||
|
||||
## Server Lifecycle
|
||||
|
||||
### 1. Plugin Enable
|
||||
- Plugin is enabled via `/plugin enable`
|
||||
- MCP servers are registered with Claude Code
|
||||
- No servers start yet
|
||||
|
||||
### 2. Claude Code Start
|
||||
- Claude Code reads enabled plugins
|
||||
- MCP servers start automatically
|
||||
- Stdio servers: Process spawned
|
||||
- HTTP/SSE servers: Connection established
|
||||
|
||||
### 3. Server Ready
|
||||
- Server responds to initialization
|
||||
- Tools/resources/prompts registered
|
||||
- Available via `/mcp` command
|
||||
|
||||
### 4. Plugin Update
|
||||
- Configuration changes detected
|
||||
- **Requires Claude Code restart** to apply
|
||||
- Old servers stop, new ones start on restart
|
||||
|
||||
### 5. Plugin Disable
|
||||
- Plugin disabled via `/plugin disable`
|
||||
- MCP servers stop automatically
|
||||
- Resources cleaned up
|
||||
|
||||
## Platform-Specific Considerations
|
||||
|
||||
### Windows
|
||||
|
||||
**npx Wrapper Required:**
|
||||
```json
|
||||
{
|
||||
"command": "cmd",
|
||||
"args": ["/c", "npx", "-y", "package-name"]
|
||||
}
|
||||
```
|
||||
|
||||
**Path Separators:**
|
||||
- Windows: Use forward slashes `/` in JSON
|
||||
- Variable expansion handles platform differences
|
||||
- Example: `"${CLAUDE_PLUGIN_ROOT}/bin/server"` works on all platforms
|
||||
|
||||
**Environment Variables:**
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"USERPROFILE": "${USERPROFILE}", // Windows home directory
|
||||
"APPDATA": "${APPDATA}" // Windows app data
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### macOS/Linux
|
||||
|
||||
**Standard Commands:**
|
||||
```json
|
||||
{
|
||||
"command": "npx",
|
||||
"args": ["-y", "package-name"]
|
||||
}
|
||||
```
|
||||
|
||||
**Executable Permissions:**
|
||||
- Bundled executables must have execute permissions
|
||||
- Set in version control: `git update-index --chmod=+x server.sh`
|
||||
- Or in plugin distribution: `chmod +x ${CLAUDE_PLUGIN_ROOT}/bin/*`
|
||||
|
||||
## Validation and Errors
|
||||
|
||||
### Common Validation Errors
|
||||
|
||||
**Invalid JSON:**
|
||||
```
|
||||
Error: Failed to parse .mcp.json
|
||||
```
|
||||
**Solution**: Validate JSON syntax with `jq` or JSON validator
|
||||
|
||||
**Missing Required Fields:**
|
||||
```
|
||||
Error: Missing required field 'command' in stdio server config
|
||||
Error: Missing required field 'url' in http server config
|
||||
```
|
||||
**Solution**: Add required fields per schema above
|
||||
|
||||
**Invalid Variable Expansion:**
|
||||
```
|
||||
Error: Environment variable 'API_KEY' is required but not set
|
||||
```
|
||||
**Solution**: Set required environment variable or provide default value
|
||||
|
||||
**Invalid URL:**
|
||||
```
|
||||
Error: Invalid URL in http server config
|
||||
```
|
||||
**Solution**: Ensure URL is valid HTTP(S) format
|
||||
|
||||
### Runtime Errors
|
||||
|
||||
**Server Won't Start:**
|
||||
- Check command path exists and is executable
|
||||
- Verify all required environment variables are set
|
||||
- Check server logs for startup errors
|
||||
|
||||
**Connection Failed (HTTP/SSE):**
|
||||
- Verify URL is accessible
|
||||
- Check network/firewall settings
|
||||
- Confirm authentication headers are correct
|
||||
|
||||
**Server Not Found:**
|
||||
- Ensure plugin is enabled
|
||||
- Restart Claude Code after config changes
|
||||
- Check `/mcp` output for registered servers
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Stdio Servers
|
||||
|
||||
**Process Overhead:**
|
||||
- Each stdio server is a separate process
|
||||
- Consider resource usage for multiple servers
|
||||
- Use HTTP servers for remote services
|
||||
|
||||
**Startup Time:**
|
||||
- Servers start on Claude Code launch
|
||||
- Slow-starting servers delay tool availability
|
||||
- Consider lazy initialization for heavy servers
|
||||
|
||||
### HTTP/SSE Servers
|
||||
|
||||
**Network Latency:**
|
||||
- Remote servers add network latency
|
||||
- Use connection pooling where possible
|
||||
- Consider caching for read-heavy operations
|
||||
|
||||
**Rate Limiting:**
|
||||
- Respect API rate limits
|
||||
- Implement backoff strategies
|
||||
- Cache responses when appropriate
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Credential Management
|
||||
|
||||
✅ **Do:**
|
||||
- Store credentials in environment variables
|
||||
- Use `${VAR}` expansion in configs
|
||||
- Document required variables in README
|
||||
- Use secure storage for sensitive values
|
||||
|
||||
❌ **Don't:**
|
||||
- Hardcode credentials in JSON
|
||||
- Commit credentials to version control
|
||||
- Share credentials in plugin distributions
|
||||
- Log credential values
|
||||
|
||||
### Network Security
|
||||
|
||||
**HTTPS Only:**
|
||||
```json
|
||||
{
|
||||
"type": "http",
|
||||
"url": "https://api.example.com/mcp" // ✅ HTTPS
|
||||
}
|
||||
```
|
||||
|
||||
**Avoid HTTP:**
|
||||
```json
|
||||
{
|
||||
"type": "http",
|
||||
"url": "http://api.example.com/mcp" // ❌ Insecure
|
||||
}
|
||||
```
|
||||
|
||||
**Certificate Validation:**
|
||||
- HTTPS certificates are validated by default
|
||||
- Don't disable certificate validation
|
||||
- Use valid, trusted certificates
|
||||
|
||||
### Process Security
|
||||
|
||||
**Least Privilege:**
|
||||
- Stdio servers run with user's permissions
|
||||
- Don't require elevated privileges
|
||||
- Validate all inputs from MCP protocol
|
||||
|
||||
**Sandboxing:**
|
||||
- Stdio servers are not sandboxed
|
||||
- Be cautious with user input
|
||||
- Validate/sanitize all data
|
||||
|
||||
## Debugging
|
||||
|
||||
### Enable Debug Logging
|
||||
|
||||
Set environment variables before starting Claude Code:
|
||||
|
||||
```bash
|
||||
export DEBUG=mcp:*
|
||||
export MCP_LOG_LEVEL=debug
|
||||
claude
|
||||
```
|
||||
|
||||
### Check Server Status
|
||||
|
||||
Within Claude Code:
|
||||
```
|
||||
/mcp
|
||||
```
|
||||
|
||||
Shows:
|
||||
- Registered servers
|
||||
- Connection status
|
||||
- Available tools/resources
|
||||
|
||||
### Test Server Manually
|
||||
|
||||
**Stdio Server:**
|
||||
```bash
|
||||
# Test command directly
|
||||
node ${CLAUDE_PLUGIN_ROOT}/servers/my-server.js
|
||||
|
||||
# With environment
|
||||
API_KEY=test node servers/my-server.js
|
||||
```
|
||||
|
||||
**HTTP Server:**
|
||||
```bash
|
||||
# Test endpoint
|
||||
curl -H "Authorization: Bearer ${API_TOKEN}" \
|
||||
https://api.example.com/mcp
|
||||
```
|
||||
|
||||
### Common Debug Scenarios
|
||||
|
||||
**Server Not Appearing:**
|
||||
1. Check plugin is enabled: `/plugin list`
|
||||
2. Verify config syntax: `cat .mcp.json | jq .`
|
||||
3. Restart Claude Code
|
||||
4. Check for error messages on startup
|
||||
|
||||
**Server Starts But No Tools:**
|
||||
1. Check server logs for initialization errors
|
||||
2. Verify server implements MCP protocol correctly
|
||||
3. Test server manually outside Claude Code
|
||||
4. Check server responds to `tools/list` request
|
||||
|
||||
**Environment Variables Not Expanding:**
|
||||
1. Verify syntax: `${VAR}` not `$VAR`
|
||||
2. Check variable is set: `echo $VAR`
|
||||
3. Restart Claude Code after setting variables
|
||||
4. Check for typos in variable names
|
||||
|
||||
## See Also
|
||||
|
||||
- [Main MCP Configuration Guide](skill.md)
|
||||
- [Real-World Examples](examples.md)
|
||||
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
|
||||
- [Claude Code Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
|
||||
306
claude-code/skills/mcp-config/skill.md
Normal file
306
claude-code/skills/mcp-config/skill.md
Normal file
@@ -0,0 +1,306 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user