Claude Code MCP Servers: The Complete Setup Guide for 2026

MCP (Model Context Protocol) is the mechanism that lets Claude Code reach outside its terminal window and interact with your databases, APIs, GitHub, Slack, file systems, and hundreds of other tools. Without MCP, Claude Code is a very capable code writer. With the right MCP servers connected, it becomes an agent that can query your production database, open pull requests, search your documentation, and trigger deployments — all without leaving the session.

This guide covers how MCP actually works in Claude Code, how to configure servers correctly, which servers are worth adding, and the patterns that keep your setup fast and secure.

How MCP Works in Claude Code

MCP is an open protocol — it defines a standard way for tools to expose capabilities to AI clients. An MCP server is a process (local or remote) that implements this protocol, advertising a set of tools that Claude can call.

When you connect an MCP server to Claude Code, Claude sees the server’s tools in its tool list alongside built-in tools like Read, Write, and Bash. From Claude’s perspective, calling a GitHub MCP tool and calling a built-in tool look identical. The MCP layer is transparent.

Transport Types

MCP servers communicate over two transport types:

stdio runs a local process on your machine. Claude Code launches the process, pipes JSON-RPC messages to stdin, and reads responses from stdout. Best for tools that need direct system access (filesystem, local databases, local CLIs).

HTTP (SSE) connects to a remote server over the network. Claude Code sends HTTP requests; the server streams responses back via Server-Sent Events. Best for cloud services, team-shared servers, and anything you don’t want running locally.

For most third-party integrations (GitHub, Linear, Notion, Slack), you’ll use HTTP. For local tools (a custom database query interface, a local search index, local file operations beyond what the built-in tools provide), you’ll use stdio.

Configuration

MCP configuration lives in a JSON file. Claude Code supports three config locations:

~/.claude/mcp.json              — user-global (all projects)
.mcp.json                       — project-local (committed to git)
.claude/settings.json           — can include mcpServers key

The project-local .mcp.json is the right place for servers your whole team should use. Global ~/.claude/mcp.json is for personal tools you want everywhere.

Adding a Server via CLI

The fastest way to add a server is the claude mcp add command:

# Add a stdio server
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allow

# Add an HTTP server with a custom name
claude mcp add github --transport http https://mcp.github.com

# Add with scope (user = global, local = project)
claude mcp add github --scope user --transport http https://mcp.github.com

Manual Configuration

For more control, edit the JSON directly:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
      "env": {}
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

Important: Use ${ENV_VAR} syntax for credentials. Never hardcode tokens in config files.

Scope

Every server has a scope that controls where it’s available:

For team setups, commit .mcp.json to your repository. Every developer who pulls the repo gets the same MCP server configuration automatically.

How Context Usage Stays Manageable

The naive assumption is that every MCP server you add bloats Claude’s context with tool definitions. In 2026, that’s no longer the problem it once was.

Claude Code uses Tool Search — on-demand tool discovery that works like a retrieval index. Instead of loading every tool definition from every connected server upfront, Claude searches for relevant tools based on the current task and loads only what it needs.

The practical effect: connecting a GitHub server with 40 tools doesn’t add 40 tool definitions to every prompt. Claude fetches create_pull_request when it needs to create a PR, and ignores the other 39 tools unless they’re relevant. Independent measurements put context reduction at roughly 85-95% compared to clients that dump all definitions upfront.

This means you can connect more servers than you’d expect without performance degradation. The limit is practical: connecting 20+ servers increases startup time and makes it harder to understand what Claude has access to. 3-5 focused servers is the recommended range.

The Servers Worth Installing

GitHub (mcp.github.com)

The most widely used MCP server. Gives Claude Code the ability to read and create issues, open pull requests, list repository content, and search code.

claude mcp add github --scope user --transport http https://mcp.github.com
export GITHUB_TOKEN=ghp_your_token_here

Useful for: keeping Claude in context about the repo state, generating PR descriptions with full diff context, cross-referencing issues while coding.

Filesystem (@modelcontextprotocol/server-filesystem)

Extends Claude’s file access beyond the working directory. Useful when you need Claude to reference files outside the current project — documentation, config files, shared libraries.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/docs ~/shared

The server only allows access to directories you explicitly pass as arguments. Don’t pass / — scope it to specific paths.

PostgreSQL / SQLite (@modelcontextprotocol/server-postgres, @modelcontextprotocol/server-sqlite)

