How to build an MCP server that a model actually uses correctly

Every code sample here is taken from a working repository, verified against @modelcontextprotocol/sdk@1.30.0 on Node 20, with an integration test that passes. If you would rather read the finished thing, it is at ImTaegan/mcp-server-starter.

Start with the thing that will waste your afternoon otherwise. The SDK deprecated server.tool(), server.resource() and server.prompt() in favour of registerTool, registerResource and registerPrompt. Most tutorials, most blog posts, and a good deal of what an assistant will confidently tell you still use the old ones. They work today and they emit deprecation warnings.

What MCP actually is

The Model Context Protocol is a JSON-RPC contract that lets a model host discover and use capabilities you expose, without anyone writing integration code for your specific service.

That is the whole idea. You could expose the same functionality as a REST API and nothing about the transport would be meaningfully different. The difference is who does the wiring. A REST API needs a developer to integrate it into each client. An MCP server is added by configuration, and the host then knows how to list your tools, read their schemas, decide when to call them, and surface your prompts as slash commands.

There are three primitives, and picking the right one matters:

If the model should decide, it is a tool. If a human should decide, it is a resource or a prompt. Most servers reach for tools by reflex and end up with a model that has to guess its way to information the user could simply have attached.

A minimal server

Two dependencies, and the SDK brings its own validation:

npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

Keep the server construction separate from the transport wiring. It costs nothing now and it is what makes the server testable later:

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function createServer(): McpServer {
  const server = new McpServer({ name: "notes", version: "1.0.0" });

  server.registerTool(
    "search_notes",
    {
      title: "Search notes",
      description: "...", // covered properly below
      inputSchema: {
        query: z.string().min(1).describe("Keywords to match."),
        limit: z.number().int().min(1).max(50).default(10),
      },
      annotations: { readOnlyHint: true, idempotentHint: true },
    },
    async ({ query, limit }) => ({
      content: [{ type: "text", text: `searched for ${query}, max ${limit}` }],
    }),
  );

  return server;
}

Note that inputSchema takes a plain object of Zod validators rather than a Zod object. The SDK converts it to JSON Schema for the wire and hands your callback typed arguments.

The transport wiring is then genuinely tiny:

// src/index.ts
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createServer } from "./server.js";

const server = createServer();
await server.connect(new StdioServerTransport());
console.error("notes MCP server ready on stdio");

That console.error is not a typo. On the stdio transport, stdout is the protocol stream. A single console.log anywhere in your server, or in a dependency, writes garbage into the JSON-RPC channel and the client disconnects with an error that names none of this. Log to stderr, always.

Designing tools a model calls correctly

This is the part that decides whether your server is good, and it is the part almost every tutorial skips.

A tool description is not documentation. It is the prompt the model reads when deciding whether to call this tool instead of another one, or instead of answering from memory. Judge it as a prompt, not as a docstring.

// Accurate. Useless.
description: "Searches notes."

// What the model needs
description:
  "Search the user's saved notes by keyword, optionally filtered to a " +
  "single tag. Use this before answering any question about what the user " +
  "has written down, and before adding a note, to avoid creating a " +
  "duplicate. Returns matching notes ordered by relevance, most relevant " +
  "first."

The second one answers three questions the first does not:

• What does it do, specifically enough to distinguish it from neighbouring tools
• When should it be reached for, including its relationship to other tools. “Before adding a note” is doing real work there.
• What comes back, so the model knows whether one call is enough

Parameters need the same treatment. Every field gets a .describe(), because the model sees those too:

inputSchema: {
  query: z.string().min(1)
    .describe("Keywords to match against note titles, bodies, and tags."),
  tag: z.string().optional()
    .describe("Restrict results to notes carrying this exact tag."),
  limit: z.number().int().min(1).max(50).default(10)
    .describe("Maximum number of notes to return."),
}

Three practices that fix most “the agent called the wrong tool” complaints, in order of effect:

