A 97-line MCP server for Claude Code, and when Claude uses it

How do you build an MCP server for Claude Code, and will Claude actually use it? I wrote a stdio MCP server in 97 lines of Node that searches a folder of Markdown files, connected it to Claude Code, and asked 12 questions that only those files answer, 192 times. The server worked on the first try. Whether Claude used it depended on the names: with Claude Code’s default tool search, a tool called search_notes was called in 43 of 48 runs, the same tool renamed query with the description “Runs a query.” in 20 of 48, and the vague tool plus two sentences of server instructions in 46 of 48.

That gap comes from how Claude Code loads MCP tools now. Until Claude asks for a tool, it sees only the tool’s name and the server’s instructions, not the description you wrote. So the name and the instructions are the parts doing the work.

This is the second post on agent memory and MCP. The first measured how often an MCP memory server returns the right note. This one is about the step before that: getting Claude to call your server at all.

How do you build an MCP server for Claude Code?

With the official TypeScript SDK (@modelcontextprotocol/sdk 1.32.1) and zod for the input schemas, a server is a name, some tools and a transport. Mine loads every .md file in a folder at startup, keeps word counts in memory, and ranks files with BM25 plus a boost for words in the title. It exposes two tools: search_notes, which returns the top files with a snippet, and read_note, which returns one file in full. The part that talks to Claude is short:

const server = new McpServer({ name: "notes-search", version: "1.0.0" });

server.registerTool(
  "search_notes",
  {
    description:
      `Full-text search over ${docs.length} Markdown notes and blog posts in a local folder. ` +
      "Returns the best matching files with a title, a relevance score and a snippet. " +
      "Use it before answering questions about what these notes say.",
    inputSchema: {
      query: z.string().describe("Words to look for, for example 'llama.cpp context size'"),
      limit: z.number().int().min(1).max(10).default(3).describe("How many files to return"),
    },
  },
  async ({ query, limit }) => ({ content: [{ type: "text", text: JSON.stringify(search(query, limit), null, 2) }] }),
);

await server.connect(new StdioServerTransport());
console.error(`notes-search: ${docs.length} notes indexed`);

The last line goes to stderr on purpose. In a stdio server, stdout carries the JSON-RPC messages; more on what happens when you get that wrong below. The full file, with the search code and read_note, is server.mjs.

Adding it to Claude Code is one command:

claude mcp add notes -- node /path/to/server.mjs /path/to/your/notes

On this laptop (2 cores, with other programs using part of the CPU), Claude Code’s own log reported the connection in a median 638 ms over 192 launches (534 to 1170 ms). Most of that is Node loading the SDK: my bare JSON-RPC client measured 383 ms to the initialize reply, 14 ms for tools/list and 9 ms for a search over the seven files.

Does Claude Code actually use your MCP tool?

To find out, I pointed the server at the seven posts of this blog and wrote 12 questions whose answers are in them, such as “How much RAM did the Hermes Agent gateway use while idle?” Each question went to claude -p (Claude Code 2.1.300, Claude Sonnet 5.5) in two phrasings: hinted, starting with “Check my notes.”, and bare, the question alone. The working folder was empty, so the built-in file tools had nothing to find, and web search was off.

The server ran in four versions:

Condition	Server name	Tool names and descriptions	Server instructions	Tool search
clear	notes	search_notes, read_note, full descriptions	none	on (default)
vague	s1	query (“Runs a query.”), get (“Gets an item by path.”)	none	on
vague + instructions	s1	same as vague	two sentences	on
clear, upfront	notes	same as clear	none	off

That is 12 questions, 2 phrasings, 4 conditions and 2 repetitions: 192 runs. I recorded every tool call, then checked each answer against the expected number and read by hand every answer that looked right without a tool call:

Condition	Called the MCP tool	Right answer	Called it, bare questions only
clear	43 / 48	47 / 48	19 / 24
vague	20 / 48	24 / 48	3 / 24
vague + instructions	46 / 48	48 / 48	22 / 24
clear, upfront	48 / 48	48 / 48	24 / 24

Every time Claude called the tool, the answer was right. Every wrong answer came from a run that never called it. The vague server was not broken; it was ignored. In 28 of its 48 runs Claude never opened it. It ran grep and ls on the empty folder, in 31 runs also tried to search outside it, often the whole home directory (Claude Code’s permission checks blocked every one of those commands), and then said it could not find the notes. Even “Check my notes.” only got the vague tool used in 17 of 24 runs.

The few right answers without the tool were questions Claude knows from training: Ollama’s default context without a GPU (4,096 tokens) and Hermes Agent’s 64K minimum. In those runs it said it was answering from memory. I graded two answers as wrong by hand because they were guesses: “I can’t answer that”, followed by “you’d expect all 120 to pass”. The overrides file lists them.

Why do the tool name and server instructions matter so much?

Because with tool search, the description is not in the context when Claude decides. Since tool search became the default, Claude Code defers MCP tools: at the start of a session Claude sees a list of tool names such as mcp__notes__search_notes and the servers’ instructions, plus a ToolSearch tool to load the full definitions. The Claude Code MCP docs put it plainly: “Only tool names and server instructions load at session start.”

The runs show Claude choosing from that list by name. Across all 192 runs it called ToolSearch 113 times, and all 113 were select: with exact tool names, never a keyword search. When it loaded the vague tool, it used it and got the answer, 20 times out of 20. The problem was deciding to load it: mcp__s1__query says nothing about notes, and mcp__notes__search_notes does.

Server instructions are the one free-text field Claude sees before loading anything. These two sentences took the vague server from 20 to 46 of 48:

