MCP Guide — Connecting External Tools to Claude

Last verified: March 24, 2026 / MCP SDK: Python 1.x, TypeScript 1.x / Claude Desktop latest

Claude has powerful conversational abilities out of the box, but tasks like querying an internal database, managing a GitHub repository, or reading and writing the local file system are not available by default.

MCP (Model Context Protocol) is an open standard that solves this problem. Just as a USB-C port connects many different devices using a single standard, MCP connects AI applications to any external system in a standardized way.

This guide explains how MCP works and walks you through the steps to connect MCP servers to Claude Desktop and Claude Code.

What is MCP — Overall Architecture

Understanding the Three Roles

The MCP ecosystem is made up of three roles: host / client / server.

Claude Desktop (host)
  ├── MCP Client A  ←→  Filesystem Server (local files)
  ├── MCP Client B  ←→  GitHub Server (GitHub API)
  └── MCP Client C  ←→  Slack Server (Slack API)

A host can use multiple MCP servers simultaneously. You can read local files and interact with GitHub all within a single conversation in Claude Desktop.

Three Types of Capabilities MCP Servers Can Provide

MCP servers can expose three types of resources to clients.

Why MCP Instead of Direct API Calls

Problems with calling APIs directly:

• Each tool requires handling its own authentication, error handling, and data formats
• Prompt engineering to teach the LLM how to use each tool becomes increasingly complex
• Every time you add a tool, you need to change the application code

Benefits of using MCP:

• Standardization: All servers communicate using the same protocol, so an MCP client written once is compatible with all servers
• Ecosystem: Hundreds of community-built servers are available to use immediately
• Security: The host can explicitly control what a server can do — which tools are available and what data can be accessed

Using Pre-Built Servers — Ready-to-Use Server List

MCP servers provided by Anthropic and the community are listed at github.com/modelcontextprotocol/servers.

Servers Provided by Anthropic

Finding Community Servers

Beyond the official list, you can find servers at the following resources:

• modelcontextprotocol.io/servers — Official catalog
• mcp.so — Community-run server directory
• npm / PyPI — Packages starting with @modelcontextprotocol/server-

Common stumbling block: "I don't know which server to use"

Start by working backwards from your goal. "I want to work with files" maps to Filesystem; "I want to use GitHub" maps to the GitHub server. If you can't find what you need, search npm for mcp server, or see the custom server section below.

Configuring Claude Desktop

MCP settings for Claude Desktop are managed in a JSON file called claude_desktop_config.json.

Config File Location

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

open ~/Library/Application\ Support/Claude/

%APPDATA%\Claude\claude_desktop_config.json

Create the file if it does not already exist.

Basic Config File Structure

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR_NAME": "value"
      }
    }
  }
}

List each server you want to use as a key inside mcpServers. The key name (e.g., "filesystem") is how Claude identifies the server within a conversation.

Example 1: Filesystem Server (Local File Access)

# Verify the server can run via npx (automatically downloaded on first use)
npx -y @modelcontextprotocol/server-filesystem --help

claude_desktop_config.json:

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

The paths at the end of args become the directories Claude is allowed to access. You can specify multiple paths. For security, limit access to only the directories that are necessary.

Example 2: GitHub Server

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

Generate a GitHub Personal Access Token at github.com/settings/tokens. The required scopes depend on what you want to do; repo:read is sufficient for read-only access.

Example 3: Configuring Multiple Servers at Once

{
  "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_xxxxxxxxxxxxxxxxxxxx"
      }
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

After saving the config, you must fully restart Claude Desktop. Once restarted, a hammer icon in the chat input area confirms that the MCP servers are recognized.

Common stumbling block: The hammer icon does not appear

1. Check for JSON syntax errors (missing commas, unmatched brackets, etc.)
2. Verify that the command path (npx, uvx, node, etc.) is correct. Running which npx to find the full path and specifying it explicitly can help
3. Quit Claude Desktop completely from the Dock and restart it
4. On macOS, log files are at ~/Library/Logs/Claude/ and contain error details

Configuring Claude Code

In Claude Code, you can configure MCP on a per-project basis by placing a .mcp.json file in the project root directory. Committing this file to your repository lets the entire team share the same MCP environment.

Structure of .mcp.json

The structure of .mcp.json is the same format as Claude Desktop's claude_desktop_config.json.

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

Using "." targets the current project root. Environment variables can be referenced using the ${ENV_VAR_NAME} syntax. Manage actual secrets (API keys, tokens) via a .env file or CI/CD secret management — do not write them directly into .mcp.json.

Managing Servers with the claude mcp Command

Claude Code lets you manage MCP servers with the claude mcp command.

# List registered MCP servers
claude mcp list

