On this page#
Before you install anything#
Define the access boundary, task, and rollback path before choosing a server. Setup order matters because an MCP server is not merely an agent feature: it is a process with tools, credentials, and permissions. Installing first and deciding scope later turns an integration mistake into a repository risk.
The Model Context Protocol is a standard for connecting an AI application to external capabilities through a consistent interface. Its value is interoperability; it does not decide which capabilities your agent should receive.
Write down four things first:
- Task: the concrete operation the server must enable.
- Boundary: the smallest directory, account, or service it may access.
- Authority: whether its tools can read, write, execute, or delete.
- Rollback: the single configuration change that disconnects it.
For this tutorial, the initial server exposes one repository directory through the official reference filesystem implementation. It receives no credentials and no parent-directory access. That narrow setup is intentionally boring: boring infrastructure survives real repositories.
MCP uses a host, a client, and one or more servers. The host is your coding agent application; its MCP client maintains a connection to the server; the server publishes tools or other capabilities. The official architecture explanation is worth reading because this separation determines where failures and permissions live.
Do not confuse protocol support with safe configuration. A server can comply with MCP while still exposing far too much.
Photo by Boris K. on Pexels.
The steps#
Use the following sequence: choose one bounded task, inspect the server, pin its installation, configure an absolute scope, restart the host, verify published tools, test denial behavior, and commit only the team-safe configuration. Each step prevents a specific failure instead of merely moving setup forward.
-
Choose one task and one server. This prevents an installation spree from hiding which integration actually provides value.
-
Inspect the server’s tools and required arguments. This prevents granting write or execution authority when the task only needs reads.
-
Install the server as a pinned repository dependency. This prevents an unreviewed future release from changing behavior on another developer’s machine.
-
Locate the installed executable and use its absolute path. This prevents the agent host’s working directory or shell environment from deciding whether startup succeeds.
-
Pass the repository root as the only allowed directory. This prevents accidental access to sibling repositories, home-directory files, and unrelated credentials.
-
Add the configuration at repository scope. This prevents a working personal setup from becoming undocumented machine state.
-
Restart the host and inspect the tools it reports. This prevents “the process started” from being mistaken for “the intended tools are available.”
-
Test one allowed path and one forbidden path. This prevents a successful happy-path call from concealing a broken access boundary.
-
Remove the server entry and restart once. This proves rollback before the integration becomes part of a larger workflow.
Use the official reference server repository to identify the maintained implementation and its installation command. Do not copy a package name from an old blog post: the repository named in this spec is the authority for the reference implementation.
If your team has not yet standardized agent instructions, permissions, and review boundaries, establish those before adding more servers. The Agent Operating Kit is the relevant PairFoundry path; the broader pack overview shows where that operating layer fits.
A working configuration#
Use a repository-scoped configuration that launches the pinned local executable and exposes only the repository root. The two absolute paths below are deliberate substitution points; everything else should remain stable. Do not replace them with npx, a floating package reference, ~, or a parent directory.
{
"mcpServers": {
"repo-filesystem": {
"command": "/absolute/path/to/repo/node_modules/.bin/mcp-server-filesystem",
"args": [
"/absolute/path/to/repo"
],
"env": {}
}
}
}Replace /absolute/path/to/repo in both places after installing the official filesystem reference server as a pinned dependency through your repository’s package manager. Then place the object in the repository-level MCP configuration location expected by your host. Claude Code, Codex, and Cursor may wrap or locate this object differently; the server definition itself expresses the important boundary.
| Line or key | Why it exists |
|---|---|
| { | Starts the configuration object. |
| "mcpServers" | Declares the named servers available to the host. |
| "repo-filesystem" | Gives this connection a task-oriented identity for logs and removal. |
| "command" | Launches the repository-installed executable without relying on global state. |
| "args" | Supplies startup arguments to that executable. |
| "/absolute/path/to/repo" | Restricts the filesystem server to the intended repository root. |
| "env": {} | Makes the absence of injected credentials explicit. |
| Closing braces | Close the server definition, server map, and configuration object. |
The empty environment object is not decorative. Credentials should appear only when a server genuinely requires them, and secrets should come from an approved secret mechanism rather than committed JSON.
This configuration also avoids a common portability lie: ${workspaceFolder} and similar placeholders are not universally expanded by every host. An explicit path works locally but differs across machines, so commit a documented template if your host cannot resolve project-relative values safely. Keep machine-specific paths out of shared configuration.
The MCP architecture explains why startup transport and tool behavior are separate concerns. A connected process can still publish unexpected tools, receive the wrong root, or fail individual calls. Verify all three layers: process, capability list, and actual boundary enforcement.
Photo by Digital Buggu on Pexels.
What to skip#
Skip any step that adds authority without proving the first task: global installation, automatic latest-version downloads, home-directory access, premature credentials, multiple servers at once, and elaborate prompt examples. These shortcuts make demonstrations smoother while making repository behavior less reproducible and failures harder to isolate.
Specifically, skip:
- Global installs. They create invisible version differences between developers and CI environments.
- Unpinned
npxexecution. Convenience is not a supply-chain policy. - Exposing
~or an entire workspace parent. The server needs the repository, not every repository and personal file beside it. - Adding tokens “for later.” Unused credentials expand the blast radius without enabling the current task.
- Installing several servers before validation. Parallel startup failures and overlapping tool names destroy diagnostic clarity.
- Testing only a successful read. A boundary is unverified until an out-of-scope request fails.
- Committing personal absolute paths. Shared configuration must not pretend machines have identical layouts.
- Treating reference servers as production architecture. They demonstrate protocol behavior; your security and operational requirements still apply.
Also skip generic “ask the agent something” validation. The official MCP specification defines the protocol contract, but your acceptance test must define the repository contract.
For more setup patterns, use PairFoundry’s agent setup hub. If the permission model or agent workflow still feels unclear, the free foundations track is a better next step than adding another integration.
First real task#
Make the first task a boundary audit, not feature work. Ask the agent to inventory the repository through the MCP server, identify its top-level structure, read one known file, and attempt one explicitly forbidden path outside the root. This confirms usefulness, observability, and denial behavior in a single reviewable sequence.
Use a prompt like this:
Use only the repo-filesystem MCP tools.
1. List the repository root.
2. Read the repository’s primary agent-instruction or contributor file.
3. Summarize the directories relevant to making a code change.
4. Attempt to list the parent directory of the configured repository root.
5. Report every tool called, its target path, and whether it succeeded.
Do not modify any file.Accept the setup only if the repository operations succeed, the parent-directory request fails, and the reported tools match the server you configured. If the forbidden request succeeds, stop immediately: narrowing the prompt is not a fix. Narrow the server argument or remove the integration.
This task is better than asking for a code change because it separates connectivity from mutation. Once the boundary is proven, the next task can be real repository work with the same review, test, and rollback rules you already apply to agent-generated changes.
Photo by ThisIsEngineering on Pexels.
Related reading#
- Npm install google Gemini CLI: a working configuration, explained line by line
- How to use Claude Code effectively — what to do before you type a single prompt
FAQ#
These are the questions that matter after the happy-path demo: where MCP belongs, how this setup differs from a quickstart, what teams must share, how to recover from failure, and when another integration is the better choice. The answers follow directly from the process and permission boundaries above.
When should I add an MCP server instead of using the agent’s built-in tools?#
Add one when a bounded external capability is required and the built-in tool cannot provide it under an acceptable permission model. Do not add a filesystem server merely because MCP exists; many coding agents already handle repository files. The integration must remove a real constraint, not duplicate a working capability.
How is this different from the official quickstart approach?#
The protocol is unchanged; the acceptance standard is stricter. This setup adds repository-scoped installation, pinned dependencies, explicit access boundaries, denial testing, and rehearsed rollback around the official mechanism. The reference servers show implementations, but they cannot define your repository’s operational or security policy.
What should a team commit to the repository?#
Commit the server identity, pinned dependency, required scope, setup instructions, acceptance test, and rollback procedure. Do not commit secrets or personal absolute paths. If the host requires machine-specific paths, commit a template and a deterministic setup instruction so every developer produces the same effective configuration.
How do I recover when the server stops starting?#
Remove or disable its configuration entry, restart the host, and confirm the agent works without it. Then check the executable path, installed dependency, startup arguments, and published tools in that order. Reinstalling everything first is the wrong move because it destroys evidence about which layer failed.
When should I not use MCP at all?#
Do not use it when the host already provides the capability safely, the server requires broader authority than the task justifies, or the team cannot pin and review its implementation. A direct API, existing command-line tool, or built-in connector is often simpler. MCP standardizes integration; it does not make unnecessary integration wise.