How to Setup MCP Servers: Complete Guide for Claude Code and AI Tools

MCP (Model Context Protocol) servers let your AI coding tool read files, query databases, call APIs, and interact with external services directly from the chat interface. To set one up with Claude Code: install the server package, add it to your ~/.claude.json config under "mcpServers", and restart Claude Code. Takes under five minutes for most servers.

• MCP is an open standard by Anthropic, launched November 2024
• Over 1,000 community MCP servers available as of 2025
• Works with Claude Code, Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients

What is Model Context Protocol (MCP)?

Model Context Protocol is an open standard that defines how AI models communicate with external tools and data sources. Think of it as a universal connector: instead of every AI tool building its own integrations, MCP servers expose a common interface that any compatible client can use.

Anthropic published the MCP specification in November 2024 and open-sourced the reference implementations. The protocol handles authentication, capability negotiation, and message passing between the AI client and the server process running on your machine (or remotely).

In practical terms: an MCP server is a small process that exposes tools (functions the AI can call), resources (data the AI can read), and prompts (templates the AI can use). Your AI client discovers what's available and calls them as needed.

How to setup MCP servers in Claude Code

Claude Code reads MCP configuration from ~/.claude.json (global) or .claude/settings.json (project-level). The setup process is the same regardless of which config file you use.

Step 1: Install the MCP server package

Most MCP servers are distributed as npm packages or Python packages. Install them globally so Claude Code can find the binary:

# npm example
npm install -g @modelcontextprotocol/server-filesystem

# Python example
pip install mcp-server-git

Step 2: Add the server to your config

Open ~/.claude.json and add an mcpServers block. If the file doesn't exist, create it:

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

The key ("filesystem") is the name you give the server. command is the binary to run. args are passed directly to the process.

Step 3: Restart Claude Code and verify

Quit and relaunch Claude Code. Run /mcp in the chat to see connected servers and their available tools. If a server shows as failed, check the error output with /mcp and verify the binary path is correct.

Adding environment variables

Servers that need API keys use an env block:

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

Never commit ~/.claude.json with real tokens. Use environment variable references if your shell supports them.

Popular MCP servers worth installing

The official MCP server directory lists reference implementations maintained by Anthropic. These are the most stable starting points:

Server	Package	What it does
Filesystem	@modelcontextprotocol/server-filesystem	Read/write files in specified directories
GitHub	@modelcontextprotocol/server-github	Search repos, read files, manage issues and PRs
PostgreSQL	@modelcontextprotocol/server-postgres	Run read-only queries against a Postgres database
Puppeteer	@modelcontextprotocol/server-puppeteer	Browser automation and web scraping
Fetch	@modelcontextprotocol/server-fetch	Fetch URLs and convert to Markdown
Memory	@modelcontextprotocol/server-memory	Persistent key-value memory across sessions
Slack	@modelcontextprotocol/server-slack	Read channels, post messages, list users
Git	mcp-server-git (Python)	Git log, diff, blame operations

Beyond the reference servers, community directories like awesome-mcp-servers list hundreds of integrations for services like Notion, Linear, Stripe, Supabase, and more.

MCP server configuration: full example

Here's a realistic ~/.claude.json with multiple servers configured:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects",
        "/Users/yourname/docs"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_yourtoken"
      }
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    }
  }
}

You can pass multiple directory paths to the filesystem server. Separate them as additional args in the array.

Project-level vs global MCP config

Claude Code supports two config locations with different scopes:

• Global: ~/.claude.json — servers available in every project
• Project-level: .claude/settings.json in your repo root — servers only active in that project

Use project-level config for servers tied to a specific codebase (a local Postgres instance, a project-specific API). Use global config for general-purpose servers like filesystem or fetch that you want everywhere. Both configs are merged at startup, with project-level settings taking precedence.

For team projects, committing .claude/settings.json with the MCP config (but without secrets) means everyone on the team gets the same tool setup automatically. Store secrets in environment variables and reference them from the config.

How to use MCP tools in Claude Code

Once servers are connected, you don't need special syntax. Claude Code sees the available tools and calls them automatically when relevant. You can also ask explicitly: "read the README from the filesystem server" or "query the users table in postgres."

To inspect what tools are available, run /mcp in the Claude Code chat. This lists all connected servers, their status, and the tools each exposes. If a server is disconnected, the command shows the error so you can debug it.

Claude Code also supports slash commands for other workflow shortcuts. MCP extends this further by letting you define custom tools that behave like built-in capabilities. See the full slash commands list for other built-in shortcuts worth knowing.

MCP with other AI tools (Cursor, Windsurf, Claude Desktop)

MCP is a cross-client standard. The server packages are identical regardless of which client you use. What changes is where the config lives:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor: Settings > MCP, or ~/.cursor/mcp.json
• Windsurf: Settings > Model Context Protocol

The mcpServers JSON structure is the same across all of them. Once you've configured a server for one client, copying the config block to another client's config file is usually all that's needed. See the MCP architecture docs for details on how clients discover and negotiate with servers.

If you're comparing Claude Code to other tools like Windsurf or Codex, MCP support is now a meaningful differentiator since it determines how extensible the tool is.

Troubleshooting MCP server issues

Most MCP setup problems fall into a few categories:

• Server fails to start: The binary isn't in PATH. Test by running the command manually in your terminal. Use absolute paths in the config if needed.
• Permission errors (filesystem): The directory path you passed doesn't exist or Claude Code can't read it. Verify the path and check macOS privacy settings under System Settings > Privacy & Security > Files and Folders.
• Auth errors (GitHub, Slack): Token is missing or expired. Re-generate the token and update the env block in your config.
• Tools not appearing: Run /mcp to check server status. A connected server with 0 tools usually means a version mismatch between client and server.

Claude Code logs MCP errors to ~/.claude/logs/. Check the most recent log file for stack traces if /mcp doesn't give enough detail.

If Claude Code itself is hitting rate limits while you're testing MCP-heavy workflows, that's a separate issue. Rate limit errors in Claude Code come from the Anthropic API, not from MCP servers.

Building your own MCP server

The MCP SDK is available for TypeScript and Python. A minimal server defines tools using a simple schema and handles incoming requests:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "get_time",
    description: "Returns the current UTC time",
    inputSchema: { type: "object", properties: {} }
  }]
}));

server.setRequestHandler("tools/call", async (req) => {
  if (req.params.name === "get_time") {
    return { content: [{ type: "text", text: new Date().toISOString() }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Point the command in your config at the compiled script and Claude Code will discover the get_time tool automatically. The MCP tools specification covers the full schema for defining inputs, outputs, and error handling.

Key takeaways

1. Install the server package globally with npm or pip
2. Add the server to ~/.claude.json under "mcpServers" with command, args, and optional env
3. Restart Claude Code and verify with /mcp
4. Use project-level config (.claude/settings.json) for repo-specific servers; commit it without secrets
5. The same server packages work across Claude Code, Claude Desktop, Cursor, and Windsurf
6. Check ~/.claude/logs/ and run /mcp for troubleshooting

Sources

• https://modelcontextprotocol.io - MCP specification and official documentation
• https://modelcontextprotocol.io/servers - Official MCP server directory
• https://modelcontextprotocol.io/docs/concepts/architecture - MCP architecture overview
• https://modelcontextprotocol.io/docs/concepts/tools - MCP tools specification
• https://github.com/modelcontextprotocol/typescript-sdk - MCP TypeScript SDK
• https://github.com/punkpeye/awesome-mcp-servers - Community MCP server directory