MCP Server Manager

Overview

MCP (Model Context Protocol) servers connect Claude Code to external tools, databases, and APIs. This skill provides guidance for installing, configuring, and managing MCP servers using the claude mcp command-line interface.

Quick Reference

Essential Commands

List all configured MCP servers:

claude mcp list

Get details about a specific server:

claude mcp get <server-name>

Remove a server:

claude mcp remove <server-name>

Check server status (from within Claude Code):

/mcp

Adding MCP Servers

Transport Types

MCP servers use one of three transport protocols. Choose the appropriate transport based on the server type:

HTTP Transport (Remote Servers)

For cloud-based services providing HTTP endpoints:

# Basic syntax
claude mcp add --transport http <name> <url>

# Example: Add Notion server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# With authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

SSE Transport (Server-Sent Events)

For remote servers using SSE protocol:

# Basic syntax
claude mcp add --transport sse <name> <url>

# Example: Add Webflow server
claude mcp add --transport sse webflow https://mcp.webflow.com/sse

# With API key header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: YOUR_KEY"

Stdio Transport (Local Process)

For servers running as local processes with stdio communication:

# Basic syntax
claude mcp add --transport stdio <name> [--env KEY=VALUE ...] -- <command> [args...]

# Example: Add Airtable server
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

# Example: Add local Python server
claude mcp add --transport stdio custom-db \
  --env DB_URL=postgresql://localhost/mydb \
  -- python3 /path/to/server.py

Important: Use -- separator before the command to indicate where environment variables end and the command begins.

Configuration Scopes

MCP servers can be configured at three different scopes:

Local Scope (Default)

Private to the current project directory only. Ideal for:

• Personal development servers
• Experimental configurations
• Servers with sensitive credentials

# Local scope (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Project Scope

Shared with team members via .mcp.json in project root. Ideal for:

• Team-shared servers
• Project-specific tools
• Version-controlled configurations

# Add project-scoped server
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

Creates/updates .mcp.json:

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    }
  }
}

Security Note: Claude Code prompts for approval before using project-scoped servers. Reset approvals with:

claude mcp reset-project-choices

User Scope

Available across all projects on the machine. Ideal for:

• Personal utility servers
• Development tools used across projects
• Frequently-used services

# Add user-scoped server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Scope Precedence

When servers with the same name exist at multiple scopes: Local > Project > User

Authentication

OAuth 2.0 (Remote Servers)

Many remote MCP servers use OAuth. Authentication flow:

1. Add the server using claude mcp add
2. First use triggers OAuth browser flow
3. Authorize in browser
4. Credentials stored in ~/.mcp-auth/

Example with Webflow:

# Add server
claude mcp add --transport sse webflow https://mcp.webflow.com/sse

# Check status - shows "⚠ Needs authentication"
claude mcp list

# Within Claude Code, trigger OAuth
# Ask: "List my Webflow sites"
# Browser opens for authorization

Reset OAuth credentials:

rm -rf ~/.mcp-auth

API Keys and Headers

For servers requiring API keys or custom headers:

# Bearer token
claude mcp add --transport http api-server https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# API key header
claude mcp add --transport sse service https://service.com/sse \
  --header "X-API-Key: YOUR_KEY"

# Multiple headers
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer TOKEN" \
  --header "X-Custom-Header: VALUE"

Environment Variables (Stdio Servers)

Pass sensitive credentials via environment variables:

claude mcp add --transport stdio database \
  --env DB_PASSWORD=secret123 \
  --env API_KEY=key456 \
  -- python3 /path/to/db-server.py

Troubleshooting

Common Issues

Server shows "⚠ Needs authentication"

• Remote server requires OAuth
• Trigger authentication by using the server's tools
• Check claude mcp get <name> for authentication status

Server shows "✗ Connection failed"

• Verify URL is correct
• Check network connectivity
• Ensure authentication credentials are valid
• For stdio servers, verify command path and permissions

Server not appearing in list

• Restart Claude Code CLI if just added
• Check scope - server may be at different scope level
• Verify configuration file syntax

Project-scoped server requires repeated approval

• Claude Code asks for approval on first use as security measure
• Select "Approve once" or "Always approve" when prompted
• Reset choices with claude mcp reset-project-choices

Configuration File Locations

Local scope: Project-specific settings in .claude/settings.local.json Project scope: .mcp.json in project root User scope: ~/.claude/settings.json

Debugging

Enable MCP debug mode:

claude --mcp-debug

Or use newer debug flag:

claude --debug

Check server details:

# Get server configuration
claude mcp get <server-name>

# List all servers with status
claude mcp list

Advanced Usage

Environment Variable Expansion in .mcp.json

Project-scoped configurations support environment variable expansion:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Syntax:

• ${VAR} - Expand environment variable
• ${VAR:-default} - Use default if not set

Import from Claude Desktop

If MCP servers are already configured in Claude Desktop:

claude mcp add-from-claude-desktop

Imports servers from Claude Desktop configuration (macOS and WSL only).

Add from JSON Configuration

Direct JSON configuration import:

claude mcp add-json <name> '<json-config>'

Example:

claude mcp add-json my-server '{
  "command": "npx",
  "args": ["-y", "server-package"],
  "env": {"API_KEY": "value"}
}'

MCP Output Limits

Control maximum output tokens from MCP tools:

# Set custom limit (default: 25,000 tokens)
export MAX_MCP_OUTPUT_TOKENS=50000
claude

Useful for servers that:

• Query large datasets
• Generate detailed reports
• Process extensive logs

Common MCP Servers

Reference the full MCP documentation for an extensive list of popular MCP servers across categories:

• Development & Testing: Sentry, Socket, Hugging Face, Jam
• Project Management: Asana, Atlassian, Linear, Notion, Monday
• Databases: Airtable, HubSpot, PostgreSQL
• Payments: PayPal, Plaid, Square, Stripe
• Design: Figma, Canva, InVideo
• Infrastructure: Cloudflare, Netlify, Vercel
• Automation: Workato, Zapier

Resources

references/mcp_documentation.md

Complete MCP documentation including:

• Comprehensive server directory with installation commands
• Detailed transport protocol specifications
• Authentication methods and OAuth flows
• Plugin-based MCP servers
• Enterprise MCP configuration
• Environment variable expansion syntax
• Practical examples and use cases

Consult when:

• Need installation command for specific MCP server
• Troubleshooting complex configuration issues
• Setting up enterprise MCP deployment
• Understanding transport protocol details