Claude Code MCP Servers - Setup, .mcp.json and Top Tools

Claude Code MCP servers are lightweight local processes that extend Claude Code beyond file reading and writing by connecting external tools through the Model Context Protocol. They enable querying databases, searching the web, managing GitHub issues, and interacting with APIs while keeping data private through bidirectional communication between Claude Code and each tool.

Claude Code MCP servers extend what Claude Code can do far beyond reading and writing files. By connecting external tools - databases, APIs, browsers, search engines - through the Model Context Protocol, Claude Code gains the ability to query production data, search the web, manage GitHub issues, and interact with virtually any service that exposes an MCP interface.

This guide covers everything needed to set up MCP servers in Claude Code: how .mcp.json configuration works, the best servers worth installing, real workflow examples, and troubleshooting for common issues that trip up new users.

What Are MCP Servers?

Claude Code MCP Servers is a topic that directly impacts how teams work day to day. Claude Code MCP servers extend what Claude Code can do far beyond reading and writing files. This guide breaks down the practical details you need to make an informed decision.

The Model Context Protocol (MCP) is an open standard created by Anthropic - the company behind Claude - that defines how AI assistants communicate with external tools and data sources. The full specification is available on the MCP documentation site. Think of it as a universal adapter - instead of building custom integrations for every service, MCP provides a single protocol that any tool can implement.

An MCP server is a lightweight process that:

• Exposes tools that Claude Code can call (e.g., query_database, search_web, create_issue)
• Provides resources like file contents, database schemas, or API documentation
• Runs locally on the same machine as Claude Code, keeping data private

The key distinction from traditional API integrations is that MCP servers are bidirectional. Claude Code does not just send requests - it discovers what tools are available, understands their parameters, and decides when to use them based on the task at hand.

Why MCP Matters for Claude Code

Without MCP servers, Claude Code operates within a sandbox of file reading, file writing, and terminal commands. That covers a lot of development work, but it misses entire categories of tasks:

• Database queries - Cannot check production data without manually running SQL
• Web search - Cannot look up documentation, error messages, or API references
• Browser automation - Cannot test web applications or capture screenshots with Puppeteer
• Third-party APIs - Cannot create GitHub issues, send Slack messages, or update project boards

MCP servers fill every one of these gaps. Once configured, Claude Code treats them as native capabilities - no prompting required to “use the search tool.” It simply searches when a search would help.

How to Set Up MCP Servers in Claude Code

Claude Code reads MCP server configuration from a file called .mcp.json in the project root directory. This file defines which servers to start, how to run them, and what environment variables they need.

Step 1: Create the Configuration File

Create .mcp.json in the root of the project:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
      "env": {}
    }
  }
}

Each server entry has three fields:

Step 2: Using the Claude Code CLI

The fastest way to add an MCP server is through the Claude Code CLI itself:

claude mcp add server-name -- npx -y @modelcontextprotocol/server-filesystem /path/to/directory

This command writes the entry to .mcp.json automatically. To verify it worked:

claude mcp list

That will display all configured servers and their connection status.

Step 3: Scope Configuration (Project vs Global)

Claude Code supports two scopes for MCP configuration:

• Project scope (default): .mcp.json in the project root. Servers are available only when working in that project.
• User scope: ~/.claude/.mcp.json in the home directory. Servers are available across all projects.

# Add to project scope (default)
claude mcp add my-server -- npx -y some-package

# Add to user/global scope
claude mcp add my-server --scope user -- npx -y some-package

Project scope is recommended for most setups. It keeps server configurations portable with the codebase and avoids loading unnecessary servers in unrelated projects.

Step 4: Verify the Connection

After adding a server, restart Claude Code (or start a new session) and look for confirmation in the startup output. The server name appears in the tool list:

> claude

╭──────────────────────────────────────────╮
│ Tools: filesystem, github, brave-search  │
╰──────────────────────────────────────────╘

If a server fails to start, Claude Code logs the error. Common causes include missing dependencies, incorrect paths, or invalid API keys - all covered in the troubleshooting section below.

Understanding .mcp.json Structure

