SuperClaude/docs/user-guide/mcp-servers.md

SuperClaude MCP Servers Guide 🔌

Overview

MCP (Model Context Protocol) servers extend Claude Code's capabilities through specialized tools. SuperClaude integrates 8 MCP servers and provides Claude with instructions on when to activate them based on your tasks.

🔍 Reality Check

• What MCP servers are: External Node.js processes that provide additional tools
• What they aren't: Built-in SuperClaude functionality
• How activation works: Claude reads instructions to use appropriate servers based on context
• What they provide: Real tools that extend Claude Code's native capabilities

Core Servers:

• context7: Official library documentation and patterns
• sequential-thinking: Multi-step reasoning and analysis
• magic: Modern UI component generation
• playwright: Browser automation and E2E testing
• morphllm-fast-apply: Pattern-based code transformations
• serena: Semantic code understanding and project memory
• tavily: Web search and real-time information retrieval
• chrome-devtools: Performance analysis and debugging

Quick Start

Setup Verification: MCP servers activate automatically. For installation and troubleshooting, see Installation Guide and Troubleshooting.

Auto-Activation Logic:

Request Contains	Servers Activated
Library imports, API names	context7
--think, debugging	sequential-thinking
component, UI, frontend	magic
test, e2e, browser	playwright
Multi-file edits, refactoring	morphllm-fast-apply
Large projects, sessions	serena
/sc:research, latest, current	tavily
performance, debug, LCP	chrome-devtools

Server Details

context7 📚

Purpose: Official library documentation access Triggers: Import statements, framework keywords, documentation requests Requirements: Node.js 16+, no API key

# Automatic activation
/sc:implement "React authentication system"
# → Provides official React patterns

# Manual activation  
/sc:analyze auth-system/ --c7

sequential-thinking 🧠

Purpose: Structured multi-step reasoning and systematic analysis Triggers: Complex debugging, --think flags, architectural analysis Requirements: Node.js 16+, no API key

# Automatic activation
/sc:troubleshoot "API performance issues"
# → Enables systematic root cause analysis

# Manual activation
/sc:analyze --think-hard architecture/

magic ✨

Purpose: Modern UI component generation from 21st.dev patterns Triggers: UI requests, /ui commands, component development Requirements: Node.js 16+, TWENTYFIRST_API_KEY ()

# Automatic activation
/sc:implement "responsive dashboard component"
# → Generates accessible UI with modern patterns

# API key setup
export TWENTYFIRST_API_KEY="your_key_here"

playwright 🎭

Purpose: Real browser automation and E2E testing Triggers: Browser testing, E2E scenarios, visual validation Requirements: Node.js 16+, no API key

# Automatic activation
/sc:test --type e2e "user login flow"
# → Enables browser automation testing

# Manual activation
/sc:validate "accessibility compliance" --play

morphllm-fast-apply 🔄

Purpose: Efficient pattern-based code transformations Triggers: Multi-file edits, refactoring, framework migrations Requirements: Node.js 16+, MORPH_API_KEY

# Automatic activation
/sc:improve legacy-codebase/ --focus maintainability
# → Applies consistent patterns across files

# API key setup
export MORPH_API_KEY="your_key_here"

serena 🧭

Purpose: Semantic code understanding with project memory Triggers: Symbol operations, large codebases, session management Requirements: Python 3.9+, uv package manager, no API key

# Automatic activation  
/sc:load existing-project/
# → Builds project understanding and memory

# Manual activation
/sc:refactor "extract UserService" --serena

tavily 🔍

