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

# 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/)