Here is a complete .mcp.json example with multiple servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/mydb"],
      "env": {}
    }
  }
}

A few important notes:

• Server names must be unique within the file. They become the prefix for tool names (e.g., filesystem__read_file).
• Environment variables in env are passed only to that specific server process. They do not leak to other servers or to Claude Code itself.
• Connection strings and API keys should not be committed to version control. Use .env files or secrets management instead, and add .mcp.json to .gitignore if it contains credentials.

Best Claude Code MCP Servers

The MCP ecosystem has grown rapidly, with dozens of community-built servers available. These are the most useful Claude Code MCP servers for day-to-day development work.

1. Filesystem Server

What it does: Gives Claude Code controlled read and write access to directories outside the current project. Useful for monorepos, shared configurations, or accessing reference codebases.

Install:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/directory

Config snippet:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents", "/home/user/configs"],
    "env": {}
  }
}

Use case: Working on a microservices project where Claude Code needs to reference shared type definitions or proto files stored in a different repository. The filesystem server provides sandboxed access to specific directories without granting full disk access. For more on Claude Code workflows, see our Claude Code pricing breakdown.

Tools provided: read_file, write_file, list_directory, search_files, get_file_info, create_directory, move_file

2. GitHub Server

What it does: Full GitHub integration - create issues, manage pull requests, search repositories, read file contents from remote repos, and manage branches.

Install:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

Config snippet:

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

Use case: During a code review session, ask Claude Code to “look at the open PRs and summarize what each one changes.” It reads PR diffs, checks CI status, and can even leave review comments - all without leaving the terminal. Our which Claude model for coding guide helps you pick the right model for code review tasks.

Tools provided: create_issue, list_issues, create_pull_request, get_pull_request, search_repositories, get_file_contents, create_branch, push_files

Token setup: Generate a personal access token at GitHub’s token settings page with repo, issues, and pull_requests scopes.

3. PostgreSQL Server

What it does: Connects Claude Code to a PostgreSQL database for read-only queries. It discovers schemas automatically and lets Claude Code write and execute SQL based on natural language questions.

Install:

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://user:password@localhost:5432/dbname

Config snippet:

{
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://user:password@localhost:5432/myapp_development"
    ],
    "env": {}
  }
}

Use case: Debugging a data issue where users report incorrect totals. Ask Claude Code “how many orders from the last 7 days have a status of ‘pending’ but a payment_status of ‘completed’?” - it queries the database directly, finds the discrepancy, and suggests the fix. The PostgreSQL psql documentation covers the underlying query interface.

Tools provided: query (read-only SQL execution with automatic schema discovery)

Security note: Always use a read-only database user for MCP connections. The server enforces read-only mode, but defense in depth is worth the extra setup.

4. Brave Search Server

What it does: Web search through the Brave Search API. Claude Code can look up documentation, find error solutions, check API references, and research technologies without switching to a browser.

Install:

claude mcp add brave-search -- npx -y @modelcontextprotocol/server-brave-search

Config snippet:

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

Use case: Encountering an obscure error message during a build. Instead of copying the error, switching to a browser, and searching manually, Claude Code searches directly, finds the relevant Stack Overflow thread or GitHub issue, and applies the fix.

Tools provided: brave_web_search, brave_local_search

API key: Sign up at the Brave Search API portal. The free tier includes 2,000 queries per month - enough for most development workflows.

5. Puppeteer Server

What it does: Browser automation and screenshots. Claude Code can navigate to pages, fill out forms, click buttons, take screenshots, and extract content from rendered web pages.

Install:

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

Config snippet:

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

Use case: After making CSS changes to a web app, ask Claude Code to “navigate to localhost:3000/dashboard and take a screenshot.” It opens the page in a headless browser, captures the result, and can even compare it against a baseline to flag visual regressions. Our best AI code editors 2026 roundup covers how Claude Code stacks up against editor alternatives.

Tools provided: puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_fill, puppeteer_evaluate

6. SQLite Server

What it does: Similar to the PostgreSQL server but for SQLite databases. Ideal for local development databases, mobile app backends, or embedded analytics.

Install:

