On this page#
Before you install anything#
To build an MCP server in fifteen minutes, do not start by writing server code. Pick one bounded repository task, use an official reference server over local stdio, expose only the directory that task needs, connect one agent, and verify a read-only operation before enabling writes. That order prevents a convenient integration from becoming an accidental trust boundary.
The Model Context Protocol is a standard for connecting AI applications to external tools and context. An MCP server exposes capabilities; an MCP client—Claude Code, Codex, Cursor, or another agent—discovers and invokes them.
That distinction matters. The server does not make your agent reliable, understand your architecture, or respect unwritten repository rules. It only creates a structured path between the agent and a capability.
Before touching configuration, write down four constraints:
- Task: What exact job should become easier?
- Root: Which directory may the server see?
- Operations: Does the task require reads, writes, or external side effects?
- Proof: What observable result will show that the connection works?
For a first setup, the right task is narrow: let the agent inspect one repository through an official filesystem server. Exposing your entire home directory is wrong. Adding databases, issue trackers, deployment tools, and production credentials at the same time is also wrong.
MCP’s client–server architecture separates the host application, client connection, and server capabilities. Use that separation deliberately: one server should have one understandable responsibility and one reviewable permission surface.
Photo by Boris K. on Pexels.
The steps#
The fastest dependable path is a six-step local setup with a deliberately small scope. Each step removes one class of failure before the next one appears: unclear purpose, excessive access, unknown implementation, broken launch configuration, hidden permission errors, and unreviewed side effects.
-
Choose one real repository task.
This prevents “install MCP” from becoming an infrastructure project with no acceptance test. -
Select the smallest repository root that contains the required files.
This prevents unrelated code, credentials, caches, and personal files from entering the server’s visible scope. -
Use an official reference implementation before writing a custom server.
This prevents protocol plumbing from obscuring whether MCP is useful for the task. The official reference servers include implementations intended to demonstrate established patterns. -
Configure the server as a local process using standard input and output.
This prevents hosting, authentication, networking, and deployment from consuming the first fifteen minutes. -
Restart the agent and confirm that the server and its tools are visible.
This prevents you from debugging prompts when the real failure is process startup, configuration location, or an invalid path. -
Run one read-only request before any mutation.
Ask the agent to list a known directory or open a known file. This prevents a successful connection from being confused with safe write behavior.
The order is the method. If the read-only request fails, stop there. Do not add another server, broaden the path, or grant writes as a debugging tactic.
Your client may store MCP configuration in a different file or settings screen, but the runtime relationship remains the same: the client launches a server process, exchanges protocol messages, and presents the server’s capabilities to the agent. The architecture documentation is the useful reference when the UI makes that relationship look more mysterious than it is.
A working configuration#
Use this configuration to connect one local filesystem server to one repository. Replace the placeholder with an absolute path, put the object in your client’s MCP configuration, and restart the client. The configuration launches the official reference server through npx; it does not expose every directory on your machine.
{
"mcpServers": {
"repository": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/absolute/path/to/repository"
]
}
}
}Here is what every line is doing:
| Line | Meaning |
|---|---|
| { | Starts the configuration object. |
| "mcpServers": { | Declares the client’s named MCP server connections. |
| "repository": { | Gives this connection a stable, human-readable name. |
| "command": "npx", | Tells the client which executable starts the server process. |
| "args": [ | Begins the arguments passed to that executable. |
| "-y", | Allows npx to proceed without an interactive installation prompt. |
| "@modelcontextprotocol/server-filesystem", | Selects the official filesystem reference server package. |
| "/absolute/path/to/repository" | Restricts the server to the repository root you chose. |
| ] | Ends the argument list. |
| } | Ends the named server definition. |
| } | Ends the MCP server map. |
| } | Ends the configuration object. |
Do not use a relative repository path. The client may launch the process from a directory you did not expect, producing either a startup failure or access to the wrong location.
Also do not replace the repository path with a broad parent directory merely because it is convenient. The reference-server repository gives you an implementation; it cannot decide which of your files are appropriate for an agent to access.
If the server does not appear after restart, check only three things first:
- The configuration is in the client’s active MCP settings.
npxis available in the environment from which the client launches processes.- The absolute repository path exists and is accessible to that process.
That is enough for the initial diagnosis. Reinstalling your editor or rewriting the configuration in another language is noise.
Photo by Jakub Zerdzicki on Pexels.
What to skip#
Skip anything that does not help prove one bounded capability against one real repository. Most MCP tutorials overbuild the demonstration: they create a custom server, add several tools, introduce remote hosting, and celebrate tool discovery. That proves protocol wiring, not that the setup is safe or useful in production engineering work.
Skip these common detours:
- Writing a custom server first. Use a reference implementation until an existing server cannot express the capability you need.
- Exposing your whole home directory. Convenience is not a permission model.
- Adding write access to make the demo impressive. A read-only result is the correct first acceptance test.
- Connecting multiple agents at once. Client-specific failures become harder to isolate.
- Starting with remote hosting. Networking adds authentication, transport, availability, and secret-management decisions before value is established.
- Inventing elaborate prompts. A server connection either exposes the expected capability or it does not.
- Building a generic “company MCP server.” Start with one domain boundary, such as repository inspection or an internal service with a small, explicit operation set.
- Treating tool availability as authorization. The protocol carries capabilities; your process boundaries and credentials determine what those capabilities can actually do.
If your real problem is agent operating discipline rather than connectivity, MCP will not solve it. The Agent Operating Kit is the more relevant next step for repository instructions, repeatable workflows, and review boundaries. You can also compare the available options on the PairFoundry packs overview.
First real task#
Your first task should inspect the repository and produce a verifiable artifact without changing files. Ask the agent to identify the repository’s documented commands, locate its governing instruction files, and report conflicts or missing prerequisites with file references. This exercises discovery, bounded reading, and evidence quality without risking a mutation.
Use a prompt like this:
Inspect this repository through the repository MCP server. Find the files that define build, test, lint, and agent instructions. Report each command with its source file, flag contradictions, and do not modify anything.
A good result contains file-backed claims. A bad result gives generic advice, guesses commands, or silently reads outside the intended root.
Only after that result is correct should you allow a small change. Choose a task with a narrow diff and an existing validation command—for example, fixing one documented inconsistency and running the repository’s own check. The MCP architecture explains the connection model, but your repository’s invariants still define success.
If the agent cannot reliably complete the read-only task, adding more capabilities will make the failure larger. Tighten the scope, inspect the evidence, and fix the boundary first.
For a broader operating model, continue through the free PairFoundry foundations track or browse the agent setup guides.
Photo by Daniil Komov on Pexels.
Related reading#
- How to run Claude Code in terminal in fifteen minutes, and what to skip
- How to start Claude Code in terminal: the order matters more than the settings
FAQ#
What is a MCP server and how to build it?#
An MCP server is a process that exposes tools, resources, or prompts to an AI application through the Model Context Protocol. To build MCP server functionality quickly, define one capability, choose its permission boundary, start from an official reference implementation, connect one client, and verify a read-only request before writing custom code.
How much does it cost to build a MCP server?#
A local MCP server can use open reference code without a separate hosting bill. The meaningful cost is engineering time: defining safe operations, handling credentials, validating inputs, logging side effects, and maintaining compatibility. Remote deployment also introduces infrastructure and operational costs that a local stdio server avoids.
How can I host an MCP server?#
Start locally as a client-launched process. Host it remotely only when multiple users or environments genuinely need shared access. Remote hosting requires an explicit transport, authentication, authorization, secret management, logging, and availability plan; moving the same permissive local server onto a network is not a production design.
Who builds MCP servers?#
Engineers who own the underlying system should define the server’s capabilities and invariants, while platform or security engineers review shared deployment and authorization. Protocol familiarity is not enough: the builder must understand which operations are safe, which inputs are valid, and which side effects require human approval.
Can I set up my own MCP server?#
Yes. The quickest way to build MCP server access is to configure an official reference server for one bounded resource, as shown above. Write your own server only when you need domain-specific operations that existing implementations cannot provide, and expose those operations as narrow actions rather than unrestricted access to the underlying system.