1. Have fewer tools. Twelve overlapping tools perform worse than five clear ones. Every tool you add makes every other tool harder to choose correctly.
2. Disambiguate in the description itself. If two tools could plausibly apply, each should say when to prefer the other.
3. Return text a model can act on. Returning raw JSON is a habit from API design. Returning readable text with the ids still in it usually produces better behaviour.

Also worth setting: annotations. The readOnlyHint and idempotentHint flags tell the host how risky a call is, which is what lets a client auto-approve reads and stop to confirm writes. Leave them off and everything looks equally dangerous, so the user gets prompted constantly and starts approving without reading.

Resources and prompts, and when they beat tools

A resource is context the user attaches. There is no decision for the model to get wrong, which makes it both cheaper and more predictable than a tool for anything the user already knows they want:

server.registerResource(
  "all-notes",
  "notes://all",
  {
    title: "All notes",
    description: "Every saved note, newest last, as markdown.",
    mimeType: "text/markdown",
  },
  async (uri) => ({
    contents: [{ uri: uri.href, mimeType: "text/markdown", text: await renderAll() }],
  }),
);

A prompt is a template the user invokes, surfaced as a slash command in most clients. Prompts are not instructions the model picks up on its own, which is the most common misunderstanding about them:

server.registerPrompt(
  "summarise-notes",
  {
    title: "Summarise my notes",
    description: "Produce a short digest of notes matching a tag.",
    argsSchema: { tag: z.string().describe("The tag to summarise.") },
  },
  ({ tag }) => ({
    messages: [{
      role: "user",
      content: { type: "text", text: `Search my notes for "${tag}" and digest them.` },
    }],
  }),
);

Safety, before you connect it to anything

An MCP server is code a language model can invoke. Treat every tool argument as untrusted input, because it is: the model produced it, and the model was influenced by whatever it read.

• Validate at the boundary and mean it. Your Zod schema is the security boundary, not a convenience. Constrain enums, cap array lengths, bound numbers.
• Never interpolate arguments into a shell or a query. Same discipline as any user input, because it is less trustworthy than user input.
• Scope credentials to the server, not the user's whole account. If it only needs read access to one thing, give it only that.
• Be careful what you return.Tool output lands in the model's context, and anything in it can influence later behaviour. Returning raw third-party content is how prompt injection gets in.

Testing it properly

Calling your handler functions directly tests your functions. It does not test whether the server advertises them correctly, whether the schemas survive conversion, or whether the client can actually reach them. Connect a real client to a real server over an in-memory transport pair instead:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";

const server = createServer();
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test", version: "1.0.0" });

await Promise.all([
  server.connect(serverTransport),
  client.connect(clientTransport),
]);

const { tools } = await client.listTools();
const res = await client.callTool({
  name: "search_notes",
  arguments: { query: "sitemap" },
});

No process spawning, no fixtures, and it runs in milliseconds. The assertion worth writing first is not that a tool returns the right answer, it is that every tool has a description long enough to be useful:

for (const tool of tools) {
  assert.ok(
    (tool.description ?? "").length > 40,
    `${tool.name} needs a description the model can act on`,
  );
}

That test has caught more real problems for me than any assertion about return values, because a tool with a weak description fails silently: everything works, the model just never calls it.

Shipping it

Build, then point a client at the compiled entry point. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "NOTES_FILE": "/absolute/path/to/notes.json" }
    }
  }
}

For Claude Code it is one command:

claude mcp add notes -- node /absolute/path/to/dist/index.js

Paths must be absolute, since the host does not run your process from your project directory. If the server fails to appear, check stderr first: it is almost always an unresolved path or something writing to stdout.

Stdio is right for anything touching a developer's own machine. For a hosted server, the SDK ships a streamable HTTP transport, at which point authentication and multi-tenancy stop being optional and become the bulk of the work.

The complete server, with the tests, is at ImTaegan/mcp-server-starter. Clone it, strip the notes logic, keep the shape.