From 898b52edcb47bcb3e9d6106e74ca73e74ea01e70 Mon Sep 17 00:00:00 2001 From: sillylaird Date: Thu, 3 Sep 2026 00:33:59 +0000 Subject: import live www.sillylaird.ca webroot --- .../mcp-integration/references/server-types.md | 536 +++++++++++++++++++++ 1 file changed, 536 insertions(+) create mode 100644 .agents/skills/mcp-integration/references/server-types.md (limited to '.agents/skills/mcp-integration/references/server-types.md') diff --git a/.agents/skills/mcp-integration/references/server-types.md b/.agents/skills/mcp-integration/references/server-types.md new file mode 100644 index 0000000..4528953 --- /dev/null +++ b/.agents/skills/mcp-integration/references/server-types.md @@ -0,0 +1,536 @@ +# MCP Server Types: Deep Dive + +Complete reference for all MCP server types supported in Claude Code plugins. + +## stdio (Standard Input/Output) + +### Overview + +Execute local MCP servers as child processes with communication via stdin/stdout. Best choice for local tools, custom servers, and NPM packages. + +### Configuration + +**Basic:** +```json +{ + "my-server": { + "command": "npx", + "args": ["-y", "my-mcp-server"] + } +} +``` + +**With environment:** +```json +{ + "my-server": { + "command": "${CLAUDE_PLUGIN_ROOT}/servers/custom-server", + "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"], + "env": { + "API_KEY": "${MY_API_KEY}", + "LOG_LEVEL": "debug", + "DATABASE_URL": "${DB_URL}" + } + } +} +``` + +### Process Lifecycle + +1. **Startup**: Claude Code spawns process with `command` and `args` +2. **Communication**: JSON-RPC messages via stdin/stdout +3. **Lifecycle**: Process runs for entire Claude Code session +4. **Shutdown**: Process terminated when Claude Code exits + +### Use Cases + +**NPM Packages:** +```json +{ + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] + } +} +``` + +**Custom Scripts:** +```json +{ + "custom": { + "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server.js", + "args": ["--verbose"] + } +} +``` + +**Python Servers:** +```json +{ + "python-server": { + "command": "python", + "args": ["-m", "my_mcp_server"], + "env": { + "PYTHONUNBUFFERED": "1" + } + } +} +``` + +### Best Practices + +1. **Use absolute paths or ${CLAUDE_PLUGIN_ROOT}** +2. **Set PYTHONUNBUFFERED for Python servers** +3. **Pass configuration via args or env, not stdin** +4. **Handle server crashes gracefully** +5. **Log to stderr, not stdout (stdout is for MCP protocol)** + +### Troubleshooting + +**Server won't start:** +- Check command exists and is executable +- Verify file paths are correct +- Check permissions +- Review `claude --debug` logs + +**Communication fails:** +- Ensure server uses stdin/stdout correctly +- Check for stray print/console.log statements +- Verify JSON-RPC format + +## SSE (Server-Sent Events) + +### Overview + +Connect to hosted MCP servers via HTTP with server-sent events for streaming. Best for cloud services and OAuth authentication. + +### Configuration + +**Basic:** +```json +{ + "hosted-service": { + "type": "sse", + "url": "https://mcp.example.com/sse" + } +} +``` + +**With headers:** +```json +{ + "service": { + "type": "sse", + "url": "https://mcp.example.com/sse", + "headers": { + "X-API-Version": "v1", + "X-Client-ID": "${CLIENT_ID}" + } + } +} +``` + +### Connection Lifecycle + +1. **Initialization**: HTTP connection established to URL +2. **Handshake**: MCP protocol negotiation +3. **Streaming**: Server sends events via SSE +4. **Requests**: Client sends HTTP POST for tool calls +5. **Reconnection**: Automatic reconnection on disconnect + +### Authentication + +**OAuth (Automatic):** +```json +{ + "asana": { + "type": "sse", + "url": "https://mcp.asana.com/sse" + } +} +``` + +Claude Code handles OAuth flow: +1. User prompted to authenticate on first use +2. Opens browser for OAuth flow +3. Tokens stored securely +4. Automatic token refresh + +**Custom Headers:** +```json +{ + "service": { + "type": "sse", + "url": "https://mcp.example.com/sse", + "headers": { + "Authorization": "Bearer ${API_TOKEN}" + } + } +} +``` + +### Use Cases + +**Official Services:** +- Asana: `https://mcp.asana.com/sse` +- GitHub: `https://mcp.github.com/sse` +- Other hosted MCP servers + +**Custom Hosted Servers:** +Deploy your own MCP server and expose via HTTPS + SSE. + +### Best Practices + +1. **Always use HTTPS, never HTTP** +2. **Let OAuth handle authentication when available** +3. **Use environment variables for tokens** +4. **Handle connection failures gracefully** +5. **Document OAuth scopes required** + +### Troubleshooting + +**Connection refused:** +- Check URL is correct and accessible +- Verify HTTPS certificate is valid +- Check network connectivity +- Review firewall settings + +**OAuth fails:** +- Clear cached tokens +- Check OAuth scopes +- Verify redirect URLs +- Re-authenticate + +## HTTP (REST API) + +### Overview + +Connect to RESTful MCP servers via standard HTTP requests. Best for token-based auth and stateless interactions. + +### Configuration + +**Basic:** +```json +{ + "api": { + "type": "http", + "url": "https://api.example.com/mcp" + } +} +``` + +**With authentication:** +```json +{ + "api": { + "type": "http", + "url": "https://api.example.com/mcp", + "headers": { + "Authorization": "Bearer ${API_TOKEN}", + "Content-Type": "application/json", + "X-API-Version": "2024-01-01" + } + } +} +``` + +### Request/Response Flow + +1. **Tool Discovery**: GET to discover available tools +2. **Tool Invocation**: POST with tool name and parameters +3. **Response**: JSON response with results or errors +4. **Stateless**: Each request independent + +### Authentication + +**Token-Based:** +```json +{ + "headers": { + "Authorization": "Bearer ${API_TOKEN}" + } +} +``` + +**API Key:** +```json +{ + "headers": { + "X-API-Key": "${API_KEY}" + } +} +``` + +**Custom Auth:** +```json +{ + "headers": { + "X-Auth-Token": "${AUTH_TOKEN}", + "X-User-ID": "${USER_ID}" + } +} +``` + +### Use Cases + +- REST API backends +- Internal services +- Microservices +- Serverless functions + +### Best Practices + +1. **Use HTTPS for all connections** +2. **Store tokens in environment variables** +3. **Implement retry logic for transient failures** +4. **Handle rate limiting** +5. **Set appropriate timeouts** + +### Troubleshooting + +**HTTP errors:** +- 401: Check authentication headers +- 403: Verify permissions +- 429: Implement rate limiting +- 500: Check server logs + +**Timeout issues:** +- Increase timeout if needed +- Check server performance +- Optimize tool implementations + +## WebSocket (Real-time) + +### Overview + +Connect to MCP servers via WebSocket for real-time bidirectional communication. Best for streaming and low-latency applications. + +### Configuration + +**Basic:** +```json +{ + "realtime": { + "type": "ws", + "url": "wss://mcp.example.com/ws" + } +} +``` + +**With authentication:** +```json +{ + "realtime": { + "type": "ws", + "url": "wss://mcp.example.com/ws", + "headers": { + "Authorization": "Bearer ${TOKEN}", + "X-Client-ID": "${CLIENT_ID}" + } + } +} +``` + +### Connection Lifecycle + +1. **Handshake**: WebSocket upgrade request +2. **Connection**: Persistent bidirectional channel +3. **Messages**: JSON-RPC over WebSocket +4. **Heartbeat**: Keep-alive messages +5. **Reconnection**: Automatic on disconnect + +### Use Cases + +- Real-time data streaming +- Live updates and notifications +- Collaborative editing +- Low-latency tool calls +- Push notifications from server + +### Best Practices + +1. **Use WSS (secure WebSocket), never WS** +2. **Implement heartbeat/ping-pong** +3. **Handle reconnection logic** +4. **Buffer messages during disconnection** +5. **Set connection timeouts** + +### Troubleshooting + +**Connection drops:** +- Implement reconnection logic +- Check network stability +- Verify server supports WebSocket +- Review firewall settings + +**Message delivery:** +- Implement message acknowledgment +- Handle out-of-order messages +- Buffer during disconnection + +## Comparison Matrix + +| Feature | stdio | SSE | HTTP | WebSocket | +|---------|-------|-----|------|-----------| +| **Transport** | Process | HTTP/SSE | HTTP | WebSocket | +| **Direction** | Bidirectional | Server→Client | Request/Response | Bidirectional | +| **State** | Stateful | Stateful | Stateless | Stateful | +| **Auth** | Env vars | OAuth/Headers | Headers | Headers | +| **Use Case** | Local tools | Cloud services | REST APIs | Real-time | +| **Latency** | Lowest | Medium | Medium | Low | +| **Setup** | Easy | Medium | Easy | Medium | +| **Reconnect** | Process respawn | Automatic | N/A | Automatic | + +## Choosing the Right Type + +**Use stdio when:** +- Running local tools or custom servers +- Need lowest latency +- Working with file systems or local databases +- Distributing server with plugin + +**Use SSE when:** +- Connecting to hosted services +- Need OAuth authentication +- Using official MCP servers (Asana, GitHub) +- Want automatic reconnection + +**Use HTTP when:** +- Integrating with REST APIs +- Need stateless interactions +- Using token-based auth +- Simple request/response pattern + +**Use WebSocket when:** +- Need real-time updates +- Building collaborative features +- Low-latency critical +- Bi-directional streaming required + +## Migration Between Types + +### From stdio to SSE + +**Before (stdio):** +```json +{ + "local-server": { + "command": "node", + "args": ["server.js"] + } +} +``` + +**After (SSE - deploy server):** +```json +{ + "hosted-server": { + "type": "sse", + "url": "https://mcp.example.com/sse" + } +} +``` + +### From HTTP to WebSocket + +**Before (HTTP):** +```json +{ + "api": { + "type": "http", + "url": "https://api.example.com/mcp" + } +} +``` + +**After (WebSocket):** +```json +{ + "realtime": { + "type": "ws", + "url": "wss://api.example.com/ws" + } +} +``` + +Benefits: Real-time updates, lower latency, bi-directional communication. + +## Advanced Configuration + +### Multiple Servers + +Combine different types: + +```json +{ + "local-db": { + "command": "npx", + "args": ["-y", "mcp-server-sqlite", "./data.db"] + }, + "cloud-api": { + "type": "sse", + "url": "https://mcp.example.com/sse" + }, + "internal-service": { + "type": "http", + "url": "https://api.example.com/mcp", + "headers": { + "Authorization": "Bearer ${API_TOKEN}" + } + } +} +``` + +### Conditional Configuration + +Use environment variables to switch servers: + +```json +{ + "api": { + "type": "http", + "url": "${API_URL}", + "headers": { + "Authorization": "Bearer ${API_TOKEN}" + } + } +} +``` + +Set different values for dev/prod: +- Dev: `API_URL=http://localhost:8080/mcp` +- Prod: `API_URL=https://api.production.com/mcp` + +## Security Considerations + +### Stdio Security + +- Validate command paths +- Don't execute user-provided commands +- Limit environment variable access +- Restrict file system access + +### Network Security + +- Always use HTTPS/WSS +- Validate SSL certificates +- Don't skip certificate verification +- Use secure token storage + +### Token Management + +- Never hardcode tokens +- Use environment variables +- Rotate tokens regularly +- Implement token refresh +- Document scopes required + +## Conclusion + +Choose the MCP server type based on your use case: +- **stdio** for local, custom, or NPM-packaged servers +- **SSE** for hosted services with OAuth +- **HTTP** for REST APIs with token auth +- **WebSocket** for real-time bidirectional communication + +Test thoroughly and handle errors gracefully for robust MCP integration. -- cgit v1.2.3