Claude Code MCP Server Integration

Overview

This page explains the fundamental concepts of integrating MCP (Model Context Protocol) servers with Claude Code. MCP enables Claude Code to connect with external tools, databases, and services.

Official Documentation: Connect Claude Code to tools via MCP – Claude Docs

Configuration File Location

The main configuration file for Claude Code MCP servers is located at:

~/.claude.json

This file defines:

• Which MCP servers to load
• How to connect to them (transport type)
• Environment variables and credentials
• Scope (user, project, or local)

Three MCP Transport Types

MCP servers can use different transport protocols depending on their architecture:

1. Stdio (Standard Input/Output)

How it works: Runs as a local process on your machine, communicating through stdin/stdout.

Best for:

• Custom scripts and tools
• Direct system access needed
• Local file operations
• Custom business logic

Example Configuration:

"wordpress-mcp": {
  "command": "node",
  "args": ["/Users/chrislee/extended-wordpress-mcp-server.js"],
  "env": {
    "WP_SITES_PATH": "/Users/chrislee/.claude/wp-sites-config.json"
  }
}

2. SSE (Server-Sent Events)

How it works: Provides real-time streaming connections for continuous data flow.

Best for:

• Real-time updates
• Event streams
• Live monitoring
• Cloud services requiring push notifications

3. HTTP (Remote Server)

How it works: Uses standard HTTP request/response pattern for remote services.

Best for:

• REST APIs
• Web services
• Cloud platforms
• Third-party integrations

Example Configuration:

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

Three Configuration Scopes

MCP servers can be installed at different scopes depending on your needs:

Local Scope (Default)

Location: Project’s .claude-mcp-config.json

Characteristics:

• ✅ Project-specific
• ✅ Not shared with other projects
• ✅ Can use relative paths (working directory is predictable)
• ⚠️ Only available in that project directory

Project Scope

Location: Project’s shared configuration (team repository)

Characteristics:

• ✅ Shared with team members
• ✅ Version controlled
• ✅ Project-specific configuration
• ⚠️ May need environment variables for credentials

User Scope

Location: ~/.claude.json

Characteristics:

• ✅ Available in all Claude Code projects
• ✅ Personal configuration
• ⚠️ Must use absolute paths (working directory varies by project)
• ✅ Can be overridden by project-level configs

Installation Command:

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

Quick Reference: Choosing the Right Setup

Transport	Scope	Paths	Use Case
Stdio	User	Absolute	Cross-project custom tools
Stdio	Project	Relative OK	Team-shared scripts
Stdio	Local	Relative OK	Personal experiments
HTTP	User	N/A	Cloud services
HTTP	Project	N/A	Team cloud tools
SSE	Any	N/A	Real-time streams

Configuration Best Practices

Path Rules

Scope	Path Type	Reason
User Scope	✅ Absolute paths required	Working directory varies by project
Project/Local Scope	✅ Relative paths OK	Working directory is predictable (project root)

Security Best Practices

• ✅ Store credentials in separate config files (not in ~/.claude.json)
• ✅ Use environment variables for sensitive data
• ✅ Keep credential files out of version control
• ✅ Use application passwords (not regular passwords) when available
• ⚠️ User-scoped configs with credentials should have restricted permissions

Testing & Verification

# Check MCP server status in Claude Code
/mcp

# Expected output for working server:
# ✔ server-name - connected

# Failed server shows:
# ✘ server-name - failed

Common Installation Commands

User Scope (Available Everywhere)

# HTTP transport (cloud services)
claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp

# Stdio transport (custom servers)
# Add manually to ~/.claude.json (see WordPress example)

Project Scope (Team Shared)

# Default scope is project-level
claude mcp add --transport http teamtool https://api.example.com/mcp

Local Scope (Current Project Only)

claude mcp add --scope local --transport http localtool https://localhost:3000/mcp

Troubleshooting Tips

Connection Failed

1. Check paths: User scope requires absolute paths
2. Verify file exists: Server file must be at specified location
3. Check permissions: Config files must be readable
4. Environment variables: Verify all required env vars are set

Server Won’t Start

1. Dependencies: Ensure all dependencies are installed (Node.js, Python, etc.)
2. Syntax errors: Check JSON configuration syntax
3. Port conflicts: Ensure ports aren’t already in use
4. Logs: Check Claude Code logs for error details

Tools Not Appearing

1. Server connected?: Run /mcp to check status
2. Restart Claude Code: Configuration changes may require restart
3. Scope correct?: Verify server is installed in expected scope
4. Tool definition: Check server implements tools correctly

Related Resources

• Official Claude Code MCP Documentation