claude-code-mcp

Guide Claude through configuring and managing MCP (Model Context Protocol) servers to connect Claude Code with external tools, databases, and services.

Purpose

MCP servers enable Claude Code to interact with external tools and data sources through a standardized protocol. This skill helps install, configure, and manage MCP servers across different scopes (local, project, user), authenticate with remote services, and troubleshoot connection issues.

When to Use This Skill

Use this skill when:

• Installing MCP servers (HTTP, SSE, or stdio transport)
• Configuring MCP server authentication and environment variables
• Managing MCP server scopes (local, project, user)
• Troubleshooting MCP server connectivity or authentication issues
• Setting up team-wide MCP server configurations
• Importing MCP servers from Claude Desktop
• Using MCP resources and prompts in conversations

Do NOT use this skill for:

• Creating or building MCP servers (use MCP SDK documentation instead)
• Writing MCP server code (this skill is for configuration only)

MCP Server Transports

MCP servers can connect using three transport mechanisms:

HTTP Transport (Recommended)

Best for cloud-based services with REST APIs.

Basic syntax:

claude mcp add --transport http <name> <url>

Examples:

# Simple HTTP 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"

# With custom headers
claude mcp add --transport http custom-api https://api.example.com/mcp \
  --header "X-API-Key: key123" \
  --header "X-Custom-Header: value"

SSE Transport (Deprecated)

Server-Sent Events transport. Use HTTP where available.

Basic syntax:

claude mcp add --transport sse <name> <url>

Example:

claude mcp add --transport sse asana https://mcp.asana.com/sse

Stdio Transport

For local processes needing direct system access.

Basic syntax:

claude mcp add --transport stdio <name> [--env KEY=value] -- <command> [args...]

Examples:

# NPM package
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

# Local script
claude mcp add --transport stdio custom-tool \
  --env CONFIG_PATH=/path/to/config \
  -- /usr/local/bin/custom-mcp-server

# Python package
claude mcp add --transport stdio python-tool \
  -- python -m my_mcp_server

Important: Use -- to separate Claude CLI flags from MCP server command/arguments.

MCP Server Scopes

MCP servers can be configured at three different scopes:

Local Scope (Default)

• Location: Project .mcp.json (gitignored)
• Visibility: Current project only
• Use case: Private configurations, testing, local development
• Command: claude mcp add --scope local (or omit --scope)

Project Scope

• Location: Project .mcp.json (committed to git)
• Visibility: All team members using the project
• Use case: Team-shared integrations, required tooling
• Command: claude mcp add --scope project

User Scope

• Location: ~/.claude/mcp.json
• Visibility: All projects for current user
• Use case: Personal tools, cross-project services
• Command: claude mcp add --scope user

Scope precedence: Local > Project > User

When the same server name exists in multiple scopes, the highest precedence wins.

MCP Configuration Workflow

To configure an MCP server, follow this process:

Step 1: Identify Requirements

Determine what information is needed:

1. Transport type - HTTP, SSE, or stdio?
2. Server URL or command - Where is the server?
3. Authentication - API keys, OAuth, headers?
4. Environment variables - Configuration needed?
5. Scope - Local, project, or user?

Example questions to ask:

• "What service are you connecting to?"
• "Do you have an API key or authentication token?"
• "Should this be available to your whole team (project scope) or just you (local/user scope)?"
• "Is this a cloud service (HTTP) or local tool (stdio)?"

Step 2: Determine Transport and Scope

Based on the requirements:

Choose HTTP when:

• Connecting to cloud-based REST APIs
• Service provides an MCP endpoint URL
• No local process needed

Choose stdio when:

• Running local tools or scripts
• Need direct system access
• Using NPM packages or local executables

Choose SSE when:

• Service only supports SSE transport
• HTTP is not available (prefer HTTP if both exist)

Choose scope based on:

• Local: Testing, temporary, contains secrets not in env vars
• Project: Team needs access, shared configuration
• User: Personal tool across all projects

Step 3: Install the MCP Server

Use the appropriate claude mcp add command based on transport and scope.

HTTP example:

claude mcp add --transport http --scope project \
  notion https://mcp.notion.com/mcp

Stdio example:

