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, 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 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.