Module 3: Setting Up MCP Servers

---

From Theory to Practice

You understand what MCP is and how it works architecturally. Now it's time to actually set up MCP servers and connect them to your AI assistant. This module covers practical configuration for the two main MCP clients: Claude Desktop and Claude Code.

By the end of this module, you'll have working MCP integrations and the knowledge to add more.

---

Prerequisites Check

Before we begin, make sure you have:

For Claude Desktop:

• Claude Desktop application installed (macOS or Windows)
• A text editor for editing configuration files
• Basic familiarity with JSON format

For Claude Code:

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Node.js 18+ installed (for running MCP servers)
• Terminal/command line access

For both:

• An Anthropic API key (for some servers)
• Relevant accounts for services you want to integrate (GitHub, etc.)

---

Claude Desktop Configuration

Claude Desktop stores its configuration in a JSON file. The location depends on your operating system:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist, create it. Here's the basic structure:

{
  "mcpServers": {
    "server-name": {
      "command": "path/to/server",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

Let's break down each field:

• server-name: A unique identifier for this server (you choose this)
• command: The executable that runs the server
• args: Command-line arguments passed to the server
• env: Environment variables the server needs

---

Your First MCP Server: Filesystem Access

Let's start with the most useful server: filesystem access. This lets Claude read and search your local files.

Step 1: Install the server

The filesystem server is part of the official MCP servers package. Install it globally:

npm install -g @modelcontextprotocol/server-filesystem

Step 2: Configure Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Projects",
        "/Users/yourname/Documents"
      ]
    }
  }
}

The arguments after the package name are the directories you're allowing access to. Claude can only read files within these directories.

Step 3: Restart Claude Desktop

After saving the configuration, completely quit and restart Claude Desktop. The server won't load until you restart.

Step 4: Verify it works

In Claude Desktop, ask: "What files are in my Projects folder?"

If configured correctly, Claude will use the filesystem server to list your files.

---

Understanding the npx Pattern

You'll notice we use npx as the command with -y flag. This is a common pattern:

"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", ...]

What's happening:

• npx is Node's package runner
• -y automatically confirms prompts
• The package name tells npx what to run
• Additional args are passed to the server

Why use npx?

• Automatically handles package installation
• Always runs the latest version
• No need to manage global installations
• Works across different systems

Alternative: Direct path

If you prefer, install globally and use the direct path:

npm install -g @modelcontextprotocol/server-filesystem

Then configure:

{
  "command": "mcp-server-filesystem",
  "args": ["/path/to/directory"]
}

---

Claude Code Configuration

Claude Code uses a different configuration approach with multiple levels:

1. User-level config (applies to all projects):

~/.claude/settings.json

2. Project-level config (applies to specific project):

.mcp.json   (in project root)

The project-level configuration is especially powerful for development workflows.

---

Project-Level MCP Configuration

For Claude Code, create a .mcp.json file in your project root:

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

Using . means "current directory" - Claude Code can access files in this project.

When you run claude in this directory, it automatically loads this configuration.

---

Adding Multiple Servers

You can run multiple MCP servers simultaneously. Here's an example with filesystem and GitHub:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Each server runs as a separate process. Claude can use tools from all connected servers.

---

Environment Variables and Secrets

Many MCP servers need API keys or tokens. You have several options:

Option 1: Direct in config (not recommended for shared configs)

{
  "env": {
    "API_KEY": "sk-actual-key-here"
  }
}

Option 2: Reference system environment variables

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

Then set the variable in your shell:

export GITHUB_TOKEN="ghp_your_token"

Option 3: Use a .env file (for project configs)

Some setups support loading from .env files. Check your specific client's documentation.

---

Common Server Configurations

Here are ready-to-use configurations for popular servers:

Brave Search (Web Search)

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "your-brave-api-key"
    }
  }
}

PostgreSQL Database

{
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://user:pass@localhost/dbname"
    ]
  }
}

SQLite Database

{
  "sqlite": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-sqlite",
      "/path/to/database.db"
    ]
  }
}

Memory (Persistent Notes)

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

---

Server Lifecycle Management

Understanding how servers start and stop helps with troubleshooting:

Startup:

1. Client reads configuration file
2. For each server, client spawns the process with given command/args
3. Client performs MCP initialization handshake
4. Server reports its capabilities
5. Server is ready for use

During Operation:

• Server process stays running
• Client sends requests as needed
• Server responds to each request

Shutdown:

• When client closes, it terminates server processes
• Servers should handle SIGTERM gracefully

Restart Required:

• After changing configuration files
• After updating server packages
• After system restarts

---

Verifying Server Status

Claude Desktop: Unfortunately, Claude Desktop doesn't have a built-in way to see server status. You can:

• Check if tools appear in the conversation
• Ask Claude "What tools do you have available?"
• Check system logs for errors

Claude Code: Claude Code provides better visibility:

claude --mcp-debug

This shows MCP server initialization and any connection issues.

---

Troubleshooting Common Issues

Server not loading:

1. Check JSON syntax (use a validator)
2. Verify the command path exists
3. Check file permissions
4. Restart the client application

"Command not found" errors:

# Verify npx is available
which npx

# Verify the package exists
npm view @modelcontextprotocol/server-filesystem

Permission denied:

• Ensure the server has access to specified directories
• Check that API keys are valid
• Verify file permissions

Server crashes immediately:

• Check if all required environment variables are set
• Look for error messages in system logs
• Try running the server manually to see errors:

npx -y @modelcontextprotocol/server-filesystem /path

---

Configuration Best Practices

1. Start minimal Add one server at a time. Verify it works before adding more.

2. Use descriptive names

{
  "mcpServers": {
    "project-files": { ... },
    "company-database": { ... },
    "github-work": { ... }
  }
}

3. Limit directory access Only expose directories that are actually needed:

"args": ["/specific/project", "/specific/data"]

Not:

"args": ["/"]  // Don't do this!

4. Keep secrets out of version control If your config file is in a git repo, use environment variables for secrets.

5. Document your setup Add comments (in a separate doc) explaining what each server does and why.

---

Configuration File Examples

Minimal Claude Desktop config:

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

Developer workstation config:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/dev/projects",
        "/Users/dev/documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/devdb"
      ]
    }
  }
}

---

Key Takeaways

1. Configuration files - Claude Desktop uses claude_desktop_config.json, Claude Code uses .mcp.json or settings.json

2. Server definition - Each server needs command, args, and optionally env

3. npx pattern - Use npx -y @package/name for easy server management

4. Multiple servers - Run as many as you need simultaneously

5. Restart required - Always restart after config changes

6. Limit access - Only expose necessary directories and resources

7. Troubleshoot systematically - Check JSON, paths, permissions, then logs

---

Exercise: Set Up Your First Server

Try this now:

1. Locate your Claude Desktop config file
2. Add the filesystem server pointing to a safe directory (like Documents)
3. Restart Claude Desktop
4. Ask Claude: "List the files in my Documents folder"

If it works, you've successfully set up MCP!

---

Looking Ahead

You now know how to configure MCP servers. In the next module, we'll explore the pre-built servers available in the ecosystem. You'll learn what each one does and when to use it, giving you a toolkit of ready-made integrations.

---

Next up: Module 4 - Available MCP Servers