Claude Code MCP Server Configuration: Add Servers, Pick a Stack, Stay Small

Claude Code users can configure MCP servers to give the AI access to external tools like GitHub, Context7, and Playwright, using commands such as 'claude mcp add' with scopes and verification via 'claude mcp list'. The guide emphasizes starting with a small stack to manage context costs and warns against committing secrets into .mcp.json.

Claude can draft the perfect PR description and still can’t open your repo, check the live docs, or click through the UI you just shipped. The model isn’t lazy. You never gave it a door into the systems where the work actually lives. MCP Model Context Protocol is how Claude Code calls external tools repos, docs, browsers, databases through configured servers. For Claude Code MCP server configuration , use claude mcp add or claude mcp add-json syntax can depend on your CLI version , choose --scope user or --scope project project configs often live in .mcp.json , then verify with claude mcp list or /mcp. Start with a small stack such as GitHub + Context7 + Playwright. More servers mean more context cost. Always cross-check commands against Claude Code MCP docs https://code.claude.com/docs/en/mcp and the MCP connector https://platform.claude.com/docs/en/agents-and-tools/mcp-connector notes plus claude mcp --help on your machine. Picture a workshop where the craftsperson is brilliant and trapped. They can sketch every cut on paper. The saws, routers, and measuring tools sit behind locked cabinet doors. Every time they need a real measurement, someone has to walk the tool in by hand, describe what it saw, and walk it out again. Work slows. Mistakes multiply. The craftsperson starts inventing dimensions that “should” be right. That locked-cabinet problem is what MCP Model Context Protocol is for. MCP is a shared way for an AI host to talk to external tool servers so the model can act in real systems instead of only predicting text. In Claude Code, those servers are how you add MCP access to GitHub, documentation look-ups, browser automation, databases, and more. People searching claude code mcp server , claude code mcp configuration , or claude code add mcp are usually stuck in the same place: the model can write code, but it cannot touch the systems that prove the code. Keep three roles straight. The host is the app that owns the session, which here is Claude Code itself. The client is the bridge inside that host which speaks MCP. The server is the separate process or endpoint that actually exposes tools, such as GitHub MCP, Context7, or Playwright. Local servers often run over stdio standard input/output: the host starts a process and talks to it on pipes . Remote servers often use HTTP sometimes with streaming/SSE-style transports, depending on the server . You do not need to memorize transport names to ship. You do need to know whether your server is “a command I run locally” or “a URL I authenticate to.” Searchers typing claude mcp desktop or how to use mcp with claude desktop are often mixing products. Claude Code is the terminal agent that lives next to your git tree, configured with claude mcp add, scopes, and project files. Claude Desktop is the chat app, configured through its own app settings. When a blog says “open Settings → MCP,” check which product the screenshots show. This guide is for Claude Code . You need a working Claude Code CLI in a real project directory. If install is still fuzzy, finish that first planned: Install Claude Code . MCP configuration assumes you can already open a session. Many MCP servers launch via npx, uvx, Docker, or a binary on your PATH. Community write-ups often assume Node.js 18+ and a healthy shell path. Treat those as environment hypotheses : confirm what your chosen server README requires before you debug Claude. If a server “installs” but never starts, the first suspect is usually not Claude. It is a missing runtime, a bad command path, or a token that never got into the environment. GitHub, Supabase, PostHog, and friends need secrets: personal access tokens, OAuth, API keys. Put secrets in environment variables or the mechanism your CLI documents. Do not commit tokens into .mcp.json and push them. Rule of thumb: if the secret would make you nervous in a Slack screenshot, it does not belong in a shared config file in plaintext. This is the core of claude code add mcp server / add mcp to claude code searches. Start with the CLI so the config lands where Claude Code expects it: claude mcp --helpclaude mcp list Exact subcommands and flags move. If your help output disagrees with a blog from last month, trust your binary. Two patterns show up constantly in 2025–2026 guides: Illustrative shapes verify against your CLI and the server’s current README : Pattern A: add shape varies by transport and version claude mcp add --transport http <name <url Pattern B: add-json JSON string / file: confirm flags locally claude mcp add-json <name '<json-config ' Community notes also mention Windows shells choking on nested quotes with add-json. If you see “Invalid input,” try the alternate add form your docs show for that transport, or pass JSON in a way your shell does not mangle. Do not fight bash quoting for twenty minutes when the README already documents a Windows path. Adding is not success. Verification is success. claude mcp list Inside a session, many builds expose /mcp or similar so you can see connected servers and available tools. Connected with an empty tool list is a failure mode, not a win. See Troubleshooting. Two references outrank every tutorial, including this one. The Claude Code MCP docs https://code.claude.com/docs/en/mcp describe how the CLI expects to be configured. The MCP connector docs https://platform.claude.com/docs/en/agents-and-tools/mcp-connector describe how the protocol behaves over a remote transport. Read those for intent, then let claude mcp --help settle any argument about flags on your machine. Version drift is the whole game here. A command that worked in a write-up from a few months ago can be renamed or replaced, and the docs get corrected long before the blog posts do. Scope is the part most listicles skip, and it is where teams get burned. There are three scopes, and the one people forget is the default. Sources in the research pack describe local as the default scope: the server is available only to you, only inside that one directory. user scope stores configs in ~/.claude.json so a server follows you across every project on the machine, which suits experiments and personal tokens. project scope writes .mcp.json into the repo so the definition travels through Git, which is where something like GitHub or Context7 belongs so every teammate gets the same tools without a setup call. That default explains a common confusion. If you add a server without thinking about scope, then open a different directory and find your tools missing, nothing broke. You installed it for one folder and then walked away from that folder. Project-level MCP config is widely described as living in .mcp.json leading dot . Guides that say mcp.json without the dot cause silent “why isn’t this loading?” bugs. Confirm the filename your current docs require. Also: do not assume every JSON file under .claude/ is the MCP server registry. Preference files and MCP definitions are easy to confuse in older blog posts. When unsure, let claude mcp add … --scope project write the file, then open what it created. Team tip: put non-secret server definitions in project scope. Keep secrets in each developer’s environment. Shared plaintext tokens are how you get a very exciting Monday. Project scope has a security step that looks like a bug the first time you meet it. When someone clones a repo containing .mcp.json and runs Claude Code in that directory for the first time, the CLI asks whether to approve adding MCP configs from this project. Until that approval happens, the servers defined in the file are not loaded, which reads exactly like a broken config. So when a teammate reports that the shared MCP setup does not work on their machine, ask what they saw on first run in that directory before you start auditing JSON. Approving someone else’s .mcp.json is also a real decision rather than a formality, because a project config can point Claude at whatever command the file’s author chose. People searching claude code best mcps or best mcp servers for claude code want a shortlist, not a museum. Here is a practical starter stack many engineering write-ups converge on: GitHub for pull requests and issues, Context7 for current library documentation, and Playwright when browser automation is part of the loop. Everything else is optional and earns its slot per project. Rankings are editorial usefulness for day-to-day coding , not a Semrush contest. Honest skip: a generic Filesystem MCP is often redundant in Claude Code because the agent already ships file tools Read, Edit, Write, Glob, Grep, and friends . Add a filesystem server only when you need to expose extra directories through MCP or reuse one server across multiple MCP clients. Verify against your workflow before you pay the context tax. Skip thin “Top 50 MCP” posts that never distinguish Desktop from Code. Prefer official server READMEs and the Claude Code MCP docs over affiliate roundups. Install the tool that matches the week’s work. Curiosity installs are how you end up with fifteen servers and a confused agent. Context7 is a clean first win for many people searching context7 claude code : Claude stops inventing APIs that changed six months ago and instead fetches documentation through the MCP server. Pattern exact package/URL/command: follow Context7’s current Claude Code install docs, then verify : If tools never appear, you do not have a Context7 problem yet. You have a configuration or auth problem. Fix that first. Here is the complication nobody puts on the affiliate thumbnail. Every MCP server publishes tool schemas into the session. Those schemas consume context. A bloated tool list makes Claude slower to choose, easier to distract, and in some builds more likely to lose tools during compaction. Community guidance often lands around a soft ceiling of roughly five to six active servers before quality drops. Treat that number as a hypothesis from sources, not a law of physics. Your model, compaction settings, and server verbosity matter. The expensive part is not the missing connector. It is the twenty connectors that make Claude hesitate. Practical discipline: Most MCP failures come from a short list: authentication that never finished, a server process that crashed on start, a config file with the wrong name or in the wrong scope, or a tool list that got squeezed out by context pressure. Work down that list before you suspect the model. Fill-FAQ angle: connected ≠ usable . Status text that says connected is marketing until the tool list is non-empty and a real call succeeds. For OAuth servers, the fix is usually narrower than a reinstall. Inside a session, the research pack describes /mcp auth <server-name as the way to re-trigger the login flow for one server, which is the right first move when a token expires and a previously working server starts answering 401. If the CLI seems stuck in a bad auth state across several servers, the same sources describe clearing the cached credentials directory at ~/.mcp-auth and restarting the CLI, after which each server logs in from scratch. Reach for the second one only after the first fails, because it signs you out of everything at once. Either way, confirm the recovery worked by making a real tool call, not by rereading the status line. Some jobs are cheaper without a server in the middle. If a native CLI already does the thing in one line, or Claude Code already has a built-in tool for it, wiring an MCP server buys you schema overhead and nothing else. MCP is leverage when the agent must repeatedly touch a system with structure. It is overhead when you are wrapping a one-liner CLI in a schema tax. FAQ count: 9. Items marked data are Semrush-backed ranked targets from Overview on the MCP primary. The last item is a same-job filler for completeness. Install Claude Code, then add a server with claude mcp add or claude mcp add-json using the server’s current README. Pick --scope user or --scope project, then verify with claude mcp list or /mcp until tools appear. Cross-check flags with claude mcp --help because syntax drifts by version. Same loop: choose the server, run the documented add command, set scope, verify tools. If you only edit JSON by hand, you are more likely to miss the filename or schema Claude Code expects. Prefer the CLI write path, then inspect the file it created. Add them one at a time and verify after each. A stack of five unverified servers is harder to debug than five short verify loops. Start with GitHub and Context7 before you chase niche servers. Follow Supabase’s current MCP + Claude Code instructions for the transport they support, inject credentials via environment variables not committed plaintext , add with the CLI, and verify tools with list / /mcp. Only keep it enabled when the project actually talks to Supabase that week. Build a small MCP server that exposes the tools you need local stdio is the usual starting point , run it with a command Claude can launch, then register that command via claude mcp add / add-json. Official MCP docs and Anthropic’s connector material are the source of truth for protocol details; start tiny one tool before you invent a platform. Use Desktop’s own MCP / connectors settings. Do not assume Claude Code’s .mcp.json and Desktop’s config are interchangeable. If your goal is repo-native engineering work, prefer Claude Code and keep Desktop for chat-side connectors. “Claude” alone is ambiguous. For the coding CLI, use Claude Code’s claude mcp commands. For the desktop app, use Desktop settings. For API / platform connectors, follow the MCP connector docs. Name the product before you paste a config blob. MCP as a protocol is open. Your costs are Claude usage, any hosted MCP endpoint pricing, and the systems behind the tools GitHub API limits, database access, browser infra . Local stdio servers can be “free” to run and still expensive in tokens if they dump huge schemas or results into context. Usually auth never finished, the server process crashed on start, the config points at the wrong command, or you are looking at the wrong scope/profile. Re-run auth, check server logs, confirm .mcp.json vs user scope, and require a successful tool call before you trust the status label. Try this once, this week: wire one server. Not five. Add GitHub or Context7, run claude mcp list until the tools actually appear, then force one real task through that door. If the tool never fires, you learned more about your setup than any “ultimate MCP list” will teach you. The agents that feel magical next year will not be the ones with the longest server menus. They will be the ones whose humans treated connectors like production dependencies: versioned, scoped, and small enough to trust. Until then, keep the cabinet unlocked and keep the shelf short. Sage PS. The first MCP I ever added successfully was a green status light with zero tools. I screenshotted the victory, then spent forty minutes discovering the token had the wrong scopes. Status is not a feature. A tool call that returns something true is. Claude Code MCP Server Configuration: Add Servers, Pick a Stack, Stay Small https://pub.towardsai.net/claude-code-mcp-server-configuration-add-servers-pick-a-stack-stay-small-41300081dbc7 was originally published in Towards AI https://pub.towardsai.net on Medium, where people are continuing the conversation by highlighting and responding to this story.