claude mcp add sqlite -- npx -y @modelcontextprotocol/server-sqlite --db-path /path/to/database.db

Config snippet:

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

Use case: Working on a mobile app that stores data locally in SQLite. Ask Claude Code to “check the schema and find any users who signed up in the last week but haven’t completed onboarding.” Our AI tools for developers roundup covers more workflows where Claude Code shines.

Tools provided: read_query, write_query, create_table, list_tables, describe_table, append_insight

7. Memory Server

What it does: Provides persistent key-value storage that survives between Claude Code sessions. Useful for storing project context, preferences, architectural decisions, or custom instructions that should carry forward.

Install:

claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

Config snippet:

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

Use case: Saving architectural decisions like “the project uses repository pattern for data access” or “all API responses follow the JSON:API spec.” Claude Code retrieves these notes automatically in future sessions, maintaining continuity across conversations.

Tools provided: create_entities, create_relations, search_nodes, open_nodes, delete_entities

8. Fetch Server

What it does: Makes HTTP requests and converts web page content to Markdown for easy consumption. Useful for reading documentation, API specs, or any URL content without leaving Claude Code.

Install:

claude mcp add fetch -- npx -y @modelcontextprotocol/server-fetch

Config snippet:

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

Use case: Ask Claude Code to “read the Stripe API documentation for payment intents” and implement the server-side handler. It fetches the docs, extracts the relevant sections, and writes the implementation.

Tools provided: fetch (GET/POST with automatic HTML-to-Markdown conversion)

Can Claude Code Use Custom MCP Servers?

Yes - and building custom MCP servers is one of the most powerful ways to extend Claude Code for specific workflows. Any process that speaks the MCP protocol can serve as a tool provider.

Building a Custom Server with Python

The official MCP Python SDK provides a framework for creating servers:

pip install mcp

Here is a minimal example that exposes a custom tool:

from mcp.server import Server
from mcp.types import Tool, TextContent
import json

