Node MCP Server V2

Code patterns are adapted from the MCP TypeScript SDK examples (opens in a new tab). The full v2 documentation index is https://ts.sdk.modelcontextprotocol.io/v2/llms.txt; every page is also served as markdown at its .md URL.

Quick Reference

Install

A Server in One Screen

v1 → v2 at a Glance

Most published examples and training data show v1 code. Translate it before use:

Do not use imports from @modelcontextprotocol/sdk/..., raw-shape schemas, Zod 3 or zod/v3, hand-wired StreamableHTTPServerTransport instances, or a shared McpServer instance returned from the factory (one created at module scope and reused across HTTP requests) in a v2 server.

Project Setup

Name the package and server {service}-mcp-server (lowercase, hyphens, no version numbers), e.g. github-mcp-server, jira-mcp-server.

package.json

• bin plus the #!/usr/bin/env node line at the top of src/index.ts let hosts launch the server with npx -y {service}-mcp-server
• A stdio-only server can drop express, @types/express, and the two adapter packages
• Keep zod at ^4.2.0 or later: v2 does not support Zod 3, and Zod 4.0–4.1 schemas fail to type-check in registerTool. If the server runs anyway (tsx skips type-checking), the SDK logs a fallback warning and, before 4.1.13, drops .describe() text from the advertised schemas

tsconfig.json

The Server Factory

Write a createServer() function that builds a fresh McpServer and registers every tool, resource, and prompt on it. You never call it yourself: the transport entry points do.

• serveStdio(createServer) calls it once for the stdio connection
• createMcpHandler(createServer) calls it once per HTTP request, so the HTTP server keeps no state between requests and scales horizontally as-is
• Register everything inside the factory, never on a shared instance outside it
• Return a new McpServer from every call. A factory that returns one shared instance passes manual tests and the self-check script, because they send one request at a time. A request that arrives while another is being served fails with -32603 “Internal server error”, and the cause goes only to the handler’s onerror option
• Keep the factory cheap: create API clients, connection pools, caches, and configuration once at module scope and close over them
• Behind createMcpHandler, the factory receives the request context: createMcpHandler(({ authInfo }) => ...) builds an instance for one authenticated caller

One file can serve both transports; the complete example picks one from the TRANSPORT environment variable.

Calling the Upstream API

Put the upstream API client at module scope, in one apiRequest helper that every tool calls. Node 20+ has fetch built in. The core of the complete example‘s helper:

• Send whatever the API requires (API key, User-Agent, version header) here, in one place
• Tool handlers pass ctx.mcpReq.signal, so a cancelled call also cancels its upstream request
• Map HTTP statuses and timeouts to messages that say how to recover (httpErrorMessage in the complete example): “Rate limit exceeded. Wait a minute before making more requests.”
• ApiError takes its message from httpErrorMessage and keeps the HTTP status, so a caller can treat a 404 differently from a 401 or a 429
• Tool handlers can let these errors propagate: the SDK turns anything a tool handler throws into an isError: true result whose text is the error’s message

Designing Tools

Names and Descriptions

• Use snake_case, action-oriented names with a service prefix: slack_send_message, github_create_issue, asana_list_tasks
• The description is what the model reads to decide when and how to call the tool. Say what it does, what it returns, when to use a sibling tool instead, and give one or two example requests. JSDoc comments are not extracted
• Give every tool a title (display name), description, inputSchema (if it takes arguments), and annotations

Annotations

Annotations are hints for clients, for example to auto-approve read-only tools or to confirm destructive ones. They never change how the SDK runs the tool.

Input Schemas

inputSchema is a Zod object schema: z.object({...}), or z.strictObject({...}) to reject unknown arguments. From that one schema the SDK derives the JSON Schema clients see, validates arguments before your handler runs, and infers the handler’s argument types (no annotation needed).

• .describe() text becomes the argument’s JSON Schema description, the only documentation the model gets for it
• Fields with .default() are optional for the caller and always present in the handler’s arguments
• Arguments that fail validation never reach the handler; the client gets an isError: true result such as Input validation error: Invalid arguments for tool example_search_users: query: Too small: expected string to have >=2 characters
• Zod 4 replaced some v3 APIs: z.strictObject({...}) instead of .strict(), z.enum(MyTsEnum) instead of z.nativeEnum, and z.email() / z.url() / z.uuid() instead of z.string().email() and similar

Output: Markdown, JSON, and structuredContent

Let the caller choose the format with a response_format argument:

• Markdown (default): readable text for the model. Headers and lists, human-readable dates, display names with IDs in parentheses, no verbose metadata
• JSON: complete data for programmatic use, with consistent field names

When a result includes structuredContent, the spec says it SHOULD also include the same data serialized as JSON in a text block. So:

• In JSON mode, return the data as structuredContent and its JSON.stringify as the text
• In Markdown mode, return only the Markdown text
• Declare outputSchema only on tools whose output is always JSON. With an outputSchema, every successful result must include matching structuredContent, or the SDK replaces it with an output validation error
• The advertised outputSchema disallows extra fields, so build structuredContent from the schema, e.g. UserSchema.parse(raw), which also validates the upstream data

Pagination

List and search tools take limit and offset and return where the next page starts:

In Markdown mode, end the text with how to get more, e.g. More results: call again with offset=20.

Character Limit

Cap responses with a CHARACTER_LIMIT (25,000 characters is a good default). Stay under it by returning fewer items, never by cutting text: next_offset then points at the first item left out, and the JSON text still matches structuredContent. Measure the text the tool sends, not an intermediate value: pretty-printing and the page fields count too.