Gives Claude read access to your database schema and the ability to run queries. Essential for tasks involving data migrations, writing schema-aware queries, or debugging data issues.

{
  "mcpServers": {
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

Security note: Use a read-only database user for the MCP connection. If Claude only needs to understand the schema and run SELECT queries, there’s no reason to give it write access.

Brave Search / Exa (@modelcontextprotocol/server-brave-search)

Lets Claude search the web mid-session without context window limitations. Useful when you’re working on integrations, debugging third-party APIs, or need current documentation.

claude mcp add brave-search -- npx -y @modelcontextprotocol/server-brave-search
export BRAVE_API_KEY=your_key_here

Linear, Notion, Slack

These are available as official HTTP MCP servers from their respective vendors. Add them if your team uses these tools and you want Claude to create tickets, query documentation, or post updates as part of a workflow.

# Linear
claude mcp add linear --transport http https://mcp.linear.app

# Notion
claude mcp add notion --transport http https://mcp.notion.so

Context7 (mcp__context7-npx)

Fetches current documentation for any library on demand. Especially valuable because Claude’s training data doesn’t reflect library changes from the past year. When Claude would otherwise guess at API signatures, Context7 fetches the actual current docs.

claude mcp add context7 -- npx -y @upstash/context7-mcp

Usage: Claude will automatically use this when it needs documentation. You can also prompt it explicitly: “Use Context7 to fetch the current Next.js 15 App Router docs before answering.”

Security Practices

MCP servers run code. Before connecting any server, treat it with the same scrutiny you’d apply to any dependency.

Audit before installing. Check the source code of any community MCP server before running it. A server that has file system access and network access can exfiltrate data. Prefer official servers published by the tool vendor.

Minimal permissions. A database MCP server for schema inspection should use a read-only database user. A GitHub MCP server for reading issues doesn’t need write access. Configure credentials with the narrowest scope that covers your actual use case.

Never expose secrets in config files. Use ${ENV_VAR} references and set the actual values in your shell environment or a .env file that isn’t committed.

Project vs user scope. Don’t commit servers to .mcp.json that require personal credentials. Use --scope user for those and commit only servers that use shared team credentials or no credentials.

The prompt injection risk. MCP servers that return content from the web, user-submitted data, or third-party APIs can return content that attempts to inject instructions into Claude’s context. Be careful with servers that fetch arbitrary external content.

Debugging

When an MCP server isn’t working:

# List all configured servers and their status
claude mcp list

# Check server details and connection status
claude mcp get github

# Remove a misconfigured server
claude mcp remove github --scope user

Inside a session, run /mcp to see which servers are connected and which tools are available. If a server is connected but Claude isn’t using its tools, check that the tool names match what you’re expecting with /mcp.

For server-side debugging, add "debug": true to the server config:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "debug": true
    }
  }
}

This logs all JSON-RPC communication to ~/.claude/mcp-debug.log.

Building Your Own MCP Server

If you have internal tools — a deployment API, a metrics dashboard, a proprietary search index — you can expose them to Claude Code via a custom MCP server. The protocol is well-documented and implementations exist in Node.js, Python, Go, and Rust.

A minimal Node.js MCP server:

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

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

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "get_deployment_status",
    description: "Get the current deployment status for a service",
    inputSchema: {
      type: "object",
      properties: {
        service: { type: "string", description: "Service name" }
      },
      required: ["service"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "get_deployment_status") {
    const { service } = request.params.arguments;
    // your actual implementation
    return { content: [{ type: "text", text: `${service}: healthy, v2.3.1` }] };
  }
});

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

Register it:

claude mcp add deploy-server -- node /path/to/my-deploy-server.js

For team use, wrap it in a Docker image and expose it as an HTTP server so you don’t need Node.js installed on every developer’s machine.

Recommended Starting Configuration

If you’re setting up Claude Code from scratch, start with this minimal .mcp.json and expand based on actual need:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

GitHub gives Claude awareness of your repository state. Context7 keeps documentation current. These two cover the most common gaps in out-of-the-box Claude Code. Add database access, search, and internal tools as specific workflows demand them.

Further Reading

• Claude Code Best Practices: The Complete Guide
• Claude Code Hooks: 10 Real-World Examples
• How to Write a CLAUDE.md File
• Browse 165+ Real AI Coding Rules