MCP Configuration Skill

This skill provides guidance for configuring MCP (Model Context Protocol) servers for Claude Code. For bundling MCP servers in plugins, see the plugin-design skill instead.

Official Documentation

Claude Code MCP configuration is post-training knowledge. Fetch current docs:

• https://code.claude.com/docs/en/mcp - Complete MCP configuration guide

Workflow Selection

Use this table to navigate to relevant sections:

Quick Start

Add HTTP server (remote/cloud):

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer ${API_TOKEN}"

Add stdio server (local tool):

claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add --env GITHUB_TOKEN=${GITHUB_TOKEN} github -- npx -y @modelcontextprotocol/server-github

Check status:

claude mcp list      # CLI
/mcp                 # Inside Claude Code

Core Understanding

MCP Extends Claude's Capabilities

MCP servers connect Claude Code to external tools, databases, and APIs. They're not plugins - they're tool providers that Claude can invoke.

Key insight: Claude Code supports HTTP transport natively. No proxy needed for remote servers (unlike Claude Desktop).

Configuration vs Plugin Bundling

This skill covers project and user configuration. For plugin bundling, load plugin-design skill.

Tool Selection Philosophy (Opinionated)

Before adding any MCP server, apply this hierarchy:

1. Prefer Native CLI Tools Over MCP

If a dedicated CLI tool exists, use it instead of MCP:

Why: CLI tools are battle-tested, have better error messages, don't consume context window, and Claude already knows how to use them.

2. Prefer Remote Official MCP Over Local/Community

When MCP is appropriate, prefer in this order:

1. Remote official - vendor-hosted (e.g., https://mcp.notion.com/mcp)
2. Local official - vendor-published npm packages (@modelcontextprotocol/server-*)
3. Community - third-party implementations (last resort)

Why: Official servers have better maintenance, security updates, and API compatibility.

3. Prefer .mcp.json Over settings.json

Store MCP configuration in .mcp.json files, not IDE settings.json:

Why: .mcp.json is the Claude Code standard, works across editors, and keeps MCP config separate from IDE settings.

Configuration Scopes (Official Specification)

Scope Hierarchy

Local (project-specific in ~/.claude.json, highest precedence)
  ↓
Project (.mcp.json in repo)
  ↓
User (~/.claude.json, cross-project)
  ↓
Managed (enterprise, lowest)

Key insight: "Local" scope means project-specific but still stored in ~/.claude.json under the project path, not in the project directory itself. This keeps credentials out of your repo while allowing per-project overrides.

Local overrides Project overrides User overrides Managed.

When to Use Each Scope

Project scope creates/updates .mcp.json at project root - check this into version control for team sharing.

Security note: Project-scoped MCP servers require user approval before first use (prevents malicious repo configs from auto-running). Reset approvals with: claude mcp reset-project-choices

Transport Type Selection (Best Practices)

Decision Framework

Default to HTTP for remote servers - it's the modern approach and Claude Code handles it natively.

Decision Framework

Should I Add an MCP Server?

Add MCP server when:

• Need external API access (GitHub, databases, cloud services)
• Want persistent tool availability across sessions
• Team needs shared access to same services

Don't add MCP when:

• One-time API call (just use WebFetch)
• Tool is already built into Claude Code
• Simpler to write a hook or agent

Project vs User Scope?

Use project scope when:

• Team should share the configuration
• Server is specific to this project
• Want to check config into version control

Use user scope when:

• Personal utility used across projects
• Contains personal credentials
• Not relevant to other team members

Quality Checklist

Before committing .mcp.json:

• All secrets use ${ENV_VAR} references
• No credentials in git history
• README documents required env vars
• README explains how to obtain credentials
• Transport type appropriate (HTTP for remote, stdio for local)
• Server names are descriptive (not "server1")

References

Read when:

• Creating/modifying MCP config: Fetch https://code.claude.com/docs/en/mcp for current syntax
• Bundling MCP in plugins: Load plugin-design skill
• Troubleshooting OAuth: Run /mcp command in Claude Code
• Finding MCP servers: Search npm for @modelcontextprotocol/server-* packages