This server searches the user's local Markdown notes and blog posts about local LLMs, llama.cpp, Ollama,
Hermes Agent, ai-memory and Claude Code. Use the query tool when the user asks about their notes or about
results from these experiments.

With instructions, the vague server even beat the clear one on bare questions (22 against 19 of 24). The clear server had no instructions, so for a bare question Claude had only the word “notes” to go on.

Should you turn tool search off?

Turning it off (ENABLE_TOOL_SEARCH=false) loads every tool definition upfront, and Claude used the clear tool in all 48 runs. It costs context, though, and mostly not for your server. I measured the input tokens of a one-turn “Reply with OK” prompt:

Setup	Input tokens
No MCP server, tool search on	13,486
This server, tool search on	13,508 (+22)
No MCP server, tool search off	27,979
This server, tool search off	28,327 (+348)

My two tools cost 22 tokens deferred and 348 upfront. But switching tool search off also loads about 14,500 tokens of Claude Code’s own deferred tools, with or without any MCP server. That is paid on every request of every session. For one small server, a clear name and a couple of sentences of instructions get you most of the way without it. The docs also describe a per-tool _meta["anthropic/alwaysLoad"] and a per-server alwaysLoad setting to load just your tools upfront. I tested those later: one tool marked alwaysLoad was called in 96 of 96 runs, like tool search off, for 238 tokens instead of about 12,000.

Does console.log break an MCP stdio server?

Every MCP tutorial warns that printing to stdout corrupts the protocol. I tried four mistakes, three times each with tool search on and three times with it off, asking a question the notes answer:

Mistake	Connected	What happened
console.log one line before the handshake	6 / 6	Worked
console.log one line on every request	6 / 6	Worked; Claude Code logs “Ignoring non-JSON line on stdout”
process.stdout.write("loading... ") with no newline	1 / 6	First launch only, then 30 s timeouts
A stdin listener added before the transport	1 / 6	First launch only, then 30 s timeouts

So in Claude Code 2.1.300, a whole stray line is skipped. A write without a newline is not: it glues itself to the front of the server’s next message, and that message is lost.

The “first launch only” part was the surprise. Claude Code’s debug log (in ~/.cache/claude-cli-nodejs/<project>/mcp-logs-<server>/) shows that on the first launch it sends a server/discover probe for the newest protocol revision, and when the probe gets no usable answer it falls back to a classic initialize. That took 3.2 s, and the broken message was the probe’s reply, so the session worked. After that it remembers the server as a “legacy peer” and sends initialize first. Now initialize’s reply is the one that gets corrupted, and the connection times out after 30 s on every launch. A server with this bug works the first time you try it and fails from then on.

The fourth row was my own mistake. I first wrote the “log on every request” test by adding a process.stdin.on("data") listener before importing the server. That puts stdin in flowing mode before the transport is listening, so the first request is read by my listener and never reaches the SDK. Same symptom, a different cause.

What happens when an MCP server fails to connect?

That depends on tool search too, which the docs mention and the runs confirm. With tool search on, Claude Code told Claude the server had failed, and Claude said so in 1 or 2 turns: “I can’t answer that yet because the notes server failed to connect (it timed out after 30 seconds)”. With tool search off, Claude was not told. In all 6 failed runs it went looking for the notes on its own, 4 to 7 turns of grep and ls, including attempts to search the whole home directory that the permission system blocked, and ended with “I couldn’t find your notes”. Those runs used 113,000 to 200,000 input tokens to reach a worse answer.

How to write an MCP server Claude Code will find

• Name the server and tools after what they hold. notes and search_notes beat s1 and query by 43 to 20 of 48 runs, with identical code behind them.
• Write server instructions. They are the only description Claude reads before loading your tools. Say what data the server has and when to use it, with the words users will type.
• Don’t count on the tool description to get you picked. It matters once the tool is loaded, not before.
• Keep stdout for the protocol. Log with console.error. If you must print at startup, never leave a line without its newline.
• Test the second launch, not just the first. Two of my broken servers passed the first try.
• Read the server log when a tool goes missing. Claude Code’s MCP log said exactly what happened every time.

What broke and what I’d do differently

• My first full run of 192 questions had my own global CLAUDE.md loaded. --setting-sources does not cover CLAUDE.md files, and mine tells Claude to check its memory tools before answering. That made Claude much more willing to look for tools: the vague server was called in 24 of 24 hinted runs then, against 17 of 24 clean. I discarded those runs and redid everything with CLAUDE_CODE_DISABLE_CLAUDE_MDS=1 and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. If you benchmark Claude Code, check what your personal instructions are adding.
• The Claude Code binary was replaced by an automatic update in the middle of that first run, and 16 launches exited at once with code 2. The benchmark now retries a launch that returns no output.
• One of my expected answers was broken: question 5 asked “how many of the 120 replies passed”, and the pattern 120 matched answers that just repeated the question. I fixed the pattern and graded the doubtful answers by hand.
• The sample is small: one model, one corpus of seven files, 12 questions, 2 repetitions. The direction of the gap was the same in both repetitions, but don’t read the exact counts as precise rates.
• Claude Code reported USD 6.27 at API prices for the 192 clean runs (it ran on a subscription), and about USD 8.70 more for the discarded run, the overhead tests and smoke tests.

Everything is in the project folder: the server, the questions and naming variants, the scripts that drive claude -p, and every run with its tool calls and answers. If you run headless Claude Code on a schedule, the daily timer post covers that setup. The same claude -p usage numbers are how I later measured how many tokens a codebase is for Claude. And when a Skill does the same job as the server, which one Claude uses comes down to the same names and server instructions.