Claude Code MCP Setup: A Practical 2026 Guide

The Model Context Protocol (MCP) is how Claude Code talks to external systems. GitHub, Slack, Linear, your database, your monitoring stack, and your browser can all become tool surfaces that Claude Code can call. This guide walks through how to set up MCP servers for Claude Code in 2026, the configuration patterns that hold up in real work, and the debugging steps when authentication or connection breaks.

Claude Code MCP: Quick Answer

• 
  What is Claude Code MCP? A standard for letting Claude Code call external tools. Each MCP server exposes one or more tools. Claude Code discovers them at startup and includes them in the tool list it can use during a session.


• 
  Where do I configure MCP servers? In ~/.claude/settings.json (user level) or .claude/settings.json in a project (project level). Project settings override user settings.


• 
  What MCP servers should I install first? GitHub for issues and PRs, then the systems your project already depends on: Linear or Jira for ticketing, Slack for team comms, Postgres or Sentry for backend work, Playwright for UI verification. Claude Code already has built-in file tools, so a separate filesystem server is usually optional.


• 
  How do I debug MCP issues? Run claude mcp list to see registered servers, claude mcp test <name> to verify a single server, and tail the Claude Code logs for stderr output from the server process.

What MCP actually is

MCP is a small protocol with a big payoff. Anthropic published the spec in 2024 and the ecosystem has compounded since. The mental model:

• 
  A server is a process that exposes tools. Each tool has a name, a description, and a JSON schema for arguments.


• 
  A client is the agent that wants to call those tools. Claude Code is one client. Cursor, OpenCode, and many others are also clients.


• 
  The protocol runs over stdio or HTTP. Claude Code launches local servers as subprocesses and talks to them over stdio. Remote servers run over HTTP.

You configure a server once. From then on, every Claude Code session in that scope sees the tools and can decide whether to call them.

Configuration file layout

Claude Code reads MCP configuration from two places.

User scope: ~/.claude/settings.json. Servers configured here are available to every Claude Code session you run.

Project scope: .claude/settings.json in the project root. Servers configured here are available only when you run Claude Code inside that project. Project scope overrides user scope, which is useful when one repo needs a different set of tools.

The minimal MCP block looks like this:

{

  "mcpServers": {

    "github": {

      "command": "npx",

      "args": ["-y", "@modelcontextprotocol/server-github"],

      "env": {

        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."

      }

    }

  }

}

Three things matter:

1. 
   command and args: how Claude Code launches the server. For npm-distributed servers, npx -y @scope/name is the standard pattern. For binaries, point at the absolute path.


2. 
   env: environment variables passed to the server. This is where API keys and tokens live.


3. 
   The key (github in the example): a name you choose. It shows up in claude mcp list and in the tool names Claude sees.

Common MCP servers worth setting up

The following five servers cover most day-to-day use. The full ranked list is in already gives Claude Code a visual session layer, tracker integration, and rich editor surfaces. The highest-leverage external MCP adds in Nimbalyst are usually the ones that connect Claude to systems outside the workspace: GitHub, Linear, Postgres, Sentry, or Playwright. You can wire those up through the same ~/.claude/settings.json configuration, and they will appear inside Nimbalyst sessions automatically.

Frequently Asked Questions

What is Claude Code MCP?

Claude Code MCP is the Model Context Protocol implementation that lets Claude Code call external tools. Each MCP server exposes one or more tools (read GitHub issues, query Postgres, post to Slack), and Claude Code discovers and calls them as part of a normal session.

Where do I put my MCP configuration?

User-scope MCP configuration goes in ~/.claude/settings.json. Project-scope configuration goes in .claude/settings.json inside the project root. Project scope overrides user scope. For team projects, commit a project-scope settings file with placeholder env values and document which secrets developers need to fill in.

Are MCP servers safe?

MCP servers run as subprocesses on your machine with the credentials you give them. Treat them like any other CLI tool. Only install servers from trusted sources. Use scoped tokens with the minimum permissions the server needs. For database servers, prefer read-only roles unless you explicitly want write access.

Can I write my own MCP server?

Yes. The MCP SDK has Python and TypeScript implementations. A minimal server is about 50 lines of code. The protocol is small enough that custom servers are practical, especially for internal tools.

Why is my MCP server not showing up in Claude Code?

Three usual causes. First, the JSON in settings.json has a syntax error. Run it through jq. Second, the command does not resolve. Use absolute paths for binaries. Third, the server itself is failing on startup. Run it manually in a terminal to see stderr.

How many MCP servers should I install?

Fewer than you think. A short tool list keeps the agent focused. Five or six well-chosen servers cover most workflows. If you find yourself with twenty servers, prune the long tail. The full ranked recommendation is in