This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.
version
0.1.0
MCP Integration for Claude Code Plugins
Overview
Model Context Protocol (MCP) enables Claude Code plugins to integrate with external services and APIs by providing structured tool access. Use MCP integration to expose external service capabilities as tools within Claude Code.
Key capabilities:
Connect to external services (databases, APIs, file systems)
Provide 10+ related tools from a single service
Handle OAuth and complex authentication flows
Bundle MCP servers with plugins for automatic setup
# Good: Single query with filters
tasks = search_tasks(project="X", assignee="me", limit=50)
# Avoid: Many individual queries
for id in task_ids:
task = get_task(id)
Testing MCP Integration
Local Testing
Configure MCP server in .mcp.json
Install plugin locally (.claude-plugin/)
Run /mcp to verify server appears
Test tool calls in commands
Check claude --debug logs for connection issues
Validation Checklist
MCP configuration is valid JSON
Server URL is correct and accessible
Required environment variables documented
Tools appear in /mcp output
Authentication works (OAuth or tokens)
Tool calls succeed from commands
Error cases handled gracefully
Debugging
Enable Debug Logging
claude --debug
Look for:
MCP server connection attempts
Tool discovery logs
Authentication flows
Tool call errors
Common Issues
Server not connecting:
Check URL is correct
Verify server is running (stdio)
Check network connectivity
Review authentication configuration
Tools not available:
Verify server connected successfully
Check tool names match exactly
Run /mcp to see available tools
Restart Claude Code after config changes
Authentication failing:
Clear cached auth tokens
Re-authenticate
Check token scopes and permissions
Verify environment variables set
Quick Reference
MCP Server Types
Type
Transport
Best For
Auth
stdio
Process
Local tools, custom servers
Env vars
SSE
HTTP
Hosted services, cloud APIs
OAuth
HTTP
REST
API backends, token auth
Tokens
ws
WebSocket
Real-time, streaming
Tokens
Configuration Checklist
Server type specified (stdio/SSE/HTTP/ws)
Type-specific fields complete (command or url)
Authentication configured
Environment variables documented
HTTPS/WSS used (not HTTP/WS)
${CLAUDE_PLUGIN_ROOT} used for paths
Best Practices
DO:
✅ Use ${CLAUDE_PLUGIN_ROOT} for portable paths
✅ Document required environment variables
✅ Use secure connections (HTTPS/WSS)
✅ Pre-allow specific MCP tools in commands
✅ Test MCP integration before publishing
✅ Handle connection and tool errors gracefully
DON'T:
❌ Hardcode absolute paths
❌ Commit credentials to git
❌ Use HTTP instead of HTTPS
❌ Pre-allow all tools with wildcards
❌ Skip error handling
❌ Forget to document setup
Additional Resources
Reference Files
For detailed information, consult:
references/server-types.md - Deep dive on each server type
references/authentication.md - Authentication patterns and OAuth
references/tool-usage.md - Using MCP tools in commands and agents