# Add an MCP server (project scope)
claude mcp add filesystem npx -- -y @modelcontextprotocol/server-filesystem .

# Add an MCP server (global scope)
claude mcp add --scope global github npx -- -y @modelcontextprotocol/server-github

# View details of a server
claude mcp get filesystem

# Remove a server
claude mcp remove filesystem

About scopes:

Verifying the Setup in Claude Code

Use the /mcp slash command inside a Claude Code session to check the status of connected MCP servers.

/mcp

If the tools are loaded correctly, you will see a list of available tools.

Common stumbling block: Added .mcp.json but tools are not being used

Claude Code reads .mcp.json at startup. After adding or modifying the file, exit the Claude Code session with /exit and restart it. Use the /mcp command to verify the connection status.

Building Your Own Server

When no pre-built server fits your needs, you can build your own. The MCP SDK is available for both TypeScript and Python.

A Minimal Server in TypeScript

Prerequisites: Node.js 18 or later

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install --save-dev typescript @types/node
npx tsc --init

src/index.ts:

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

// Create a server instance
const server = new McpServer({
  name: "my-server",
  version: "1.0.0",
});

// Define a tool
server.tool(
  "greet",
  "Greet a person by name",
  {
    name: z.string().describe("The name of the person to greet"),
  },
  async ({ name }) => {
    return {
      content: [
        {
          type: "text",
          text: `Hello, ${name}!`,
        },
      ],
    };
  }
);

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Server started"); // For STDIO servers, always write to stderr

Add a build script to package.json and build the project:

npx tsc
node dist/index.js

A Minimal Server in Python

Prerequisites: Python 3.10 or later, the uv package manager

uv init my-mcp-server
cd my-mcp-server
uv add "mcp[cli]"

server.py:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def greet(name: str) -> str:
    """Greet a person by name.

    Args:
        name: The name of the person to greet
    """
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="stdio")

uv run server.py

Registering Your Custom Server with Claude Desktop

Once you have built and tested your server, add it to claude_desktop_config.json.

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}

For Python:

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/my-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

Always use absolute paths. Relative paths will not work.

Debugging and Troubleshooting

Checking Claude Desktop Logs

# Watch logs in real time
tail -f ~/Library/Logs/Claude/mcp*.log

# Open the logs folder
explorer "$env:APPDATA\Claude\logs"

Testing Servers in Isolation with MCP Inspector

Before deploying a server, you can verify its behavior using MCP Inspector, a developer tool.

npx @modelcontextprotocol/inspector node dist/index.js

A browser window opens where you can inspect and test the server's tools, resources, and prompts through a GUI.

Common Errors and Solutions

Common stumbling block: Python's uv command not found

uv is a relatively new tool and may not be on the PATH when Claude Desktop launches. Run which uv to find the full path (e.g., /Users/yourname/.cargo/bin/uv) and use that full path in the command field.

Security Considerations

MCP greatly expands Claude's capabilities, but that comes with risk. When using third-party servers or deploying to production, keep the following in mind.

Minimize the Access Scope

When configuring the Filesystem server, limit the directories Claude can access to the bare minimum.

// Bad: access to the entire home directory
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname"]

// Good: only a specific project directory
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/my-project/docs"]

Restrict API Token Permissions

Follow the principle of least privilege for tokens such as GitHub tokens: grant only the scopes that are needed. If read-only access is sufficient, do not grant write permissions.

Use Only Trusted Servers

Before using a community-built MCP server, check the following:

• Is the source code publicly available? (Even for npm / PyPI packages, verify the original repository)
• Is it maintained by a reputable developer or organization?
• Does it access more data than it needs to?

Do Not Write Secrets in Config Files

.mcp.json is often committed to a repository, so do not write secrets (API keys, tokens) directly in the file.

// Bad: token written directly
"env": { "GITHUB_TOKEN": "ghp_abc123..." }

// Good: reference an environment variable
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }

Manage actual tokens via a .env file (added to .gitignore) or your CI/CD secret management system.

Tool Execution Approval Flow

When Claude attempts to invoke an MCP Tool, Claude Desktop and Claude Code will show the user an approval dialog before proceeding (depending on the host implementation). Check your host configuration to ensure that important operations — such as deleting files or writing to external services — are not auto-approved.

Next Steps

Now that you have the MCP basics down, deepen your understanding with these resources:

• API Guide — Integrating Claude into Your App — How to call the Claude API directly to build applications. Combining it with MCP lets you build even more powerful systems
• Official MCP Server Catalog — A list of community-built MCP servers
• MCP Architecture Deep Dive — Details on the transport layer (STDIO vs HTTP/SSE) and the protocol itself
• MCP SDK Reference (TypeScript) — API documentation for the TypeScript SDK
• MCP SDK Reference (Python) — API documentation for the Python SDK