{"slug": "claude-code-mcp-setup-a-practical-2026-guide", "title": "Claude Code MCP Setup: A Practical 2026 Guide", "summary": "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.", "body_md": "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.\n\n`~/.claude/settings.json`\n\n(user level) or `.claude/settings.json`\n\nin a project (project level). Project settings override user settings.`claude mcp list`\n\nto see registered servers, `claude mcp test <name>`\n\nto 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:\n\nYou configure a server once. From then on, every Claude Code session in that scope sees the tools and can decide whether to call them.\n\nClaude Code reads MCP configuration from two places.\n\n**User scope:** `~/.claude/settings.json`\n\n. Servers configured here are available to every Claude Code session you run.\n\n**Project scope:** `.claude/settings.json`\n\nin 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.\n\nThe minimal MCP block looks like this:\n\n```\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n      \"env\": {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"ghp_...\"\n      }\n    }\n  }\n}\n```\n\nThree things matter:\n\n`command`\n\nand `args`\n\n`npx -y @scope/name`\n\nis the standard pattern. For binaries, point at the absolute path.`env`\n\n`github`\n\nin the example)`claude mcp list`\n\nand 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.\n\nThe official GitHub MCP server lets Claude Code read issues, create pull requests, comment on PRs, and search code across repositories.\n\n```\n\"github\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n  \"env\": {\n    \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"ghp_...\"\n  }\n}\n```\n\nGenerate a fine-grained personal access token with `repo`\n\n, `read:org`\n\n, and `workflow`\n\nscopes for most workflows.\n\nClaude 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`\n\n, sandbox rules, and worktrees before you add a separate filesystem MCP server.\n\nA dedicated filesystem server still makes sense in two cases:\n\nIf you do need it, the config looks like this:\n\n```\n\"filesystem\": {\n  \"command\": \"npx\",\n  \"args\": [\n    \"-y\",\n    \"@modelcontextprotocol/server-filesystem\",\n    \"/Users/you/code/project-a\",\n    \"/Users/you/code/project-b\"\n  ]\n}\n```\n\nThe 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.\n\nFor team coordination. Claude Code can read recent channel history, post messages, and reply in threads.\n\n```\n\"slack\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@modelcontextprotocol/server-slack\"],\n  \"env\": {\n    \"SLACK_BOT_TOKEN\": \"xoxb-...\",\n    \"SLACK_TEAM_ID\": \"T0123...\"\n  }\n}\n```\n\nCreate a Slack app, install it to your workspace, and grab the bot token from OAuth and Permissions.\n\nFor ticket-driven work. Read issues, update status, leave comments.\n\n```\n\"linear\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@linear/mcp-server\"],\n  \"env\": {\n    \"LINEAR_API_KEY\": \"lin_api_...\"\n  }\n}\n```\n\nThe 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.\n\nFor 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:\n\n```\n\"postgres\": {\n  \"command\": \"npx\",\n  \"args\": [\n    \"-y\",\n    \"@modelcontextprotocol/server-postgres\",\n    \"postgresql://localhost/mydb\"\n  ]\n}\n```\n\nBe careful with permissions. Give Claude Code a read-only database role unless you explicitly want it to mutate.\n\nAfter editing your settings file, run:\n\n```\nclaude mcp list\n```\n\nEvery server you configured should appear. If one is missing, the JSON probably has a syntax error. Run the file through `jq`\n\nto confirm it parses.\n\nTo test a single server end-to-end:\n\n```\nclaude mcp test github\n```\n\nThis launches the server, lists its tools, and reports any errors. Most failures are auth-related: the token is missing, expired, or has wrong scopes.\n\n`npx -y @scope/name`\n\ndownloads 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`\n\nto avoid the lazy fetch, then point `command`\n\nat the global binary.\n\nIf you use `env`\n\nfor 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`\n\nto `.gitignore`\n\nfor project-level configs that contain secrets.\n\nFilesystem-server path arguments take absolute paths. `~/code/project`\n\ndoes not expand. Use `/Users/you/code/project`\n\n(or the equivalent on Linux and Windows).\n\nIf two MCP servers expose tools with the same name, Claude Code will prefer one and ignore the other. The `tools`\n\nfield in the server config can rename or filter tools. Use it when servers conflict.\n\nThe most common cause is a long-running auth flow that prompts on stderr. Run the server manually first (`npx -y @scope/name`\n\nin a terminal) to see prompts and complete any first-time auth.\n\nFor most servers, user level is the right scope. GitHub, Slack, Linear, and your filesystem are stable across projects.\n\nFor 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.\n\nA 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.\n\n[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`\n\nconfiguration, and they will appear inside Nimbalyst sessions automatically.\n\nClaude 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.\n\nUser-scope MCP configuration goes in `~/.claude/settings.json`\n\n. Project-scope configuration goes in `.claude/settings.json`\n\ninside 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.\n\nMCP 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.\n\nYes. 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.\n\nThree usual causes. First, the JSON in `settings.json`\n\nhas a syntax error. Run it through `jq`\n\n. Second, the `command`\n\ndoes not resolve. Use absolute paths for binaries. Third, the server itself is failing on startup. Run it manually in a terminal to see stderr.\n\nFewer 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/).", "url": "https://wpnews.pro/news/claude-code-mcp-setup-a-practical-2026-guide", "canonical_source": "https://dev.to/stravukarl/claude-code-mcp-setup-a-practical-2026-guide-424f", "published_at": "2026-07-22 14:45:40+00:00", "updated_at": "2026-07-22 15:01:53.178848+00:00", "lang": "en", "topics": ["artificial-intelligence", "developer-tools", "large-language-models", "ai-tools"], "entities": ["Anthropic", "Claude Code", "GitHub", "Slack", "Linear"], "alternates": {"html": "https://wpnews.pro/news/claude-code-mcp-setup-a-practical-2026-guide", "markdown": "https://wpnews.pro/news/claude-code-mcp-setup-a-practical-2026-guide.md", "text": "https://wpnews.pro/news/claude-code-mcp-setup-a-practical-2026-guide.txt", "jsonld": "https://wpnews.pro/news/claude-code-mcp-setup-a-practical-2026-guide.jsonld"}}