Claude Code MCP Setup: A Practical 2026 Guide

Anthropic's Model Context Protocol (MCP) enables Claude Code to interact with external systems like GitHub, Slack, and Linear. A 2026 guide details configuring MCP servers via `~/.claude/settings.json` or project-level `.claude/settings.json`, with commands like `claude mcp list` for management. The guide recommends five key servers covering GitHub, filesystem, Slack, and Linear, emphasizing that the filesystem server should not be the primary safety tool.

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/settings.json user level or .claude/settings.json in a project project level . Project settings override user settings. 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.MCP is a small protocol with a big payoff. Anthropic published the spec in 2024 and the ecosystem has compounded since. The mental model: 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. 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: command and args npx -y @scope/name is the standard pattern. For binaries, point at the absolute path. env github in the example claude mcp list and in the tool names Claude sees.The following five servers cover most day-to-day use. The full ranked list is in Best Claude Code MCP servers https://nimbalyst.com/blog/best-claude-code-mcp-servers/ , but if you only set up a few, set up these. The official GitHub MCP server lets Claude Code read issues, create pull requests, comment on PRs, and search code across repositories. "github": { "command": "npx", "args": "-y", "@modelcontextprotocol/server-github" , "env": { "GITHUB PERSONAL ACCESS TOKEN": "ghp ..." } } Generate a fine-grained personal access token with repo , read:org , and workflow scopes for most workflows. Claude Code already ships built-in file tools plus permission rules and sandboxing. If your goal is to keep Claude away from secrets or sensitive directories, prefer permissions.deny , sandbox rules, and worktrees before you add a separate filesystem MCP server. A dedicated filesystem server still makes sense in two cases: If you do need it, the config looks like this: "filesystem": { "command": "npx", "args": "-y", "@modelcontextprotocol/server-filesystem", "/Users/you/code/project-a", "/Users/you/code/project-b" } The trailing arguments are the allowed roots. Anything outside those roots is invisible to that MCP server. This is useful, but it should not be your first safety tool for Claude Code. For team coordination. Claude Code can read recent channel history, post messages, and reply in threads. "slack": { "command": "npx", "args": "-y", "@modelcontextprotocol/server-slack" , "env": { "SLACK BOT TOKEN": "xoxb-...", "SLACK TEAM ID": "T0123..." } } Create a Slack app, install it to your workspace, and grab the bot token from OAuth and Permissions. For ticket-driven work. Read issues, update status, leave comments. "linear": { "command": "npx", "args": "-y", "@linear/mcp-server" , "env": { "LINEAR API KEY": "lin api ..." } } The token is created in your Linear settings under API. Personal API keys give Claude Code your own permissions, so create a service account if your team has multiple humans. For projects that touch a database, an MCP server for your specific stack is the highest-leverage tool you can give Claude Code. Postgres, MySQL, SQLite, MongoDB, and several others have MCP servers. The Postgres example: "postgres": { "command": "npx", "args": "-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb" } Be careful with permissions. Give Claude Code a read-only database role unless you explicitly want it to mutate. After editing your settings file, run: claude mcp list Every server you configured should appear. If one is missing, the JSON probably has a syntax error. Run the file through jq to confirm it parses. To test a single server end-to-end: claude mcp test github This launches the server, lists its tools, and reports any errors. Most failures are auth-related: the token is missing, expired, or has wrong scopes. npx -y @scope/name downloads the server on first run. On a slow connection or behind a corporate proxy, the first launch can hang. Pre-install the server globally with npm install -g @scope/name to avoid the lazy fetch, then point command at the global binary. If you use env for tokens, make sure your shell history and CI logs do not capture the file. The settings file should be in your dotfiles, not in any committed repo. Add .claude/settings.json to .gitignore for project-level configs that contain secrets. Filesystem-server path arguments take absolute paths. ~/code/project does not expand. Use /Users/you/code/project or the equivalent on Linux and Windows . If two MCP servers expose tools with the same name, Claude Code will prefer one and ignore the other. The tools field in the server config can rename or filter tools. Use it when servers conflict. The most common cause is a long-running auth flow that prompts on stderr. Run the server manually first npx -y @scope/name in a terminal to see prompts and complete any first-time auth. For most servers, user level is the right scope. GitHub, Slack, Linear, and your filesystem are stable across projects. For database servers, monitoring servers, and project-specific APIs, project level is cleaner. Each repo gets only the tools it actually needs, and Claude Code's tool list stays short. A short tool list matters more than people expect. The model has to consider every tool on every turn. A bloated tool list slows the agent down and increases the chance it picks the wrong tool. Nimbalyst https://nimbalyst.com 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. 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. 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. 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. 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. 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. 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 Best Claude Code MCP servers https://nimbalyst.com/blog/best-claude-code-mcp-servers/ .