Claude Code MCP Server Integration Guide

Leave a Comment / Uncategorized / By

Overview

This guide 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

Example Implementations:

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"
  }
}

Real Examples:

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"
}

Real Examples:

  • Notion MCP
  • Canva MCP
  • Box MCP

Note: For custom stdio servers like WordPress and Whisper, see the stdio transport section above

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

Use Cases:

  • Personal development servers
  • Experimental configurations
  • Sensitive credentials specific to one project
  • Testing new MCP servers

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)

Use Cases:

  • Team shared tools
  • Project-specific services
  • Collaboration tools required by the team
  • CI/CD integrations

Characteristics:

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

User Scope

Location: ~/.claude.json

Use Cases:

  • Personal utilities needed across multiple projects
  • Development tools (Notion, WordPress, databases)
  • Frequently used services
  • Cross-project productivity tools

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

Example Implementations

These pages demonstrate real-world MCP integrations:

WordPress MCP Server (Stdio + User Scope)

WordPress MCP Server Integration: Complete Setup Guide

What it demonstrates:

  • Custom stdio MCP server implementation
  • WordPress REST API integration
  • User scope configuration with absolute paths
  • Troubleshooting common issues

Key Features:

  • Create/update/delete WordPress posts
  • Test API connection
  • List posts with pagination
  • Direct REST API communication

Whisper MCP Server (Stdio + Custom Endpoint)

Whisper MCP Integration: Custom Audio Transcription Setup

What it demonstrates:

  • Customizing existing MCP server
  • Integrating with custom API endpoint
  • Large file handling (300MB+)
  • Audio compression workflow

Key Features:

  • Audio transcription
  • Automatic file compression
  • Custom AdventureTube endpoint integration
  • Environment variable configuration

Quick Reference: Choosing the Right Setup

Transport Scope Paths Use Case Example
Stdio User Absolute Cross-project custom tools WordPress MCP
Stdio Project Relative OK Team-shared scripts Whisper MCP
Stdio Local Relative OK Personal experiments Custom dev tools
HTTP User N/A Cloud services Notion, Canva
HTTP Project N/A Team cloud tools Shared API services
SSE Any N/A Real-time streams Live monitoring

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

Project Scope (Team Shared)

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

Local Scope (Current Project Only)

claude mcp add --scope local --transport http localtool https://example.com/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

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *