{"slug": "mcp-servers-in-claude-code-the-minimal-setup-and-when-you-should-skip-mcp", "title": "MCP servers in Claude Code: the minimal setup, and when you should skip MCP entirely", "summary": "A developer outlines a minimal setup for MCP servers in Claude Code, noting that a single CLI command suffices and that many teams may not need MCP at all. The post details configuration scopes, environment variable expansion, and common failure modes such as PATH issues, missing environment blocks, and startup timeouts.", "body_md": "Most MCP setup guides start with a wall of JSON. You don't need it. Claude Code can register an MCP server with one CLI command, and for a lot of teams the right number of MCP servers is zero — a shell command in a rules file does the same job with less context overhead. This is the minimal path, the config that actually gets written to disk, and the handful of failure modes that account for almost every \"my server doesn't show up\" thread.\n\nFor a local (stdio) server, this is the whole setup:\n\n```\nclaude mcp add github -- npx -y @modelcontextprotocol/server-github\n```\n\nThen inside a session:\n\n```\n/mcp\n```\n\n`/mcp`\n\nshows every configured server, its connection state, and the tools it exposes. If your server is listed and connected, you're done. If it isn't, skip to the failure modes section — the cause is almost always one of four things.\n\nThe `--`\n\nseparator matters: everything after it is the command Claude Code runs to start the server process. Flags before it belong to `claude mcp add`\n\nitself.\n\nEvery MCP server has a scope, and the scope decides which file it's written to and who else gets it. This is the part most people discover by accident when a server follows them into an unrelated project — or doesn't follow them into the one where they wanted it.\n\n| Scope | Flag | Written to | Who sees it |\n|---|---|---|---|\n| local (default) | — | your user config, keyed to the current project | just you, just this project |\n| project | `--scope project` |\n`.mcp.json` at the repo root |\neveryone who clones the repo |\n| user | `--scope user` |\nyour user config, global | just you, every project |\n\nTwo practical rules fall out of this:\n\n`.mcp.json`\n\n`claude mcp reset-project-choices`\n\nre-asks.`claude mcp add --scope user notion ...`\n\nonce, and it's everywhere.`.mcp.json`\n\nis plain JSON and fine to edit by hand:\n\n```\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\nThat `${GITHUB_TOKEN}`\n\nis not decoration — Claude Code expands environment variable references in `.mcp.json`\n\n(`${VAR}`\n\n, with `${VAR:-fallback}`\n\nfor defaults) at server start. This is how you commit a shared config without committing anyone's token: the file references the variable, each machine supplies its own value.\n\nServers that live behind a URL instead of a local process use a transport flag:\n\n```\nclaude mcp add --transport http sentry https://mcp.sentry.dev/mcp\n```\n\nFor services that need auth, run `/mcp`\n\nin a session and pick the server — Claude Code walks the OAuth flow in your browser and stores the token. No key ends up in a config file, which is exactly where keys shouldn't be.\n\nRemote HTTP servers have one operational property worth internalizing: they fail with the network. If a provider's MCP endpoint is down, your session just loses those tools until it recovers. Design your rules so that nothing critical assumes an MCP tool is always present.\n\n**1. The command isn't on PATH where Claude Code runs.** Your shell has nvm-managed node; the environment Claude Code launched from may not. If `/mcp`\n\nshows the server as failed and the log says `command not found`\n\n, use an absolute path to the binary (`command: \"/Users/you/.nvm/versions/node/v22.17.0/bin/npx\"`\n\n) or a wrapper script that sources your environment first.\n\n**2. The env block is missing.** A stdio server is a child process — it inherits nothing you didn't give it. If the server needs `GITHUB_TOKEN`\n\nand the `env`\n\nblock doesn't pass it, the server usually starts fine and then every tool call fails with an auth error. The confusing symptom: connected server, broken tools.\n\n**3. The server is slow to start and gets killed.** Claude Code enforces a startup timeout (configurable with the `MCP_TIMEOUT`\n\nenvironment variable). First-run `npx`\n\ndownloads are the classic trigger: the download takes longer than the timeout, the server \"fails\", and the second attempt mysteriously works because the package is now cached. Warm the cache (`npx -y <pkg> --help`\n\nonce) or raise the timeout.\n\n**4. It's a scope problem, not a server problem.** The server works in the project where you added it and is \"missing\" everywhere else — because default scope is local. `claude mcp list`\n\nshows what's configured in the current context; if the server isn't in the list, it's not broken, it's just somewhere else.\n\nRun `claude --debug`\n\nwhen none of the above fits — it logs each server's startup and the actual error instead of a silent absence.\n\nEvery MCP tool gets a name of the form `mcp__<server>__<tool>`\n\n, and your permission rules treat it like any other tool. Two useful patterns:\n\n```\n{\n  \"permissions\": {\n    \"allow\": [\"mcp__github__search_repositories\"],\n    \"deny\": [\"mcp__github__delete_repository\"]\n  }\n}\n```\n\n`mcp__github`\n\n(no tool suffix) matches every tool the server exposes. One thing to know: MCP tool rules don't take argument patterns — you can allow or deny a tool, but not \"this tool with these arguments\". Scope your write-capable tokens accordingly: the permission system controls which tools run, the token controls what they can touch.\n\nEvery connected server injects its tool definitions into context — that's capability you pay for in tokens on every request, whether or not the session uses it. Before adding a server, it's worth asking what the integration is actually for:\n\n`gh`\n\n, `aws`\n\n, `kubectl`\n\n, `psql`\n\nthrough Bash directly. A line in your rules file (\"use `gh`\n\nfor GitHub operations\") costs a few tokens once. An MCP server that duplicates a CLI costs schema tokens forever and adds a process to babysit.`curl`\n\npattern in a rules file is transparent, debuggable, and versioned with your repo.The heuristic that has held up: **if you can express it as a command, write it as a rule; if it needs a connection, make it a server.** Teams that follow it end up with one to three servers doing work nothing else can do, instead of eight servers reimplementing their shell.\n\n*Rulestack builds config packs for Claude Code, Cursor, and Codex — rules files, hooks, and permission setups tested against current tool behavior: https://rulestack.gumroad.com?ref=devto?ref=devto*\n\n*Short, practical notes on AI coding agents, most days, on Bluesky: @ai-shop.bsky.social*", "url": "https://wpnews.pro/news/mcp-servers-in-claude-code-the-minimal-setup-and-when-you-should-skip-mcp", "canonical_source": "https://dev.to/rulestack/mcp-servers-in-claude-code-the-minimal-setup-and-when-you-should-skip-mcp-entirely-1499", "published_at": "2026-07-18 22:23:24+00:00", "updated_at": "2026-07-18 22:57:31.583964+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["Claude Code", "MCP", "GitHub", "Sentry", "npx"], "alternates": {"html": "https://wpnews.pro/news/mcp-servers-in-claude-code-the-minimal-setup-and-when-you-should-skip-mcp", "markdown": "https://wpnews.pro/news/mcp-servers-in-claude-code-the-minimal-setup-and-when-you-should-skip-mcp.md", "text": "https://wpnews.pro/news/mcp-servers-in-claude-code-the-minimal-setup-and-when-you-should-skip-mcp.txt", "jsonld": "https://wpnews.pro/news/mcp-servers-in-claude-code-the-minimal-setup-and-when-you-should-skip-mcp.jsonld"}}