render(users) builds the page and its text in the requested format; see the complete example.

Errors

MCP has two error channels:

• Tool errors are tool results with isError: true. The model reads them, so the text should say how to recover. A tool handler produces them by returning isError: true, or by throwing: the thrown error’s message becomes the result text
• Protocol errors are JSON-RPC error responses handled by the client application; the model never sees them. Resource and prompt callbacks have no isError channel, so they throw ProtocolError (see Resources and Prompts)

Complete Example

One file, two tools, both transports. example_search_users shows pagination, the character limit, and the two output formats; example_get_user shows an outputSchema.

Serving

stdio (Local Servers)

serveStdio(createServer) reads requests on stdin and writes responses on stdout. Never write to stdout yourself: one console.log corrupts the JSON-RPC stream. Log with console.error.

Streamable HTTP (Remote Servers)

createMcpHandler(createServer) returns a web-standard handler; toNodeHandler adapts it to Express:

• It serves clients on the 2026-07-28 protocol revision and older 2025-era clients from the same factory, with no sessions for either
• createMcpExpressApp() installs express.json() and validates Host and Origin headers on localhost binds, which blocks DNS rebinding attacks. When binding all interfaces, name the hosts you serve: createMcpExpressApp({ host: "0.0.0.0", allowedHosts: ["mcp.example.com"] })
• Hono and Fastify adapters are @modelcontextprotocol/hono and @modelcontextprotocol/fastify
• On web-standard runtimes (Cloudflare Workers, Deno, Bun), export default handler is the whole mount; put Host/Origin checks in front as described in the web-standard docs (opens in a new tab)

Authentication

The handler verifies no tokens. For a server exposed beyond localhost, put requireBearerAuth in front of the route:

• expectedResource accepts only tokens issued for this server, so a token meant for another service is refused
• The verified AuthInfo reaches the factory as createMcpHandler(({ authInfo }) => ...) and tool handlers as ctx.http?.authInfo (undefined on stdio)
• Serving OAuth discovery metadata and per-tool scopes are covered by the oauth (opens in a new tab) and scoped-tools (opens in a new tab) examples and the authorization docs (opens in a new tab)

Transport selection: stdio for local tools a host launches as a subprocess; Streamable HTTP for remote services and multiple clients.

Resources and Prompts

Resources expose read-only data at a URI that the client application reads and attaches as context. Prompts are message templates a user invokes by name. Tools are for anything the model should call, including operations with side effects.

• Give a template a list callback that returns { resources: [...] } to make its instances appear in resources/list; { list: undefined } leaves them readable but unlisted
• If a template variable becomes a filesystem path, resolve it with realpath and reject anything outside your root before reading

Notifications

The handles returned by registerTool, registerResource, and registerPrompt send the matching list_changed notification when you change them:

Behind createMcpHandler each request has its own server instance, so publish changes through the handler instead: handler.notify.toolsChanged(), handler.notify.resourcesChanged(). Send notifications only when the server’s capabilities actually change.

Verify Your Server

Write a self-check script that starts the built server, calls its tools as a client would, and exits non-zero on any failure. Run it after every change, along with npm run build; adapt the tool names and assertions to your server.

• Call read-only tools with realistic arguments; check that one invalid input is rejected
• StdioClientTransport gives the child process only a safe default environment (PATH, HOME, and similar), so pass API keys and other settings in env
• For an HTTP server, start it (TRANSPORT=http npm start) and connect with new StreamableHTTPClientTransport(new URL("http://127.0.0.1:3000/mcp")) from @modelcontextprotocol/client instead
• For manual exploration, npx @modelcontextprotocol/inspector node dist/index.js opens an interactive UI
• More test patterns, including in-process tests without a subprocess: https://ts.sdk.modelcontextprotocol.io/v2/testing.md

More Features

Each linked example is a runnable server and client pair from the SDK repository:

Migrating a v1 Server

To move an existing @modelcontextprotocol/sdk server to v2, run the official codemod at the package root, then fix what it marks:

The codemod rewrites imports, package.json, registration calls, and handler context access. Check that zod ends up at ^4.2.0 or later, then run your formatter and tests. The full guide is at https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2.md.

Quality Checklist

Tool Design

• Not done: Tools enable complete workflows, not just API endpoint wrappers
• Not done: Tool names are snake_case with a service prefix
• Not done: Every tool has a title, a description that says when to use it, and correct annotations
• Not done: Inputs are Zod object schemas with constraints and .describe() text; z.strictObject where unknown arguments should be rejected
• Not done: List and search tools paginate with limit / offset and return next_offset
• Not done: Responses stay under CHARACTER_LIMIT by returning fewer items
• Not done: Results with structuredContent also include that data serialized as JSON text; outputSchema only on always-JSON tools
• Not done: Error messages say what went wrong and how to recover

Implementation

• Not done: createServer() returns a new McpServer on every call, with everything registered inside it; shared clients live at module scope
• Not done: Upstream requests pass ctx.mcpReq.signal and have a timeout
• Not done: Strict TypeScript; no any; upstream data validated where it feeds structuredContent
• Not done: Nothing writes to stdout in a stdio server
• Not done: HTTP servers keep Host/Origin validation, and add bearer auth when exposed beyond localhost

Project

• Not done: package.json depends on @modelcontextprotocol/server (not @modelcontextprotocol/sdk) and zod ^4.2.0 or later
• Not done: No imports from @modelcontextprotocol/sdk/... or zod/v3
• Not done: bin points at dist/index.js, and src/index.ts starts with #!/usr/bin/env node

Verification

• Not done: npm run build completes without errors
• Not done: The self-check script passes against the built server