Build your first MCP server: the smallest one that does something useful

The concept is simpler than the terminology suggests. You write a small program that advertises a set of functions with described inputs. The agent reads that list, decides when one is relevant, calls it, and receives the result.

That is the whole idea. Everything else — the transport, the schema format, the handshake — is plumbing that a library handles.

What it buys you is that the agent can now do something specific to your work: query your own data, drive an application you use, run a process only you have. Without it, the agent is limited to files and shell commands.

An agent can already run commands and read files. If your capability is available as a CLI, it is available already, and a server adds nothing but maintenance.

A server earns its place when:

• The capability is not exposed as a command — an application's internal API, a live session, a scripting interface.
• The interaction is stateful, and a fresh process each time would lose that state.
• Raw output needs shaping into something an agent can use without reading a wall of text.

That last one is underrated. A server whose job is returning a compact, structured answer instead of a hundred lines is doing real work even when the underlying command exists.

Pick one thing. Register it with a name, a description, and a typed input. Return a short result.

@server.tool()
def project_status(name: str) -> str:
    """Return the current status of a project by name.
    Use when asked what state a project is in."""
    ...
    return summary

The description is the important part and it is written for a reader deciding whether to call it, not for a developer reading source. Say what it does and when to use it. A vague description means the tool is either never called or called at the wrong moment.

Get one tool working before adding a second. The first one is where all the setup problems appear.

Add the server to your agent's configuration with the command that launches it, then restart the session so it is picked up.

Verify by asking the agent what tools it can see, rather than by asking it to do the thing. If the tool is not listed, no amount of prompting will invoke it, and you are debugging the wrong layer.

Common causes when it does not appear: the process exits immediately, a dependency is missing in the environment the agent launches it from, or the path in the configuration is relative when it needed to be absolute.

The instinct is to return everything relevant. That fills the conversation with material and forces the agent to parse prose.

Return the specific answer, compactly. Where output could be large, return a summary plus a way to fetch detail — a count, a list of identifiers, an option to request one item in full.

Errors deserve the same care. 'Failed' is unusable. 'Project not found; available: a, b, c' lets the agent correct itself in one step instead of asking you.

Tool lists are loaded whether or not they are used. A large server imposes that cost on every session, including all the ones where it is irrelevant.

Expose the operations you actually invoke. Combine related ones behind a single tool with a mode parameter rather than exposing every variation separately.

Review it occasionally and delete what you have not called. The good version of a personal server is small, specific, and describes itself well enough that the agent reaches for it at the right moment without being told.