Initial commit

skills/mcp-integration/references/authentication.md

@@ -0,0 +1,549 @@
+# MCP Authentication Patterns
+
+Complete guide to authentication methods for MCP servers in Claude Code plugins.
+
+## Overview
+
+MCP servers support multiple authentication methods depending on the server type and service requirements. Choose the method that best matches your use case and security requirements.
+
+## OAuth (Automatic)
+
+### How It Works
+
+Claude Code automatically handles the complete OAuth 2.0 flow for SSE and HTTP servers:
+
+1. User attempts to use MCP tool
+2. Claude Code detects authentication needed
+3. Opens browser for OAuth consent
+4. User authorizes in browser
+5. Tokens stored securely by Claude Code
+6. Automatic token refresh
+
+### Configuration
+
+```json
+{
+  "service": {
+    "type": "sse",
+    "url": "https://mcp.example.com/sse"
+  }
+}
+```
+
+No additional auth configuration needed! Claude Code handles everything.
+
+### Supported Services
+
+**Known OAuth-enabled MCP servers:**
+- Asana: `https://mcp.asana.com/sse`
+- GitHub (when available)
+- Google services (when available)
+- Custom OAuth servers
+
+### OAuth Scopes
+
+OAuth scopes are determined by the MCP server. Users see required scopes during the consent flow.
+
+**Document required scopes in your README:**
+```markdown
+## Authentication
+
+This plugin requires the following Asana permissions:
+- Read tasks and projects
+- Create and update tasks
+- Access workspace data
+```
+
+### Token Storage
+
+Tokens are stored securely by Claude Code:
+- Not accessible to plugins
+- Encrypted at rest
+- Automatic refresh
+- Cleared on sign-out
+
+### Troubleshooting OAuth
+
+**Authentication loop:**
+- Clear cached tokens (sign out and sign in)
+- Check OAuth redirect URLs
+- Verify server OAuth configuration
+
+**Scope issues:**
+- User may need to re-authorize for new scopes
+- Check server documentation for required scopes
+
+**Token expiration:**
+- Claude Code auto-refreshes
+- If refresh fails, prompts re-authentication
+
+## Token-Based Authentication
+
+### Bearer Tokens
+
+Most common for HTTP and WebSocket servers.
+
+**Configuration:**
+```json
+{
+  "api": {
+    "type": "http",
+    "url": "https://api.example.com/mcp",
+    "headers": {
+      "Authorization": "Bearer ${API_TOKEN}"
+    }
+  }
+}
+```
+
+**Environment variable:**
+```bash
+export API_TOKEN="your-secret-token-here"
+```
+
+### API Keys
+
+Alternative to Bearer tokens, often in custom headers.
+
+**Configuration:**
+```json
+{
+  "api": {
+    "type": "http",
+    "url": "https://api.example.com/mcp",
+    "headers": {
+      "X-API-Key": "${API_KEY}",
+      "X-API-Secret": "${API_SECRET}"
+    }
+  }
+}
+```
+
+### Custom Headers
+
+Services may use custom authentication headers.
+
+**Configuration:**
+```json
+{
+  "service": {
+    "type": "sse",
+    "url": "https://mcp.example.com/sse",
+    "headers": {
+      "X-Auth-Token": "${AUTH_TOKEN}",
+      "X-User-ID": "${USER_ID}",
+      "X-Tenant-ID": "${TENANT_ID}"
+    }
+  }
+}
+```
+
+### Documenting Token Requirements
+
+Always document in your README:
+
+```markdown
+## Setup
+
+### Required Environment Variables
+
+Set these environment variables before using the plugin:
+
+\`\`\`bash
+export API_TOKEN="your-token-here"
+export API_SECRET="your-secret-here"
+\`\`\`
+
+### Obtaining Tokens
+
+1. Visit https://api.example.com/tokens
+2. Create a new API token
+3. Copy the token and secret
+4. Set environment variables as shown above
+
+### Token Permissions
+
+The API token needs the following permissions:
+- Read access to resources
+- Write access for creating items
+- Delete access (optional, for cleanup operations)
+\`\`\`
+```
+
+## Environment Variable Authentication (stdio)
+
+### Passing Credentials to Server
+
+For stdio servers, pass credentials via environment variables:
+
+```json
+{
+  "database": {
+    "command": "python",
+    "args": ["-m", "mcp_server_db"],
+    "env": {
+      "DATABASE_URL": "${DATABASE_URL}",
+      "DB_USER": "${DB_USER}",
+      "DB_PASSWORD": "${DB_PASSWORD}"
+    }
+  }
+}
+```
+
+### User Environment Variables
+
+```bash
+# User sets these in their shell
+export DATABASE_URL="postgresql://localhost/mydb"
+export DB_USER="myuser"
+export DB_PASSWORD="mypassword"
+```
+
+### Documentation Template
+
+```markdown
+## Database Configuration
+
+Set these environment variables:
+
+\`\`\`bash
+export DATABASE_URL="postgresql://host:port/database"
+export DB_USER="username"
+export DB_PASSWORD="password"
+\`\`\`
+
+Or create a `.env` file (add to `.gitignore`):
+
+\`\`\`
+DATABASE_URL=postgresql://localhost:5432/mydb
+DB_USER=myuser
+DB_PASSWORD=mypassword
+\`\`\`
+
+Load with: \`source .env\` or \`export $(cat .env | xargs)\`
+\`\`\`
+```
+
+## Dynamic Headers
+
+### Headers Helper Script
+
+For tokens that change or expire, use a helper script:
+
+```json
+{
+  "api": {
+    "type": "sse",
+    "url": "https://api.example.com",
+    "headersHelper": "${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh"
+  }
+}
+```
+
+**Script (get-headers.sh):**
+```bash
+#!/bin/bash
+# Generate dynamic authentication headers
+
+# Fetch fresh token
+TOKEN=$(get-fresh-token-from-somewhere)
+
+# Output JSON headers
+cat <<EOF
+{
+  "Authorization": "Bearer $TOKEN",
+  "X-Timestamp": "$(date -Iseconds)"
+}
+EOF
+```
+
+### Use Cases for Dynamic Headers
+
+- Short-lived tokens that need refresh
+- Tokens with HMAC signatures
+- Time-based authentication
+- Dynamic tenant/workspace selection
+
+## Security Best Practices
+
+### DO
+
+✅ **Use environment variables:**
+```json
+{
+  "headers": {
+    "Authorization": "Bearer ${API_TOKEN}"
+  }
+}
+```
+
+✅ **Document required variables in README**
+
+✅ **Use HTTPS/WSS always**
+
+✅ **Implement token rotation**
+
+✅ **Store tokens securely (env vars, not files)**
+
+✅ **Let OAuth handle authentication when available**
+
+### DON'T
+
+❌ **Hardcode tokens:**
+```json
+{
+  "headers": {
+    "Authorization": "Bearer sk-abc123..."  // NEVER!
+  }
+}
+```
+
+❌ **Commit tokens to git**
+
+❌ **Share tokens in documentation**
+
+❌ **Use HTTP instead of HTTPS**
+
+❌ **Store tokens in plugin files**
+
+❌ **Log tokens or sensitive headers**
+
+## Multi-Tenancy Patterns
+
+### Workspace/Tenant Selection
+
+**Via environment variable:**
+```json
+{
+  "api": {
+    "type": "http",
+    "url": "https://api.example.com/mcp",
+    "headers": {
+      "Authorization": "Bearer ${API_TOKEN}",
+      "X-Workspace-ID": "${WORKSPACE_ID}"
+    }
+  }
+}
+```
+
+**Via URL:**
+```json
+{
+  "api": {
+    "type": "http",
+    "url": "https://${TENANT_ID}.api.example.com/mcp"
+  }
+}
+```
+
+### Per-User Configuration
+
+Users set their own workspace:
+
+```bash
+export WORKSPACE_ID="my-workspace-123"
+export TENANT_ID="my-company"
+```
+
+## Authentication Troubleshooting
+
+### Common Issues
+
+**401 Unauthorized:**
+- Check token is set correctly
+- Verify token hasn't expired
+- Check token has required permissions
+- Ensure header format is correct
+
+**403 Forbidden:**
+- Token valid but lacks permissions
+- Check scope/permissions
+- Verify workspace/tenant ID
+- May need admin approval
+
+**Token not found:**
+```bash
+# Check environment variable is set
+echo $API_TOKEN
+
+# If empty, set it
+export API_TOKEN="your-token"
+```
+
+**Token in wrong format:**
+```json
+// Correct
+"Authorization": "Bearer sk-abc123"
+
+// Wrong
+"Authorization": "sk-abc123"
+```
+
+### Debugging Authentication
+
+**Enable debug mode:**
+```bash
+claude --debug
+```
+
+Look for:
+- Authentication header values (sanitized)
+- OAuth flow progress
+- Token refresh attempts
+- Authentication errors
+
+**Test authentication separately:**
+```bash
+# Test HTTP endpoint
+curl -H "Authorization: Bearer $API_TOKEN" \
+     https://api.example.com/mcp/health
+
+# Should return 200 OK
+```
+
+## Migration Patterns
+
+### From Hardcoded to Environment Variables
+
+**Before:**
+```json
+{
+  "headers": {
+    "Authorization": "Bearer sk-hardcoded-token"
+  }
+}
+```
+
+**After:**
+```json
+{
+  "headers": {
+    "Authorization": "Bearer ${API_TOKEN}"
+  }
+}
+```
+
+**Migration steps:**
+1. Add environment variable to plugin README
+2. Update configuration to use ${VAR}
+3. Test with variable set
+4. Remove hardcoded value
+5. Commit changes
+
+### From Basic Auth to OAuth
+
+**Before:**
+```json
+{
+  "headers": {
+    "Authorization": "Basic ${BASE64_CREDENTIALS}"
+  }
+}
+```
+
+**After:**
+```json
+{
+  "type": "sse",
+  "url": "https://mcp.example.com/sse"
+}
+```
+
+**Benefits:**
+- Better security
+- No credential management
+- Automatic token refresh
+- Scoped permissions
+
+## Advanced Authentication
+
+### Mutual TLS (mTLS)
+
+Some enterprise services require client certificates.
+
+**Not directly supported in MCP configuration.**
+
+**Workaround:** Wrap in stdio server that handles mTLS:
+
+```json
+{
+  "secure-api": {
+    "command": "${CLAUDE_PLUGIN_ROOT}/servers/mtls-wrapper",
+    "args": ["--cert", "${CLIENT_CERT}", "--key", "${CLIENT_KEY}"],
+    "env": {
+      "API_URL": "https://secure.example.com"
+    }
+  }
+}
+```
+
+### JWT Tokens
+
+Generate JWT tokens dynamically with headers helper:
+
+```bash
+#!/bin/bash
+# generate-jwt.sh
+
+# Generate JWT (using library or API call)
+JWT=$(generate-jwt-token)
+
+echo "{\"Authorization\": \"Bearer $JWT\"}"
+```
+
+```json
+{
+  "headersHelper": "${CLAUDE_PLUGIN_ROOT}/scripts/generate-jwt.sh"
+}
+```
+
+### HMAC Signatures
+
+For APIs requiring request signing:
+
+```bash
+#!/bin/bash
+# generate-hmac.sh
+
+TIMESTAMP=$(date -Iseconds)
+SIGNATURE=$(echo -n "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)
+
+cat <<EOF
+{
+  "X-Timestamp": "$TIMESTAMP",
+  "X-Signature": "$SIGNATURE",
+  "X-API-Key": "$API_KEY"
+}
+EOF
+```
+
+## Best Practices Summary
+
+### For Plugin Developers
+
+1. **Prefer OAuth** when service supports it
+2. **Use environment variables** for tokens
+3. **Document all required variables** in README
+4. **Provide setup instructions** with examples
+5. **Never commit credentials**
+6. **Use HTTPS/WSS only**
+7. **Test authentication thoroughly**
+
+### For Plugin Users
+
+1. **Set environment variables** before using plugin
+2. **Keep tokens secure** and private
+3. **Rotate tokens regularly**
+4. **Use different tokens** for dev/prod
+5. **Don't commit .env files** to git
+6. **Review OAuth scopes** before authorizing
+
+## Conclusion
+
+Choose the authentication method that matches your MCP server's requirements:
+- **OAuth** for cloud services (easiest for users)
+- **Bearer tokens** for API services
+- **Environment variables** for stdio servers
+- **Dynamic headers** for complex auth flows
+
+Always prioritize security and provide clear setup documentation for users.

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.

