MCP servers and clients

In the Model Context Protocol, the AI agent is the client and the thing it reaches out to is the server. The client asks, the server answers. When the data the server works with should never leave your computer, such as your own source code, the right shape is a server that runs locally, on the same machine as the client.

Two roles, not two machines

The words client and server describe roles in a conversation, not sizes or locations of computers. The client is whoever wants something done. The server is whoever offers to do it. That is the entire distinction, and holding it plainly will save you a lot of confusion, because both roles can run on the same laptop, and a program can be a client in one conversation and a server in another.

A restaurant makes the roles concrete. You, at the table, are the client. You do not go into the kitchen. You read a menu, decide what you want, and ask for it. The kitchen is the server. It knows how to make the dishes and it does the work out of your sight. You do not need to know how the kitchen is organized, and the kitchen does not need to know anything about you except your order. The menu is what connects the two: a fixed list of what can be asked for, in a form both sides understand.

In MCP, the AI agent is always the client. It is the party with a goal that decides it needs something from the outside. Each capability it has been connected to is a server. When the agent wants to search your code or check what a change would affect, it does not do that work directly. It sends an order, in the shape the protocol defines, to the server that offers that dish. The server does the work and hands back a result. The agent reads the result and keeps going. The client decides what and when. The server knows how.

How the message gets across: transport

For the client to send an order and the server to send a result, there has to be a channel between them. The way messages physically travel is called the transport, and MCP allows more than one, because a server can sit in two very different places.

In the first arrangement, the server is a small program running on the same machine as the client. The client starts it as a local process, and the two talk directly, on the same computer, the way two programs on your laptop can pass messages without any network in between. Nothing leaves the machine. This is the natural shape when the server’s whole job is to work on data that already lives on that machine.

In the second arrangement, the server runs on a different computer, somewhere across a network, and the client reaches it the way your browser reaches a website: a request goes out over the network, and a response comes back. This makes sense when the server offers something that is inherently remote, like a hosted service or a shared database that many people use at once.

The important thing is that the protocol is the same in both cases. The client asks in the same way and reads results in the same way whether the server is a program next to it or a machine on the far side of the world. Transport is the road; the protocol is the language spoken on it. Because the language does not change with the road, a client does not have to be rebuilt to talk to a local server versus a remote one, and the choice of where a server lives can be made on its own merits.

When local is the right shape

Running a server on your own machine is the right choice whenever the data it works with should not leave that machine. Source code is the clearest example. A company’s code is often its most sensitive asset. It may be private intellectual property, it may be under contractual or legal restrictions on where it can be stored, and it is exactly the thing a business least wants copied to a computer it does not control. If a server that analyzes your code ran on someone else’s machine, your code would have to be sent there first. A local server removes that step entirely, because the code and the analysis are on the same machine from the start.

Privacy is not the only reason, though it is the loudest. Many organizations operate under rules, whether legal, contractual, or internal, about where certain data is allowed to travel. In those settings, the question is not only whether you trust a remote service but whether you are even permitted to send the data to it. A tool that never moves the data off the machine sidesteps that question, because there is nothing to review and nothing to approve: the data stays exactly where it already was.

There are ordinary benefits too. A local server has no network round trip, so answers come back without the delay of sending a request across the world and waiting for a reply. And it works when the network does not: on a plane, on a train, behind a strict firewall, or during an outage. There is also a tradeoff to be honest about. A local server uses your own computer’s processor and memory to do its work, and it cannot be shared, so each machine runs its own copy rather than everyone querying one central instance. For code, where privacy is the whole point, that tradeoff is usually well worth making.

Koragraph is built exactly this way. It is a local MCP server that gives AI coding agents a persistent, offline, multi repo code knowledge graph, with no LLM or cloud dependency. It runs entirely on the developer’s machine, and no source code leaves the machine. The facts it learns about your code are kept in a local database file on that same machine, at ~/.koragraph/practice.db. Local is not an incidental detail of how it happens to be packaged; it is the direct answer to the question of where code analysis belongs.

