Module 5: Using MCP with Claude Code

---

Claude Code: The Developer's AI Assistant

Claude Code is Anthropic's command-line interface for working with Claude. It's specifically designed for developers and integrates deeply with your development workflow. In this module, you'll learn how to configure and use MCP servers effectively with Claude Code.

If you're a developer, this is where MCP becomes incredibly powerful.

---

Installing Claude Code

If you haven't already installed Claude Code:

npm install -g @anthropic-ai/claude-code

Verify the installation:

claude --version

Claude Code requires an Anthropic API key. Set it up:

claude config set apiKey YOUR_API_KEY

Or use environment variable:

export ANTHROPIC_API_KEY=your_key_here

---

Configuration Hierarchy

Claude Code uses a layered configuration system:

1. User-level settings (~/.claude/settings.json)

• Apply to all Claude Code sessions
• Good for personal preferences and commonly-used servers

2. Project-level settings (.mcp.json in project root)

• Apply only when running Claude Code in that directory
• Perfect for project-specific integrations
• Can be committed to version control (without secrets)

3. Command-line flags

• Override settings for a single session
• Useful for testing and debugging

The layers merge, with project settings overriding user settings, and command-line flags overriding both.

---

Project-Level MCP Configuration

The most powerful Claude Code feature is project-scoped MCP. Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "project-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

When you run claude in this directory, it automatically connects to servers defined in .mcp.json.

Why project-level?

• Different projects need different tools
• Configuration travels with the project
• Team members get the same setup
• No need to modify global settings

---

Practical Project Configuration Examples

Node.js Project:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "src", "tests", "docs"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Python Project with Database:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "src", "tests"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Monorepo:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "packages/frontend",
        "packages/backend",
        "packages/shared"
      ]
    }
  }
}

---

Running Claude Code with MCP

Basic usage:

cd your-project
claude

Claude Code automatically detects .mcp.json and connects to the configured servers.

Debug mode (see MCP activity):

claude --mcp-debug

This shows server connections, tool calls, and responses.

Specify a different config:

claude --mcp-config path/to/config.json

---

Claude Code Workflow Examples

Let's see MCP in action with real development tasks:

Code Review:

You: Review the changes in src/auth/login.ts for security issues

Claude: [Uses filesystem server to read the file]
        I've reviewed login.ts. Here are my findings...

Documentation Update:

You: Update the README to reflect the new API endpoints in src/routes/

Claude: [Reads route files, reads current README]
        I'll update the README with the following changes...

Bug Investigation:

You: The user authentication is failing. Check the auth module and related tests.

Claude: [Reads multiple files across the project]
        I found the issue. In auth/verify.ts line 45...

Database Schema Analysis:

You: What tables reference the users table?

Claude: [Queries database schema via postgres server]
        The following tables have foreign keys to users...

---

Interactive Development Session

Claude Code shines in interactive sessions. Here's a typical workflow:

$ claude
Claude Code v1.0.0

You: I need to add a new API endpoint for user preferences

Claude: I'll help you add that endpoint. First, let me look at your current
        API structure.

        [Uses filesystem to read routes/index.ts, models/user.ts]

        Based on your project structure, I recommend:
        1. Create routes/preferences.ts
        2. Add UserPreferences model
        3. Update the router in index.ts

        Should I generate the code?

You: Yes, show me the route handler first

Claude: Here's the route handler for user preferences:

        [Generates code based on project patterns]

The AI understands your specific codebase because it can actually read it.

---

Scoping Server Access

You can limit which parts of your project are accessible:

Focused access:

{
  "mcpServers": {
    "source-code": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "src"]
    }
  }
}

Multiple scopes:

{
  "mcpServers": {
    "code": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "src", "lib"]
    },
    "docs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "docs"]
    },
    "config": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "config"]
    }
  }
}

Why separate scopes?

• Claude can reference which server it used
• Easier to audit what was accessed
• Can enable/disable specific areas

---

Environment Variable Handling

For secrets in project configs, use environment variables:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Then set in your shell or .env file:

export GITHUB_TOKEN=ghp_xxxx

For team projects:

1. Commit .mcp.json with ${VAR} placeholders
2. Add actual values to your local .env (gitignored)
3. Document required variables in README

---

Combining with Claude Code Features

MCP integrates with other Claude Code capabilities:

With context files:

claude --context ARCHITECTURE.md

Claude reads your architecture doc AND has MCP access to the codebase.

With specific prompts:

claude "Analyze src/api for potential performance issues"

Combines your directive with MCP file access.

With output handling:

claude "Generate test cases for utils/parser.ts" > new-tests.ts

Generate code based on actual file content, save to file.

---

Team Configuration Patterns

Pattern 1: Shared base, personal additions

.mcp.json (committed):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "src"]
    }
  }
}

~/.claude/settings.json (personal):

{
  "mcpServers": {
    "github": { ... }
  }
}

Pattern 2: Development-specific config

.mcp.json:

{
  "mcpServers": {
    "filesystem": { ... }
  }
}

.mcp.local.json (gitignored):

{
  "mcpServers": {
    "dev-database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DEV_DB_URL}"]
    }
  }
}

---

Debugging MCP in Claude Code

Check server status:

claude --mcp-debug

Watch for:

• "Connected to server: xxx" messages
• Error messages during initialization
• Tool call logs

Common issues:

1. Server not connecting:

   • Check JSON syntax
   • Verify package is installed
   • Check environment variables are set

2. Tools not available:

   • Server might have crashed
   • Check if you're in the right directory
   • Verify .mcp.json exists and is valid

3. Slow responses:

   • Large directory scans
   • Database connection issues
   • Network latency for remote servers

---

Performance Considerations

MCP adds latency for tool calls. Optimize by:

1. Limiting scope

"args": ["src", "tests"]  // Good
"args": ["."]             // Slower for large projects

2. Using specific servers Don't enable servers you won't use.

3. Local over remote Filesystem is faster than GitHub API for local files.

4. Caching awareness Some servers cache results. Ask Claude to refresh if needed.

---

Claude Code Commands Reference

Command	Description
claude	Start interactive session
claude "prompt"	Single query
claude --mcp-debug	Show MCP activity
claude --mcp-config file	Use specific config
claude config	Manage settings
claude --help	Full help

---

Key Takeaways

1. Project-level config - .mcp.json in project root for project-specific servers

2. Configuration hierarchy - User → Project → Command-line

3. Scope appropriately - Limit filesystem access to relevant directories

4. Environment variables - Use ${VAR} syntax for secrets

5. Debug mode - --mcp-debug shows what's happening

6. Team patterns - Commit base config, personalize locally

7. Interactive power - MCP makes Claude Code truly understand your codebase

---

Exercise: Project-Specific Setup

Try this in one of your projects:

1. Create .mcp.json with filesystem server pointing to src
2. Run claude --mcp-debug
3. Ask Claude about a specific file in your project
4. Watch the MCP calls in debug output

---

Looking Ahead

You've learned to use existing MCP servers. But what if you need something that doesn't exist? In the next module, we'll build custom MCP servers from scratch. You'll learn the SDK, implement tools and resources, and create servers tailored to your specific needs.

---

Next up: Module 6 - Building Custom MCP Servers