claude mcp add --transport stdio --scope user \
  airtable \
  --env AIRTABLE_API_KEY=${AIRTABLE_API_KEY} \
  -- npx -y airtable-mcp-server

With multiple environment variables:

claude mcp add --transport stdio --scope project \
  custom-db \
  --env DB_HOST=${DB_HOST} \
  --env DB_PORT=${DB_PORT:-5432} \
  --env DB_NAME=analytics \
  -- /usr/local/bin/db-mcp-server

Step 4: Verify Installation

After installation:

1. List servers:

   claude mcp list
   

2. Get server details:

   claude mcp get <server-name>
   

3. Test in Claude Code:

   • Start Claude Code
   • Ask the user to run /mcp to see server status
   • Try using a tool from the server

Step 5: Authenticate (if required)

Some servers require OAuth or additional authentication:

1. Start Claude Code
2. Run /mcp command
3. Select the server requiring authentication
4. Follow browser authentication flow
5. Verify authentication succeeded in /mcp menu

Tokens are securely stored and auto-refreshed. Clear with "Clear authentication" from /mcp menu.

Step 6: Troubleshoot if Needed

If the server isn't working:

Check server status:

claude mcp list

Get detailed information:

claude mcp get <server-name>

Common issues:

1. Server not starting (stdio)

   • Verify command is executable: which npx, which python
   • Check environment variables are set
   • Test command independently
   • On Windows, use cmd /c wrapper: -- cmd /c npx -y package

2. Authentication failures (HTTP/SSE)

   • Verify API keys are correct
   • Check headers are properly formatted
   • Use /mcp to re-authenticate OAuth servers
   • Verify URL is correct and accessible

3. Server timeout

   • Increase timeout: MCP_TIMEOUT=10000 claude
   • Check network connectivity
   • Verify server is responding

4. Output limit warnings

   • Increase output limit: export MAX_MCP_OUTPUT_TOKENS=50000
   • Default is 25,000 tokens
   • Warning at 10,000 tokens

For additional details on popular MCP servers and their specific configurations, consult the official MCP documentation.

Common MCP Server Patterns

Cloud Service with API Key (HTTP)

claude mcp add --transport http --scope user \
  service-name https://api.service.com/mcp \
  --header "Authorization: Bearer ${API_KEY}"

Local NPM Package (stdio)

claude mcp add --transport stdio --scope user \
  package-name \
  --env API_KEY=${API_KEY} \
  -- npx -y @org/mcp-package

Team Database Access (stdio, project scope)

claude mcp add --transport stdio --scope project \
  analytics-db \
  --env DB_URL=${ANALYTICS_DB_URL} \
  -- npx -y @bytebase/dbhub

Personal Tool Across Projects (stdio, user scope)

claude mcp add --transport stdio --scope user \
  my-tool \
  -- /usr/local/bin/my-mcp-tool

Environment Variable Handling

MCP configurations support environment variable expansion:

Syntax:

• ${VAR} - Required variable (error if not set)
• ${VAR:-default} - Optional with default value

Examples:

# Required variable
--env DB_HOST=${DB_HOST}

# Optional with default
--env DB_PORT=${DB_PORT:-5432}

# Literal value
--env ENVIRONMENT=production

# Multiple variables
--env API_URL=${API_URL} \
--env API_KEY=${API_KEY} \
--env TIMEOUT=${TIMEOUT:-30}

Setting environment variables:

# In shell (temporary)
export API_KEY=your-key-here
claude mcp add --transport stdio tool --env API_KEY=${API_KEY} -- npx tool

# In .env file (project)
echo "API_KEY=your-key-here" >> .env
source .env
claude mcp add ...

# In shell profile (permanent)
echo 'export API_KEY=your-key-here' >> ~/.zshrc
source ~/.zshrc

Managing MCP Servers

List All Servers

claude mcp list

Shows all configured servers across all scopes with status.

Get Server Details

claude mcp get <server-name>

Shows configuration, scope, transport type, and status.

Remove a Server

claude mcp remove <server-name>

Removes from the scope where it was added.

Check Status in Claude Code

Within Claude Code, use /mcp command to:

• View all connected servers
• See authentication status
• Re-authenticate OAuth servers
• Clear authentication tokens

Using MCP Tools in Conversations

Once servers are connected:

Access MCP Tools

Claude Code automatically sees MCP tools. Just ask:

> "Check Sentry for errors in the last 24 hours"
> "Create a GitHub issue for this bug"
> "Query the database for user count"

Use MCP Resources

Type @ to list available resources:

> "Analyze @github:issue://123"
> "Review @notion:page://abc123"

Resources are auto-fetched and attached to context.

Use MCP Prompts as Slash Commands

MCP prompts appear as slash commands:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login" high

Plugin-Provided MCP Servers

Plugins can bundle MCP servers that start automatically:

Plugin configuration (.mcp.json in plugin root):

{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {
      "DB_URL": "${DB_URL}"
    }
  }
}

Key points:

• Managed via plugin install/uninstall, not /mcp commands
• Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths
• Start automatically when plugin is enabled
• Appear in /mcp menu but managed by plugin

Team Configuration Best Practices

For team-wide MCP server setup:

Project Scope Configuration

1. Use project scope for shared integrations:

   claude mcp add --scope project \
     github https://api.githubcopilot.com/mcp/
   

2. Commit .mcp.json to repository

3. Document required environment variables in README:

   ## Required Environment Variables
   - `GITHUB_TOKEN` - GitHub personal access token
   - `JIRA_API_KEY` - Jira API key
   

4. Team members set environment variables locally:

   export GITHUB_TOKEN=ghp_xxxx
   export JIRA_API_KEY=xxxx
   

Environment Variable Management

For sensitive values:

• Never commit actual secrets to .mcp.json
• Use ${VAR} expansion
• Document required variables
• Use .env files (gitignored) for local values

For non-sensitive values:

• Can specify directly in configuration
• Example: --env ENVIRONMENT=production

Importing from Claude Desktop

Import existing MCP servers from Claude Desktop:

claude mcp add-from-claude-desktop

Interactively select which servers to import. Configurations are copied to appropriate scope.

Advanced: JSON Configuration

Add servers via JSON for programmatic setup:

# HTTP server
claude mcp add-json weather-api '{
  "type": "http",
  "url": "https://api.weather.com/mcp",
  "headers": {
    "Authorization": "Bearer token"
  }
}'

# Stdio server
claude mcp add-json db-tool '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@tool/mcp"],
  "env": {
    "DB_URL": "${DB_URL}"
  }
}'

Additional Resources

For additional information about MCP:

• Popular MCP Servers: Browse the MCP servers repository for community-maintained servers
• Building MCP Servers: See the MCP SDK documentation to create your own servers
• Official Documentation: Consult the Claude Code MCP guide for complete reference documentation

Troubleshooting

Server Not Appearing

Symptoms: Server added but not visible in /mcp

Solutions:

• Restart Claude Code after adding server
• Verify server was added: claude mcp list
• Check correct scope: claude mcp get <name>
• For stdio: verify command is executable

Authentication Failures

Symptoms: OAuth flow fails or API returns 401/403

Solutions:

• Use /mcp to re-authenticate
• Verify API key is correct
• Check header format: "Authorization: Bearer token"
• Clear and re-authenticate: /mcp → Clear authentication

Command Not Found (stdio)

Symptoms: "command not found" for stdio servers

Solutions:

• Verify command exists: which npx, which python
• Use full path: -- /usr/local/bin/tool
• On Windows: use -- cmd /c npx -y package
• Check PATH environment variable

Environment Variable Not Expanded

Symptoms: ${VAR} appears literally in configuration

Solutions:

• Verify variable is exported: echo $VAR
• Set before running command: export VAR=value
• Use shell substitution if needed: --env VAR=$VAR (expanded by shell)

Server Timeout

Symptoms: Server connection times out

Solutions:

• Increase timeout: MCP_TIMEOUT=10000 claude
• Check network connectivity
• Verify server URL is correct
• For stdio: check command starts quickly

Integration with Other Skills

This skill works alongside other claude-code-meta skills:

• Use claude-code-plugins - For bundling MCP servers in plugins

Activate these skills when working on plugin-provided MCP servers or automated MCP configuration workflows.