A local server is the right shape whenever the honest answer to where should this data live is right here, and nowhere else.

The trust boundary

A trust boundary is the line across which you have to start being careful, because on the far side of it you are handing something to a party you do not fully control. Every connection has one, and it helps to know where yours is.

When a server runs remotely, the trust boundary sits at the network. To use the server you must send your data across that line to a machine someone else runs, and you are trusting them to handle it well: to keep it private, to not retain it longer than they should, and to secure it against others. That trust may be perfectly reasonable, but it is real, and for highly sensitive data it is a decision that deserves thought.

When a server runs locally, the trust boundary stays on your own machine. The data does not cross a network to reach the server, because they are in the same place. That does not make trust disappear, since a local program is still software you chose to run and it can read the files you point it at. But it collapses the boundary down to a single question you can answer for yourself: do I trust this program on my own computer. It removes the separate and harder question of whether you trust a distant service with a copy of your code, because no copy is ever sent. For source code, keeping the boundary local is often the deciding factor.

How a client discovers what a server can do

A client is not told in advance what any given server offers. Instead, when the two first connect, the client asks, and the server describes itself. This step is called discovery, and it is why a single client can work with servers it was never specifically built for.

Return to the restaurant. You do not memorize every dish before you sit down. You are handed a menu, and the menu lists what this kitchen makes, along with enough of a description of each dish that you can decide what to order. Discovery is the client being handed the menu. It asks the server what it offers, and the server answers with a list of its capabilities, each one described well enough that the agent can tell when it would be the right thing to reach for.

This is what makes the whole arrangement flexible. Because the client learns a server’s capabilities at connection time rather than having them wired in ahead of time, you can add a new server to an agent and the agent simply picks up the new abilities. It reads the fresh menu and now has more it can order. Nothing about the agent had to change. The descriptions the server hands over during discovery are what let the model choose the right capability at the right moment, a behavior taken up in Tool use and function calling.

Discovery also keeps the two sides honest about versions. A server can grow over time, adding a new capability or refining an old one, and because the client asks fresh each time they connect, it always sees the current menu rather than a stale copy. The client does not have to be reinstalled or reconfigured to notice that a server can now do more. It simply reads what the server reports today. This is the same reason a restaurant can change its menu without reprinting every customer’s memory: the truth lives with the kitchen, and the diner reads it at the table.

Registering a server with a client

Before discovery can happen, the client has to be told the server exists. You do this once, and from then on the client knows to start or reach that server and ask it for its menu. The details differ by client, but the idea is always the same: name the server and say how to launch or find it.

Koragraph makes a good concrete walk through, because it is a local server and the steps are short. First you install the server program on your machine, then you have it read a repository so it has something to serve, then you check that everything is in order, and finally you register it with your agent so the agent can start using it.

npm install -g koragraphmcp
koragraph ingest /path/to/repo
koragraph doctor
claude mcp add koragraph -s user -- koragraph mcp

Read from the top, those four lines are the whole arc of connecting a server. The first installs Koragraph, which needs Node.js version 22 or newer to run. The second points it at a repository and has it build its map of the code, a step called ingesting, covered in its own concept. The third runs a self check. The fourth is the registration itself: it tells the client, in this case Claude Code, that there is a server named koragraph and how to start it, so that from then on the agent can discover Koragraph’s capabilities and call them. After that single setup, the client and server meet through the protocol on their own.

It is worth naming what the registration line does not do. It does not send your code anywhere, and it does not depend on a network service. It simply records, on your machine, that this local program is a server the agent may talk to. That is consistent with everything above: the client and the server are two roles, meeting locally, across a trust boundary that never has to leave your computer.

Where this leads

With the roles clear, the next question is what a server actually puts on its menu. A server does not offer one undifferentiated capability; it offers a few distinct kinds of thing, and sorting them out is the subject of Tools, resources and prompts. And the reason a code server in particular is built to run on your own machine, keeping every step of its work and every fact it stores on that machine, is drawn out in Local-first, offline by design.