Claude Code MCP setup guide: every server worth installing in 2026

Model Context Protocol (MCP) is the single biggest productivity multiplier for Claude Code in 2026 — and the single biggest source of foot-guns. This is the practical setup guide: which servers are worth installing, how to configure them, what the security model actually means, and the patterns that scale beyond personal use.

The 30-second mental model

MCP is a standard protocol for letting LLM clients (Claude Code, Cursor, Zed, Continue) talk to external tools (filesystems, databases, APIs, custom internal services). The protocol is JSON-RPC over stdio, websockets, or HTTP. The LLM sees MCP-exposed tools as standard function calls; the client handles the transport.

Three things to internalise:

1. MCP servers run locally on your machine (unless you explicitly configure a remote server). Filesystem and shell servers literally execute commands as your user.
2. The LLM decides when to call MCP tools. You can review tool calls before execution, but the default is auto-execute.
3. MCP definitions count against your prompt cache. Bloated tool sets = lower cache hit rate = higher cost.

The essential servers (start here)

1. @modelcontextprotocol/server-filesystem

The bread-and-butter — gives Claude Code direct read/write access to project files. You configure which directories are allowed.

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

Without it, Claude Code falls back to its built-in file tools — slightly more conservative but slower for large refactors.

2. @modelcontextprotocol/server-git

Git history, blame, log access. Critical for "why did this file change?" investigations. Install if you frequently use Claude Code for code archaeology or debugging.

3. @modelcontextprotocol/server-postgres (or your DB)

Read-only SQL access to your dev database. Lets Claude Code answer questions like "what's the schema for users?" or "show me example rows" without you copy-pasting. Always use a read-only credential.

4. @modelcontextprotocol/server-puppeteer

Browser automation for debugging frontend issues. Claude Code can screenshot your dev server, click around, and report what it sees. Cuts iteration time on visual bugs roughly in half.

5. @modelcontextprotocol/server-github

GitHub API access — search issues, read PRs, post comments. Useful for "what's the context on this ticket" or "summarise the discussion on PR #1234" workflows.

The selective servers (install if you use them)

• Linear / Notion / Slack — workspace integration if those are your primary tools.
• Sentry / Datadog / Grafana — observability if you're doing live debugging.
• Stripe / AWS / GCP — only if you're comfortable letting an LLM read your production config. Default to no.

The servers to AVOID by default

• Shell execution servers without a sandbox. Claude Code is good but not perfect; auto-executing arbitrary shell commands is how you end up with deleted files. Use the built-in Bash tool with the standard permission prompt instead.
• Write-access database servers. Read-only is fine; write access invites destructive accidents.
• Production-credentialed cloud APIs. Test against staging.

Where to put the config

Claude Code reads ~/.claude/mcp_servers.json (global) and <project>/.claude/mcp_servers.json (per-project). Project-level wins on conflict. Project config commits to git for shared team setup.

Format:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "/path/to/project"]
    },
    "postgres-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://readonly@localhost/dev"],
      "env": { "POSTGRES_PASSWORD": "dev_only_no_secrets" }
    }
  }
}

After editing, restart Claude Code (Cmd+R in the chat surface). Use /mcp to list active servers and verify they connected.

The security model (read this)

MCP servers run as your local user. They have the permissions your shell has. A malicious or poorly-written MCP server can:

• Read every file you can read
• Make outbound network requests with your credentials
• Modify your shell config to persist access

What this means in practice:

1. Only install MCP servers from sources you trust. @modelcontextprotocol/* is the official Anthropic-maintained set — those are reviewed. Third-party MCP packages on npm are not reviewed by anyone.
2. Audit the config you ship. Don't commit .claude/mcp_servers.json with hardcoded production credentials. Use env var indirection.
3. Approve tool calls before auto-execution for sensitive operations. Claude Code lets you enable per-tool approval prompts; use them for file write, shell exec, and external API calls.

Cost implications

Every MCP tool's JSON schema is added to the prompt at request time. Verbose schemas (especially auto-generated ones) can add 5-15K tokens per request. Without prompt caching that's $0.05-0.15 per request in overhead — small individually, $15-45/day at 300 requests.

Two mitigations:

1. Cache tool definitions. Claude Code does this automatically with the 5-minute TTL cache. Don't add/remove servers mid-session.
2. Audit tool descriptions. Some MCP servers ship verbose docstrings. If you control the server, trim aggressively. Every token costs you.

Patterns that scale (teams)

Solo use is easy. Team-wide deployment is harder. What works:

Shared per-project config

Commit .claude/mcp_servers.json to the repo. Use env var references for anything secret. Every developer runs the same MCP server set; Claude Code behaves consistently across the team.

Centrally managed allowlist

For regulated environments, maintain a team allowlist of approved MCP packages + versions in a separate repo. New developers npm install from the allowlist, not from arbitrary npm.

Run servers in containers

For high-security environments, wrap MCP servers in containers with minimal mounted volumes. The MCP protocol works over stdio, so the container boundary is enforceable. Adds operational overhead — only worth it if you handle regulated data.

Debugging when it breaks

claude /mcp lists connected servers. If a server isn't listed, three common causes:

1. Path to executable wrong. which npx to verify, use full path if needed.
2. Server crashed at startup. Run the command from your shell manually — most MCP servers print useful errors to stderr.
3. Permission denied on a referenced directory. Filesystem server silently exits if any of its allowed paths don't exist or aren't readable.

Logs: ~/Library/Logs/Claude/mcp-*.log on macOS, ~/.config/Claude/logs/mcp-*.log on Linux.

What's coming

MCP is moving fast. Three trends to watch:

1. Remote MCP servers — HTTP-served MCP for cloud-hosted tools. Useful for team-shared knowledge bases, internal APIs.
2. Subagent-scoped MCP — different MCP server sets per Claude Code subagent. Already supported, but underused. Lets the "search-agent" subagent have web search while the "code-agent" doesn't.
3. MCP marketplaces — Anthropic-curated discovery surface. Should improve trust signal for third-party servers.

Bottom line

Install the official Anthropic-maintained MCP servers, audit any third-party ones, commit a shared config per repo, use prompt caching to amortise the tool-definition overhead. Skip the shell-execution and write-access-DB servers unless you have a strong reason.

Done right, MCP makes Claude Code roughly 2× more productive without adding meaningful risk. Done wrong, it's a security incident waiting to happen.