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

Add MCP servers to Claude Code with claude mcp add, choose scope, keep the stack small, and fix connected-but-no-tools failures. 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 (and the MCP connector notes) plus claude mcp --help on your machine. Plug tools into Claude Code. Don’t fake the terminal. Table of contents What is MCP in Claude Code? Prerequisites How to add an MCP server Scope: user vs project (.mcp.json) Best MCP servers for Claude Code Context7 worked example Context cost and how many MCPs to run Troubleshooting When not to use MCP FAQ What is MCP in Claude Code? 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. Host, client, and server 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. Claude Code hosts the client. Each MCP server is a tool process or endpoint. 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.” Claude Code vs Claude Desktop MCP 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. Same protocol, two different configuration surfaces. When a blog says “open Settings → MCP,” check which product the screenshots show. This guide is for Claude Code . Prerequisites Claude Code installed and authenticated 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. Runtime and path reality 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. Auth without drama 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. How to add an MCP server This is the core of claude code add mcp server / add mcp to claude code searches. Prefer the CLI over hand-edited mystery JSON Start with the CLI so the config lands where Claude Code expects it: claude mcp --help claude mcp list Exact subcommands and flags move. If your help output disagrees with a blog from last month, trust your binary. claude mcp add vs claude mcp add-json Two patterns show up constantly in 2025–2026 guides: claude mcp add … : common for straightforward local or remote servers with a known transport. claude mcp add-json … : common when you need to pass a fuller JSON definition (and some version notes say newer Claude Code builds lean on this for certain installs). 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 # Pattern B: add-json (JSON string / file: confirm flags locally) claude mcp add-json ' ' 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. https://medium.com/media/803cb26bc94de3327d5c214e2a102d01/href Verify: claude mcp list and /mcp 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. Docs first, then your own binary Two references outrank every tutorial, including this one. The Claude Code MCP docs describe how the CLI expects to be configured. The MCP connector docs 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: user vs project (.mcp.json) Scope is the part most listicles skip, and it is where teams get burned. User scope is personal. Project scope ships with the repo (usually via .mcp.json). 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. The project approval prompt 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. Best MCP servers for Claude Code 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. Three servers cover most coding work. Optional ones need a reason. https://medium.com/media/a782971e4703dbd3a98760604c8514ac/href 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. Domain examples (not a shopping list) Supabase MCP : useful when the agent must inspect or mutate your Supabase project with real credentials and clear guardrails. PostHog MCP : useful when product analytics questions are part of the coding loop. Blender MCP : useful for 3D / creative pipelines; irrelevant for most SaaS CRUD apps. Install the tool that matches the week’s work. Curiosity installs are how you end up with fifteen servers and a confused agent. Context7 worked example 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): Add the server with claude mcp add or add-json as their README shows. Choose scope: user for personal trials, project if the whole team should share it. Restart or refresh the session if your build requires it. claude mcp list / /mcp until tools appear. Ask a version-sensitive question (“what’s the current API for X in library Y?”) and watch whether the tool is actually invoked. If tools never appear, you do not have a Context7 problem yet. You have a configuration or auth problem. Fix that first. Context cost and how many MCPs to run 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. Every server expands the tool list. Budget the context. The expensive part is not the missing connector. It is the twenty connectors that make Claude hesitate. Practical discipline: Start with GitHub + Context7 (+ Playwright if UI is the job). Add one domain server when a sprint needs it. Remove servers you have not used in a week. Prefer a native CLI (gh, psql) when the MCP wrapper costs more than it saves. Troubleshooting 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. Match the symptom, then check auth and scope before anything else. Fill-FAQ angle: connected ≠ usable . Status text that says connected is marketing until the tool list is non-empty and a real call succeeds. When it is really just auth For OAuth servers, the fix is usually narrower than a reinstall. Inside a session, the research pack describes /mcp auth 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. When not to use MCP 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. A schema tax you pay every session is worse than typing the command yourself. 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 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. How to add MCP to Claude Code? 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. How to add MCP server to Claude Code? 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. How to add MCP servers to Claude Code? 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. How to add Supabase MCP to Claude Code? 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. How to create a Claude MCP server? 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. How to use MCP with Claude Desktop? 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. How to add MCP to Claude? “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. Is Claude MCP free? 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. Why is MCP “connected” but tools don’t show? 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. Related guides Claude Code Plan Mode Install Claude Code Claude Code slash commands & settings Claude Code sessions & memory 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 was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.