server = Server("my-custom-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="lookup_customer",
            description="Look up customer details by email address",
            inputSchema={
                "type": "object",
                "properties": {
                    "email": {"type": "string", "description": "Customer email"}
                },
                "required": ["email"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "lookup_customer":
        # Custom logic here - hit internal API, query database, etc.
        customer = await fetch_customer(arguments["email"])
        return [TextContent(type="text", text=json.dumps(customer))]

if __name__ == "__main__":
    import asyncio
    from mcp.server.stdio import stdio_server
    asyncio.run(stdio_server(server))

Register it in .mcp.json:

{
  "my-custom-server": {
    "command": "python",
    "args": ["scripts/mcp/my_custom_server.py"],
    "env": {}
  }
}

Building a Custom Server with TypeScript

For TypeScript projects, the official TypeScript SDK works the same way:

npm install @modelcontextprotocol/sdk

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

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

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "deploy_preview",
    description: "Deploy a preview environment for the current branch",
    inputSchema: {
      type: "object",
      properties: {
        branch: { type: "string", description: "Git branch name" }
      },
      required: ["branch"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "deploy_preview") {
    const result = await deployPreview(request.params.arguments.branch);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }
});

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

Custom Server Ideas for Development Teams

Real Workflow Examples

Workflow 1: Full-Stack Bug Investigation

A user reports that order totals are incorrect. Here is how Claude Code handles this with MCP servers configured:

1. GitHub server - Reads the issue details and linked PR
2. Postgres server - Queries recent orders to find the pattern
3. Filesystem server - Reads the pricing calculation logic in a shared library
4. Brave Search server - Looks up the rounding behavior of the decimal library in use
5. Claude Code identifies the bug, writes the fix, and creates a PR

Without MCP servers, steps 2 and 4 would require manual intervention - copying SQL to a terminal, searching the web separately, and pasting results back. Our best AI coding assistants 2026 roundup covers how this kind of orchestrated workflow compares across tools.

Workflow 2: Documentation-Driven Development

Starting a new API endpoint:

1. Fetch server - Reads the OpenAPI spec from the documentation site
2. Claude Code generates the route handler, request validation, and response types
3. Postgres server - Checks the actual database schema to ensure types match
4. Puppeteer server - Hits the endpoint on localhost and validates the response

Workflow 3: Codebase Migration

Migrating from one framework to another:

1. Filesystem server - Reads patterns from a reference project that already uses the target framework
2. Claude Code applies the migration file by file
3. Memory server - Stores decisions made during migration (“chose X pattern for Y reason”)
4. Brave Search server - Looks up migration guides when encountering edge cases

Claude Code vs Cursor MCP: What Is the Difference?

Both Claude Code and Cursor support MCP servers, but the implementations differ in important ways. For a head-to-head comparison of these two AI coding tools, see our Cursor vs Windsurf breakdown.

Configuration

Runtime Behavior

When to Choose Each

Claude Code is the better fit when:

• The workflow is terminal-centric (devops, scripting, server administration)
• The project requires deep codebase understanding across many files
• Agentic execution - running tests, committing code, managing git - is important
• The team prefers CLI-based configuration that lives in version control

Cursor is the better fit when:

• Visual code editing with inline AI suggestions is the priority
• The team wants a traditional IDE experience with MCP as a supplement
• Rapid prototyping with visual feedback matters more than terminal workflows
• Users prefer GUI-based server management over CLI configuration

Windsurf also supports MCP servers with a similar configuration approach. The core protocol is identical across all three tools - a server built for one works with all of them.

Portability Across Tools

Since MCP is an open standard, the same .mcp.json configuration works across Claude Code, Cursor, and Windsurf with minimal changes. A team can standardize on a set of MCP servers and have every developer use their preferred editor.

The main portability consideration is the config file location:

• Claude Code: .mcp.json (project root)
• Cursor: .cursor/mcp.json
• Windsurf: .windsurf/mcp.json or settings UI

A common pattern is to maintain a canonical mcp-servers.json in the project root and symlink or copy it to each tool’s expected location. Our GitHub Copilot vs Cursor comparison covers how config portability differs across editors.

Troubleshooting Claude Code MCP Servers

Server Fails to Start

Symptom: Claude Code reports “failed to connect to server” on startup.

Common causes:

1. Missing Node.js or Python - The command field references a runtime that is not installed. Fix: ensure node, npx, python, or uvx is on the system PATH.

2. Package not found - The npm or pip package name is misspelled. Fix: run the install command manually to verify it works:

npx -y @modelcontextprotocol/server-filesystem /tmp

3. Permission denied - The server process cannot access the specified directory or port. Fix: check file permissions and ensure no other process is using the same port.

Tools Not Appearing

Symptom: The server starts but no tools show up.

Fixes:

• Restart Claude Code after modifying .mcp.json
• Check that the server name in .mcp.json does not contain spaces or special characters
• Verify the server actually implements the tools/list handler

Environment Variables Not Loading

Symptom: Server starts but API calls fail with authentication errors.

Fixes:

• Double-check the env block in .mcp.json - variable names are case-sensitive
• Ensure API keys do not have trailing whitespace or newline characters
• Test the API key outside of MCP first:

curl -H "X-Subscription-Token: BSA_your_key" "https://api.search.brave.com/res/v1/web/search?q=test"

Slow Server Responses

Symptom: Claude Code hangs or times out waiting for MCP tool results.

Fixes:

• Database servers: Add connection pooling or reduce query timeout
• Puppeteer: Ensure Chromium is already downloaded (npx puppeteer browsers install chrome)
• Network-dependent servers: Check firewall rules and proxy settings
• All servers: The MCP protocol has a default timeout. For long-running operations, consider breaking them into smaller steps

Windows-Specific Issues

On Windows, path handling requires extra attention:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\username\\projects"],
    "env": {}
  }
}

• Use double backslashes in JSON paths, or forward slashes (both work)
• If npx is not found, use the full path: C:\\Program Files\\nodejs\\npx.cmd
• For Python servers, use the full path to the Python executable

Debugging Server Communication

Enable verbose logging to see the raw MCP protocol messages:

claude --mcp-debug

This prints every message exchanged between Claude Code and MCP servers, making it easy to identify where communication breaks down.

Advanced Configuration Tips