Purpose: Web search and real-time information retrieval for research Triggers: /sc:research commands, "latest" information requests, current events, fact-checking Requirements: Node.js 16+, TAVILY_API_KEY (free tier available at https://app.tavily.com)

# Automatic activation
/sc:research "latest AI developments 2024"
# → Performs intelligent web research

# Manual activation  
/sc:analyze "market trends" --tavily

# API key setup (get free key at https://app.tavily.com)
export TAVILY_API_KEY="tvly-your_api_key_here"

chrome-devtools 📊

Purpose: Performance analysis, debugging, and real-time browser inspection Triggers: Performance auditing, debugging layout issues (e.g., CLS), slow loading times (LCP), console errors, network requests Requirements: Node.js 16+, no API key

# Automatic activation
/sc:debug "page is loading slowly"
# → Enables performance analysis with Chrome DevTools

# Manual activation
/sc:analyze --performance "homepage"

Capabilities:

• Web Search: Comprehensive searches with ranking and filtering
• News Search: Time-filtered current events and updates
• Content Extraction: Full-text extraction from search results
• Domain Filtering: Include/exclude specific domains
• Multi-Hop Research: Iterative searches based on findings (up to 5 hops)

Research Depth Control:

• --depth quick: 5-10 sources, basic synthesis
• --depth standard: 10-20 sources, structured report (default)
• --depth deep: 20-40 sources, comprehensive analysis
• --depth exhaustive: 40+ sources, academic-level research

Unified MCP Gateway (Alternative Setup)

For users who want a simpler, unified setup that manages all MCP servers through a single endpoint, AIRIS MCP Gateway provides:

• 50 tools from 7 default servers (airis-agent, context7, fetch, memory, sequential-thinking, serena, tavily)
• Single SSE endpoint instead of 8+ separate stdio connections
• Lazy loading - servers start only when needed, auto-terminate when idle

Setup

# 1. Clone and start
git clone https://github.com/agiletec-inc/airis-mcp-gateway.git
cd airis-mcp-gateway
docker compose up -d

# 2. Register with Claude Code
claude mcp add --scope user --transport sse airis-mcp-gateway http://localhost:9400/sse

Verify

curl http://localhost:9400/health
curl http://localhost:9400/api/tools/combined | jq '.tools_count'

Configuration

Edit mcp-config.json to enable/disable servers, then restart:

docker compose restart api

More Information

• Repository: github.com/agiletec-inc/airis-mcp-gateway

---

Configuration

MCP Configuration File (~/.claude.json):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "sequential-thinking": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "magic": {
      "command": "npx",
      "args": ["@21st-dev/magic"],
      "env": {"TWENTYFIRST_API_KEY": "${TWENTYFIRST_API_KEY}"}
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "morphllm-fast-apply": {
      "command": "npx",
      "args": ["@morph-llm/morph-fast-apply"],
      "env": {"MORPH_API_KEY": "${MORPH_API_KEY}"}
    },
    "serena": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"]
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {"TAVILY_API_KEY": "${TAVILY_API_KEY}"}
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Usage Patterns

Server Control:

# Enable specific servers
/sc:analyze codebase/ --c7 --seq

# Disable all MCP servers
/sc:implement "simple function" --no-mcp

# Enable all servers
/sc:design "complex architecture" --all-mcp

Multi-Server Coordination:

# Full-stack development
/sc:implement "e-commerce checkout"
# → Sequential: workflow analysis
# → Context7: payment patterns  
# → Magic: UI components
# → Serena: code organization
# → Playwright: E2E testing

Troubleshooting

Common Issues:

• No servers connected: Check Node.js: node --version (need v16+)
• Context7 fails: Clear cache: npm cache clean --force
• Magic/Morphllm errors: Expected without API keys (paid services)
• Server timeouts: Restart Claude Code session

Quick Fixes:

# Reset connections
# Restart Claude Code session

# Check dependencies  
node --version  # Should show v16+

# Test without MCP
/sc:command --no-mcp

# Check configuration
ls ~/.claude.json

API Key Configuration:

# For Magic server (required for UI generation)
export TWENTYFIRST_API_KEY="your_key_here"

# For Morphllm server (required for bulk transformations)
export MORPH_API_KEY="your_key_here"

# For Tavily server (required for web search - free tier available)
export TAVILY_API_KEY="tvly-your_key_here"

# Add to shell profile for persistence
echo 'export TWENTYFIRST_API_KEY="your_key"' >> ~/.bashrc
echo 'export MORPH_API_KEY="your_key"' >> ~/.bashrc
echo 'export TAVILY_API_KEY="your_key"' >> ~/.bashrc

Environment Variable Usage:

• ✅ TWENTYFIRST_API_KEY - Required for Magic MCP server functionality
• ✅ MORPH_API_KEY - Required for Morphllm MCP server functionality
• ✅ TAVILY_API_KEY - Required for Tavily MCP server functionality (free tier available)
• ❌ Other env vars in docs - Examples only, not used by framework
• 📝 Magic and Morphllm are paid services, Tavily has free tier, framework works without them

Server Combinations

No API Keys (Free):

• context7 + sequential-thinking + playwright + serena

1 API Key:

• Add magic for professional UI development

2 API Keys:

• Add morphllm-fast-apply for large-scale refactoring

Common Workflows:

• Learning: context7 + sequential-thinking
• Web Development: magic + context7 + playwright
• Enterprise Refactoring: serena + morphllm + sequential-thinking
• Complex Analysis: sequential-thinking + context7 + serena
• Deep Research: tavily + sequential-thinking + serena + playwright
• Current Events: tavily + context7 + sequential-thinking
• Performance Tuning: chrome-devtools + sequential-thinking + playwright

Integration

With SuperClaude Commands:

• Analysis commands automatically use Sequential + Serena
• Implementation commands use Magic + Context7
• Testing commands use Playwright + Sequential
• Research commands use Tavily + Sequential + Playwright

With Behavioral Modes:

• Brainstorming Mode: Sequential for discovery
• Task Management: Serena for persistence
• Orchestration Mode: Optimal server selection
• Deep Research Mode: Tavily + Sequential + Playwright coordination

Performance Control:

• Automatic resource management based on system load
• Concurrency control: --concurrency N (1-15)
• Priority-based server selection under constraints

Related Resources

Essential Reading:

• Commands Guide - Commands that activate MCP servers
• Quick Start Guide - MCP setup guide

Advanced Usage:

• Behavioral Modes - Mode-MCP coordination
• Agents Guide - Agent-MCP integration
• Session Management - Serena workflows

Technical References:

• Examples Cookbook - MCP workflow patterns
• Technical Architecture - Integration details