skills/mcp-integration/references/tool-usage.md

@@ -0,0 +1,538 @@
+# Using MCP Tools in Commands and Agents
+
+Complete guide to using MCP tools effectively in Claude Code plugin commands and agents.
+
+## Overview
+
+Once an MCP server is configured, its tools become available with the prefix `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`. Use these tools in commands and agents just like built-in Claude Code tools.
+
+## Tool Naming Convention
+
+### Format
+
+```
+mcp__plugin_<plugin-name>_<server-name>__<tool-name>
+```
+
+### Examples
+
+**Asana plugin with asana server:**
+- `mcp__plugin_asana_asana__asana_create_task`
+- `mcp__plugin_asana_asana__asana_search_tasks`
+- `mcp__plugin_asana_asana__asana_get_project`
+
+**Custom plugin with database server:**
+- `mcp__plugin_myplug_database__query`
+- `mcp__plugin_myplug_database__execute`
+- `mcp__plugin_myplug_database__list_tables`
+
+### Discovering Tool Names
+
+**Use `/mcp` command:**
+```bash
+/mcp
+```
+
+This shows:
+- All available MCP servers
+- Tools provided by each server
+- Tool schemas and descriptions
+- Full tool names for use in configuration
+
+## Using Tools in Commands
+
+### Pre-Allowing Tools
+
+Specify MCP tools in command frontmatter:
+
+```markdown
+---
+description: Create a new Asana task
+allowed-tools: [
+  "mcp__plugin_asana_asana__asana_create_task"
+]
+---
+
+# Create Task Command
+
+To create a task:
+1. Gather task details from user
+2. Use mcp__plugin_asana_asana__asana_create_task with the details
+3. Confirm creation to user
+```
+
+### Multiple Tools
+
+```markdown
+---
+allowed-tools: [
+  "mcp__plugin_asana_asana__asana_create_task",
+  "mcp__plugin_asana_asana__asana_search_tasks",
+  "mcp__plugin_asana_asana__asana_get_project"
+]
+---
+```
+
+### Wildcard (Use Sparingly)
+
+```markdown
+---
+allowed-tools: ["mcp__plugin_asana_asana__*"]
+---
+```
+
+**Caution:** Only use wildcards if the command truly needs access to all tools from a server.
+
+### Tool Usage in Command Instructions
+
+**Example command:**
+```markdown
+---
+description: Search and create Asana tasks
+allowed-tools: [
+  "mcp__plugin_asana_asana__asana_search_tasks",
+  "mcp__plugin_asana_asana__asana_create_task"
+]
+---
+
+# Asana Task Management
+
+## Searching Tasks
+
+To search for tasks:
+1. Use mcp__plugin_asana_asana__asana_search_tasks
+2. Provide search filters (assignee, project, etc.)
+3. Display results to user
+
+## Creating Tasks
+
+To create a task:
+1. Gather task details:
+   - Title (required)
+   - Description
+   - Project
+   - Assignee
+   - Due date
+2. Use mcp__plugin_asana_asana__asana_create_task
+3. Show confirmation with task link
+```
+
+## Using Tools in Agents
+
+### Agent Configuration
+
+Agents can use MCP tools autonomously without pre-allowing them:
+
+```markdown
+---
+name: asana-status-updater
+description: This agent should be used when the user asks to "update Asana status", "generate project report", or "sync Asana tasks"
+model: inherit
+color: blue
+---
+
+## Role
+
+Autonomous agent for generating Asana project status reports.
+
+## Process
+
+1. **Query tasks**: Use mcp__plugin_asana_asana__asana_search_tasks to get all tasks
+2. **Analyze progress**: Calculate completion rates and identify blockers
+3. **Generate report**: Create formatted status update
+4. **Update Asana**: Use mcp__plugin_asana_asana__asana_create_comment to post report
+
+## Available Tools
+
+The agent has access to all Asana MCP tools without pre-approval.
+```
+
+### Agent Tool Access
+
+Agents have broader tool access than commands:
+- Can use any tool Claude determines is necessary
+- Don't need pre-allowed lists
+- Should document which tools they typically use
+
+## Tool Call Patterns
+
+### Pattern 1: Simple Tool Call
+
+Single tool call with validation:
+
+```markdown
+Steps:
+1. Validate user provided required fields
+2. Call mcp__plugin_api_server__create_item with validated data
+3. Check for errors
+4. Display confirmation
+```
+
+### Pattern 2: Sequential Tools
+
+Chain multiple tool calls:
+
+```markdown
+Steps:
+1. Search for existing items: mcp__plugin_api_server__search
+2. If not found, create new: mcp__plugin_api_server__create
+3. Add metadata: mcp__plugin_api_server__update_metadata
+4. Return final item ID
+```
+
+### Pattern 3: Batch Operations
+
+Multiple calls with same tool:
+
+```markdown
+Steps:
+1. Get list of items to process
+2. For each item:
+   - Call mcp__plugin_api_server__update_item
+   - Track success/failure
+3. Report results summary
+```
+
+### Pattern 4: Error Handling
+
+Graceful error handling:
+
+```markdown
+Steps:
+1. Try to call mcp__plugin_api_server__get_data
+2. If error (rate limit, network, etc.):
+   - Wait and retry (max 3 attempts)
+   - If still failing, inform user
+   - Suggest checking configuration
+3. On success, process data
+```
+
+## Tool Parameters
+
+### Understanding Tool Schemas
+
+Each MCP tool has a schema defining its parameters. View with `/mcp`.
+
+**Example schema:**
+```json
+{
+  "name": "asana_create_task",
+  "description": "Create a new Asana task",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "description": "Task title"
+      },
+      "notes": {
+        "type": "string",
+        "description": "Task description"
+      },
+      "workspace": {
+        "type": "string",
+        "description": "Workspace GID"
+      }
+    },
+    "required": ["name", "workspace"]
+  }
+}
+```
+
+### Calling Tools with Parameters
+
+Claude automatically structures tool calls based on schema:
+
+```typescript
+// Claude generates this internally
+{
+  toolName: "mcp__plugin_asana_asana__asana_create_task",
+  input: {
+    name: "Review PR #123",
+    notes: "Code review for new feature",
+    workspace: "12345",
+    assignee: "67890",
+    due_on: "2025-01-15"
+  }
+}
+```
+
+### Parameter Validation
+
+**In commands, validate before calling:**
+
+```markdown
+Steps:
+1. Check required parameters:
+   - Title is not empty
+   - Workspace ID is provided
+   - Due date is valid format (YYYY-MM-DD)
+2. If validation fails, ask user to provide missing data
+3. If validation passes, call MCP tool
+4. Handle tool errors gracefully
+```
+
+## Response Handling
+
+### Success Responses
+
+```markdown
+Steps:
+1. Call MCP tool
+2. On success:
+   - Extract relevant data from response
+   - Format for user display
+   - Provide confirmation message
+   - Include relevant links or IDs
+```
+
+### Error Responses
+
+```markdown
+Steps:
+1. Call MCP tool
+2. On error:
+   - Check error type (auth, rate limit, validation, etc.)
+   - Provide helpful error message
+   - Suggest remediation steps
+   - Don't expose internal error details to user
+```
+
+### Partial Success
+
+```markdown
+Steps:
+1. Batch operation with multiple MCP calls
+2. Track successes and failures separately
+3. Report summary:
+   - "Successfully processed 8 of 10 items"
+   - "Failed items: [item1, item2] due to [reason]"
+   - Suggest retry or manual intervention
+```
+
+## Performance Optimization
+
+### Batching Requests
+
+**Good: Single query with filters**
+```markdown
+Steps:
+1. Call mcp__plugin_api_server__search with filters:
+   - project_id: "123"
+   - status: "active"
+   - limit: 100
+2. Process all results
+```
+
+**Avoid: Many individual queries**
+```markdown
+Steps:
+1. For each item ID:
+   - Call mcp__plugin_api_server__get_item
+   - Process item
+```
+
+### Caching Results
+
+```markdown
+Steps:
+1. Call expensive MCP operation: mcp__plugin_api_server__analyze
+2. Store results in variable for reuse
+3. Use cached results for subsequent operations
+4. Only re-fetch if data changes
+```
+
+### Parallel Tool Calls
+
+When tools don't depend on each other, call in parallel:
+
+```markdown
+Steps:
+1. Make parallel calls (Claude handles this automatically):
+   - mcp__plugin_api_server__get_project
+   - mcp__plugin_api_server__get_users
+   - mcp__plugin_api_server__get_tags
+2. Wait for all to complete
+3. Combine results
+```
+
+## Integration Best Practices
+
+### User Experience
+
+**Provide feedback:**
+```markdown
+Steps:
+1. Inform user: "Searching Asana tasks..."
+2. Call mcp__plugin_asana_asana__asana_search_tasks
+3. Show progress: "Found 15 tasks, analyzing..."
+4. Present results
+```
+
+**Handle long operations:**
+```markdown
+Steps:
+1. Warn user: "This may take a minute..."
+2. Break into smaller steps with updates
+3. Show incremental progress
+4. Final summary when complete
+```
+
+### Error Messages
+
+**Good error messages:**
+```
+❌ "Could not create task. Please check:
+   1. You're logged into Asana
+   2. You have access to workspace 'Engineering'
+   3. The project 'Q1 Goals' exists"
+```
+
+**Poor error messages:**
+```
+❌ "Error: MCP tool returned 403"
+```
+
+### Documentation
+
+**Document MCP tool usage in command:**
+```markdown
+## MCP Tools Used
+
+This command uses the following Asana MCP tools:
+- **asana_search_tasks**: Search for tasks matching criteria
+- **asana_create_task**: Create new task with details
+- **asana_update_task**: Update existing task properties
+
+Ensure you're authenticated to Asana before running this command.
+```
+
+## Testing Tool Usage
+
+### Local Testing
+
+1. **Configure MCP server** in `.mcp.json`
+2. **Install plugin locally** in `.claude-plugin/`
+3. **Verify tools available** with `/mcp`
+4. **Test command** that uses tools
+5. **Check debug output**: `claude --debug`
+
+### Test Scenarios
+
+**Test successful calls:**
+```markdown
+Steps:
+1. Create test data in external service
+2. Run command that queries this data
+3. Verify correct results returned
+```
+
+**Test error cases:**
+```markdown
+Steps:
+1. Test with missing authentication
+2. Test with invalid parameters
+3. Test with non-existent resources
+4. Verify graceful error handling
+```
+
+**Test edge cases:**
+```markdown
+Steps:
+1. Test with empty results
+2. Test with maximum results
+3. Test with special characters
+4. Test with concurrent access
+```
+
+## Common Patterns
+
+### Pattern: CRUD Operations
+
+```markdown
+---
+allowed-tools: [
+  "mcp__plugin_api_server__create_item",
+  "mcp__plugin_api_server__read_item",
+  "mcp__plugin_api_server__update_item",
+  "mcp__plugin_api_server__delete_item"
+]
+---
+
+# Item Management
+
+## Create
+Use create_item with required fields...
+
+## Read
+Use read_item with item ID...
+
+## Update
+Use update_item with item ID and changes...
+
+## Delete
+Use delete_item with item ID (ask for confirmation first)...
+```
+
+### Pattern: Search and Process
+
+```markdown
+Steps:
+1. **Search**: mcp__plugin_api_server__search with filters
+2. **Filter**: Apply additional local filtering if needed
+3. **Transform**: Process each result
+4. **Present**: Format and display to user
+```
+
+### Pattern: Multi-Step Workflow
+
+```markdown
+Steps:
+1. **Setup**: Gather all required information
+2. **Validate**: Check data completeness
+3. **Execute**: Chain of MCP tool calls:
+   - Create parent resource
+   - Create child resources
+   - Link resources together
+   - Add metadata
+4. **Verify**: Confirm all steps succeeded
+5. **Report**: Provide summary to user
+```
+
+## Troubleshooting
+
+### Tools Not Available
+
+**Check:**
+- MCP server configured correctly
+- Server connected (check `/mcp`)
+- Tool names match exactly (case-sensitive)
+- Restart Claude Code after config changes
+
+### Tool Calls Failing
+
+**Check:**
+- Authentication is valid
+- Parameters match tool schema
+- Required parameters provided
+- Check `claude --debug` logs
+
+### Performance Issues
+
+**Check:**
+- Batching queries instead of individual calls
+- Caching results when appropriate
+- Not making unnecessary tool calls
+- Parallel calls when possible
+
+## Conclusion
+
+Effective MCP tool usage requires:
+1. **Understanding tool schemas** via `/mcp`
+2. **Pre-allowing tools** in commands appropriately
+3. **Handling errors gracefully**
+4. **Optimizing performance** with batching and caching
+5. **Providing good UX** with feedback and clear errors
+6. **Testing thoroughly** before deployment
+
+Follow these patterns for robust MCP tool integration in your plugin commands and agents.