Conditional Server Loading

Not every server needs to run for every task. Use separate .mcp.json files for different contexts:

# For database work
cp .mcp-database.json .mcp.json

# For web development
cp .mcp-web.json .mcp.json

Or use the CLI to quickly toggle servers:

claude mcp remove postgres
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres $DATABASE_URL

Security Best Practices

1. Never commit credentials - Add .mcp.json to .gitignore if it contains API keys. Instead, commit a .mcp.json.example with placeholder values.

2. Use read-only database users - Even though the Postgres MCP server enforces read-only mode, create a dedicated database user with SELECT-only permissions.

3. Limit filesystem access - The filesystem server accepts a list of allowed directories. Only grant access to directories Claude Code actually needs.

4. Rotate API keys regularly - MCP server API keys should follow the same rotation policy as any other credential.

Team Configuration Patterns

For teams, a shared configuration template works well:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "internal-api": {
      "command": "python",
      "args": ["scripts/mcp/internal_api_server.py"],
      "env": {
        "API_BASE_URL": "${INTERNAL_API_URL}"
      }
    }
  }
}

Each developer sets environment variables locally while the server configuration stays consistent across the team.

The Bottom Line

Claude Code MCP servers transform a capable terminal-based coding assistant into a fully connected development environment. The setup takes minutes - create a .mcp.json file, add server entries, and restart Claude Code. From there, the assistant can query databases, search the web, manage GitHub workflows, and interact with any custom tool the project needs.

Start with the filesystem and GitHub servers for immediate productivity gains. Add Brave Search when web lookups become a frequent need. Connect database servers when working on data-heavy features. Build custom servers when the team has internal tools that would benefit from AI integration.

The MCP ecosystem is still growing rapidly. New servers appear weekly on the MCP servers registry, and building a custom server requires less than 100 lines of code. For teams already using Claude Code, MCP servers are the highest-impact upgrade available in 2026.

FAQ

Q: What are Claude Code MCP servers?

Claude Code MCP servers are lightweight local processes that extend Claude Code beyond reading and writing files. They expose tools Claude Code can call, such as query_database, search_web, or create_issue, provide resources like file contents and database schemas, and run locally on the same machine as Claude Code to keep data private while enabling external integrations.

Q: How does the Model Context Protocol work with Claude Code?

The Model Context Protocol is an open standard created by Anthropic that defines how AI assistants communicate with external tools and data sources. Instead of building custom integrations for every service, MCP provides a single universal adapter. MCP servers are bidirectional, so Claude Code discovers available tools, understands their parameters, and decides when to use them based on the task.

Q: Why do MCP servers matter for Claude Code workflows?

Without MCP servers, Claude Code operates within a sandbox of file reading, file writing, and terminal commands. That misses entire categories of tasks like database queries, web search, browser automation, and third-party APIs such as GitHub or Slack. MCP servers fill those gaps and let Claude Code treat external services as native capabilities without explicit prompting.

Q: What can Claude Code do once MCP servers are configured?

Once configured, Claude Code can query production data through databases, search the web for documentation and error messages, manage GitHub issues, automate browsers to test web applications or capture screenshots, and interact with virtually any service that exposes an MCP interface. It uses these tools automatically when they would help complete a task, with no extra prompting required.

Related Reading

• Claude Code Review: Full Tool Overview - In-depth look at Claude Code features, pricing, and ratings
• Claude Review - Full review of Anthropic’s Claude AI assistant
• Cursor Review - AI-native code editor with Composer and parallel agents
• Windsurf Review - AI code editor with MCP server support
• Claude Code Pricing in 2026 - Complete breakdown of Claude Code plans and costs
• Which Claude Model for Coding - Choosing the right Claude model for development tasks
• Cursor vs Windsurf - Head-to-head comparison of two popular AI code editors
• Best AI Code Editors 2026 - Comparing Cursor, Windsurf, and GitHub Copilot

External Resources

• Model Context Protocol Official Documentation - Full protocol specification and server registry
• Claude Code Documentation - Official setup guides and configuration reference
• MCP Servers GitHub Repository - Source code for all official MCP servers