On this page#
Before you install anything#
A reliable claude code mcp config starts with boundaries, not installation commands: choose one task, identify the minimum capability it requires, decide which repository paths the server may access, and define how the configuration will be removed. Installing servers first creates an unreviewed tool surface that is difficult to audit later.
MCP is a protocol through which an AI application can discover and call tools exposed by a server. Claude Code is the client; an MCP server is a separate process or remote service. Adding one does not merely improve context—it gives the agent another operational interface.
Use this order:
- Name the blocked task.
- Decide whether Claude Code’s built-in tools already solve it.
- Select the smallest MCP server that closes the gap.
- Restrict its filesystem, credentials, and network reach.
- Add the configuration at the correct scope.
- verify the advertised tools before using them.
- Run one bounded repository task.
- Remove the server if it does not earn its maintenance cost.
That order matters because configuration scope and server capability are independent. A project-level file can be shared safely while still launching an unsafe server; a private user-level entry can still expose excessive credentials. The official Claude Code documentation explains the supported configuration mechanisms, but your repository must define the operational boundary.
Do not start by collecting servers. A long MCP list increases tool ambiguity, startup failure points, dependency drift, and the number of interfaces a team must review. One justified server is better than a catalog of speculative integrations.
Photo by Boris K. on Pexels.
The steps#
The safe setup is short: establish a clean baseline, add one narrowly scoped server, inspect what Claude Code discovers, and test it on a reversible task. Each step below prevents a specific failure mode rather than adding ceremony for its own sake.
-
Confirm the task without MCP. This prevents attributing an existing Claude Code, repository, or shell problem to the new server.
-
Choose project or user scope deliberately. This prevents personal credentials and machine-specific paths from leaking into a shared repository.
-
Read the server’s command, arguments, and environment requirements. This prevents executing an opaque launcher copied from a tutorial.
-
Limit the accessible directory to the repository. This prevents a repository tool from receiving unnecessary access to unrelated files.
-
Keep secrets out of committed JSON. This prevents tokens from entering Git history, logs, review systems, or copied examples.
-
Add only one server. This prevents overlapping tools from making the first failure impossible to isolate.
-
Restart or reload Claude Code, then inspect the discovered server and tools. This prevents debugging task behavior when the server never connected.
-
Run a read-only task before permitting writes. This prevents a configuration mistake from becoming a repository change.
-
Review the resulting tool calls and output. This prevents “the answer looked right” from replacing verification of which system actually produced it.
-
Document the server’s purpose and removal path. This prevents an abandoned dependency from becoming permanent team infrastructure.
The MCP architecture documentation separates the host, client, and server roles. That separation is operationally important: Claude Code can control how a tool is presented and approved, but the server implementation determines what happens after the call crosses that boundary.
A working configuration#
Put the following .mcp.json in the repository root when the whole team should use the same filesystem server. It exposes only the current project directory, contains no secret, and declares a single stdio server. It assumes Node’s package runner is already available on the machine.
{
"mcpServers": {
"repository-files": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${CLAUDE_PROJECT_DIR}"
]
}
}
}This is valid JSON, so it intentionally contains no inline comments. JSON-with-comments examples are a common source of needless parse failures. Here is the same configuration explained field by field:
| Line or field | What it does | Boundary it establishes |
|---|---|---|
| { | Starts the configuration object. | Nothing exists outside the declared document. |
| "mcpServers" | Contains the MCP server definitions Claude Code should load. | Keeps MCP configuration separate from unrelated settings. |
| "repository-files" | Gives this server a stable local name. | Makes approvals and failures identifiable. |
| "type": "stdio" | Tells Claude Code to communicate with a local child process over standard input and output. | No remote endpoint is implied. |
| "command": "npx" | Selects the executable that launches the server package. | The executable resolves according to the machine environment. |
| "args" | Supplies arguments to that executable. | Launch behavior is visible in the committed file. |
| "-y" | Allows the package runner to proceed without an interactive confirmation. | Automation improves, but dependency execution becomes less explicit. |
| "@modelcontextprotocol/server-filesystem" | Names the filesystem MCP server package. | The configuration requests filesystem tools, not shell or SaaS access. |
| "${CLAUDE_PROJECT_DIR}" | Passes the current Claude Code project directory as the allowed root. | The server is scoped to the repository instead of a home directory. |
| Closing brackets | End the argument list, server definition, server map, and document. | Prevent accidental sibling settings from being treated as arguments. |
The important line is not the package name; it is "${CLAUDE_PROJECT_DIR}". Replacing that value with a home directory or broad parent directory is the wrong tradeoff. Convenience does not justify exposing unrelated source trees, SSH material, cloud configuration, or personal documents.
The npx launcher is convenient for a minimal configuration, but a team rollout should replace floating package execution with an organization-approved, reproducible launcher. Do not invent a version in a copied snippet. Choose and record a reviewed version through your normal dependency process, then have the configuration call that controlled entry point.
Do not add an env object unless the server genuinely requires environment variables. If it needs a token, reference an externally supplied variable; never paste the token into .mcp.json. The Claude Code overview is the authoritative starting point for how Claude Code fits into repository work, while the server remains a separately trusted component.
For a repeatable repository-wide operating model—configuration review, task boundaries, and agent instructions—the PairFoundry Agent Operating Kit is the next step. The broader PairFoundry packs overview shows the available packages without requiring every repository to adopt the same setup.
Photo by Daniil Komov on Pexels.
What to skip#
Skip any step that adds reach without solving the named task. Most MCP tutorials overbuild the setup: they install several servers, expose broad directories, add credentials immediately, and treat a successful connection as proof of safe operation. Those steps produce configuration volume, not engineering confidence.
Do not:
- Install multiple servers “while you are here.”
- Give a filesystem server access to your home directory.
- Commit API keys, personal access tokens, or copied
.envvalues. - Add a remote server before identifying its operator and data path.
- Disable approval controls merely to reduce prompts.
- Assume a familiar package name makes the executed package trustworthy.
- Mix personal integrations with a repository-shared
.mcp.json. - Debug the agent’s final answer before confirming server connection and tool discovery.
- Keep a server because installation was difficult.
- Copy configuration containing comments into strict JSON.
Also skip redundant tools. If Claude Code can already read, search, and edit the repository through its native interface, a filesystem MCP server may add no meaningful capability. The example above is useful for understanding configuration and scoping; it is not a claim that every Claude Code repository needs that server.
That distinction follows directly from the MCP client-server architecture: the protocol standardizes communication, not the necessity, quality, or safety of every tool. For more setup decisions grounded in repository constraints, use the PairFoundry agent setup hub.
First real task#
The first real task should be read-only, repository-specific, and independently checkable: ask the configured server to identify files involved in one known invariant, then compare the result with the repository itself. Do not begin with a migration, dependency upgrade, mass edit, deployment, or credential-backed integration.
A strong first prompt is:
Using only the repository filesystem tools, identify every file involved in enforcing
<named invariant>. Return file paths, the relevant symbol or configuration key, and any apparent enforcement gaps. Do not modify files.
Replace <named invariant> with something concrete: where generated files are excluded, where an API boundary is enforced, or which configuration controls a build mode. You should already know enough about the repository to detect an incomplete or implausible answer.
The task verifies four things at once:
- Claude Code can discover the server.
- The server can access the intended repository.
- It cannot rely on an unrelated write operation.
- Its output can be checked against known code and configuration.
After that passes, allow one small, reversible edit with an explicit diff review. If the server cannot improve a real task after those two bounded checks, remove it. Engineers who want the underlying workflow before adopting a packaged operating model can follow the free PairFoundry foundations track.
Photo by panumas nikhomkhai on Pexels.
Related reading#
- Cursor setup — the setup that survives a real repo
- Vibe coding tutorial: the order matters more than the settings
FAQ#
Should we commit .mcp.json to the repository?#
Commit it when the server is part of the repository’s shared workflow and the file contains portable commands, narrow paths, and no secrets. Keep machine-specific integrations and personal credentials in user-scoped configuration. A shared file is an interface contract, so review changes to it like build or CI configuration.
How is this different from following the official setup instructions?#
The official documentation defines supported Claude Code behavior; this configuration adds an engineering policy around it. The crucial additions are task-first selection, minimum access, one-server isolation, reproducible launching, and a removal criterion. Those are repository governance decisions, not protocol syntax.
What usually breaks when a team shares the configuration?#
Non-portable executable paths, missing runtimes, floating dependencies, undeclared environment variables, and different credential availability cause most avoidable failures. Treat the launcher as a dependency: make prerequisites explicit, keep secrets external, and verify the same tool list appears on each supported development environment.
How do I roll back a broken MCP setup?#
Remove or revert the single server entry, reload Claude Code, and repeat the original task without MCP. If several servers were added together, rollback becomes ambiguous—that is why the one-server rule matters. Repository changes made through the server must be reviewed and reverted separately through normal version control.
When should I avoid MCP entirely?#
Avoid it when Claude Code’s existing tools already complete the task, when the server needs broader access than the task justifies, or when your team cannot review how it handles data and credentials. MCP is an integration boundary, not a default requirement.