MCP Servers

Architecture Diagram

This diagram shows how Claude Code acts as the MCP client, connecting to one or more MCP servers, each of which bridges to an external service.

What is MCP?

MCP stands for Model Context Protocol. It is an open protocol created by Anthropic that standardizes how AI models connect to external data sources and tools. Before MCP, every integration was a one-off. Now there is a single protocol that any tool can implement.

Think of MCP like an API gateway specifically designed for AI. Instead of hardcoding integrations into the model, you declare which servers are available and the model discovers what each one can do at runtime.

How MCP Works

The flow is straightforward. When Claude Code starts, it reads your MCP server configuration and spawns each server process. The client and server then negotiate capabilities via an initialization handshake.

At runtime, the flow looks like this:

1. Discovery — Claude asks each server "what tools do you offer?" and gets back a list with names, descriptions, and input schemas
2. Selection — when you ask Claude a question, it decides which tool (if any) to call based on your request and the tool descriptions
3. Invocation — Claude sends a JSON-RPC tools/call request to the server with the tool name and arguments
4. Execution — the MCP server runs the action (queries a database, calls an API, reads a file) and returns the result
5. Response — Claude incorporates the result into its answer

Configuring MCP Servers

MCP servers are configured in your settings.json file (project-level .claude/settings.json or user-level ~/.claude/settings.json). The key is mcpServers, and each entry follows the same pattern: a name, a command to spawn the server, optional arguments, and optional environment variables.

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

That is the universal shape. Every MCP server follows it. The only things that change are the command, args, and env values.

Example: Filesystem MCP Server

The filesystem MCP server lets Claude read and write files outside the current project directory. This is useful when you need to access config files, logs, or data stored elsewhere on your machine.

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

The paths in args are the directories the server is allowed to access. Claude can only read and write within those directories — it cannot escape to the rest of your filesystem.

Example: Database MCP Server (PostgreSQL)

Want Claude to query your database directly? The PostgreSQL MCP server exposes tools for running SQL queries, listing tables, and inspecting schemas.

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/mydb"
      ]
    }
  }
}

Once configured, you can ask Claude things like "show me the top 10 orders from last week" and it will write and execute the SQL query through the MCP server, returning the results directly in your conversation.

Example: GitHub MCP Server

The GitHub MCP server gives Claude access to repositories, issues, pull requests, and more through the GitHub API.

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

With this configured, Claude can create pull requests, read issue details, search repositories, review code, and manage branches — all through natural language commands.

# Now you can ask Claude things like:
# "Create a PR for the changes on the feature/auth branch"
# "List all open issues labeled 'bug'"
# "What changed in PR #42?"

Building a Custom MCP Server

You can build your own MCP server in Python using the FastMCP framework. This is the quickest path to exposing any API or service to Claude.

Python quickstart with FastMCP

from mcp.server.fastmcp import FastMCP

# Create the server
mcp = FastMCP("my-tools")

# Define a tool using the @mcp.tool() decorator
@mcp.tool()
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    # In real code, call a weather API here
    return f"Weather in {city}: 72°F, sunny"

# Define a resource (read-only data Claude can access)
@mcp.resource("config://app")
def get_app_config() -> str:
    """Return the current application configuration."""
    return "{ \"debug\": false, \"version\": \"2.1.0\" }"

# Run the server
if __name__ == "__main__":
    mcp.run()

The @mcp.tool() decorator turns any function into an MCP tool. The function's docstring becomes the tool description that Claude reads when deciding which tool to call. Type hints define the input schema automatically.

Registering your custom server

{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["path/to/my_server.py"]
    }
  }
}

JavaScript/TypeScript alternative

If you prefer Node.js, the official @modelcontextprotocol/sdk package provides the same capabilities:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-tools",
  version: "1.0.0"
});

// Define a tool
server.tool(
  "get_weather",
  { city: z.string() },
  async ({ city }) => ({
    content: [{
      type: "text",
      text: `Weather in ${city}: 72°F, sunny`
    }]
  })
);

// Connect via stdio
const transport = new StdioServerTransport();
await server.connect(transport);

Security Considerations

MCP servers run code on your machine with your permissions. Treat them like any other dependency — trust matters.

Debugging MCP Servers

When an MCP server is not working, here is how to diagnose the problem.

Check MCP logs

Claude Code logs MCP server activity. Check the logs for connection errors, failed tool calls, or server crashes:

# MCP logs are in the Claude Code log directory
# Look for connection and initialization messages
claude --verbose

Test with mcp-inspector

The mcp-inspector is a standalone tool that connects to your MCP server and lets you test tools interactively — without involving Claude at all.

# Install and run the inspector
npx @modelcontextprotocol/inspector

# It opens a web UI where you can:
# - See all tools the server exposes
# - Call tools with custom arguments
# - View raw JSON-RPC messages