mcp-v2-minimal

A minimal MCP (Model Context Protocol) server that actually runs on the current spec — 2026-07-28 — using TypeScript SDK v2 (@modelcontextprotocol/server 2.4.x).

Most MCP server examples you will find online target the 2025 revisions. They fail on today's SDK, and they fail quietly: the host connects, then lists no tools.

[error] MCP server "myserver" failed to start: no tools found

This repo is the smallest thing that works, plus the notes that explain why the old shape stopped working.

Verified on @modelcontextprotocol/server 2.4.0 · MCP spec 2026-07-28 · Node 20+
Built and smoke-tested on Node 25.8.2 / TypeScript 7.0.2

This repo is the minimal cut. The parts that cost the hours are in a paid kit: Streamable HTTP with the Host/Origin guards, resources and resource templates, an 18-test harness, and the cookbook with the full v1 → v2 migration diff. MCP Starter Kit — $29 →

Quick start

npm install
npm run build
npm run smoke     # drives the server with a real client in memory — 6 checks, no subprocess
npm start         # the server itself; it waits on stdin

npm start prints one line to stderr and then waits. That is success:

[mcp-v2-minimal] ready on stdio

Related MCP server: MPC-PoC-1-EchoServerToolsbasicas

Register it in a host

The host launches your server as a child process and speaks JSON-RPC over its stdin/stdout. Every host uses the same launch command; only the config file differs.

Claude Code

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

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "minimal": { "command": "node", "args": ["/absolute/path/to/mcp-v2-minimal/dist/index.js"] }
  }
}

VS Code (GitHub Copilot) — .vscode/mcp.json

{
  "servers": {
    "minimal": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}

Claude Desktop — claude_desktop_config.json, same mcpServers shape as Cursor.

What changed, and why your old snippet breaks

The three symptoms these cause, in the order you will meet them:

1. Connects, then no tools. A console.log in the startup path. stdout is the protocol channel.

2. TypeError: server.connect is not a function. v1 code on v2.

3. server/discover returns -32601 Method not found. Not a bug: a request without _meta["io.modelcontextprotocol/protocolVersion"] is routed to the legacy 2025 path.

The minimal server, in full

import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

export function createServer(): McpServer {
  const server = new McpServer({ name: 'mcp-v2-minimal', version: '1.0.0' });

  server.registerTool(
    'echo',
    {
      description: 'Return the text you pass in',
      inputSchema: z.object({ text: z.string().describe('Text to echo back') })
    },
    async ({ text }) => ({ content: [{ type: 'text', text }] })
  );

  return server;
}

void serveStdio(createServer);
console.error('[mcp-v2-minimal] ready on stdio');   // never console.log

Three details that matter more than they look:

• serveStdio takes the factory, not an instance. That is what makes the identical server serve HTTP later — the factory is called once per request, so nothing may be kept on the instance.

• inputSchema is the only schema you write. The SDK derives the JSON Schema the model sees, validates arguments before your handler runs, and infers your handler's types.

• Bad arguments return an isError: true tool result, not a throw. That is deliberate: the model reads the message and retries. json_format in src/index.ts shows the pattern.

What the full kit adds (only if you need it)

This repo is deliberately minimal: one transport, two tools, no HTTP. The kit is for the moment you outgrow it.

→ https://haojm.gumroad.com/l/mcp-starter-kit

If this repo saved you an hour, a ⭐ helps someone else find it.

License

MIT — see LICENSE.