Building an MCP Server with the TypeScript SDK

The official TypeScript MCP SDK mirrors the Python SDK's shape: register tool and resource handlers on a server object, then run it over a transport.

If your service already lives in a Node codebase, this SDK lets you expose it to Claude without introducing a second language.

Summary

A TypeScript MCP server is built around McpServer, the SDK's high-level server class.

You register capabilities by calling server.tool(...) and server.resource(...) directly, rather than with decorators.

Zod schemas define each tool's input shape and double as runtime validation.

The server connects to a transport, most commonly StdioServerTransport for local development, the same way the Python SDK does.

This page mirrors the depth of the Python SDK article: typed arguments, error handling, and parameterized resources, expressed in idiomatic TypeScript.

Recipe

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
const server = new McpServer({ name: "tickets-server", version: "1.0.0" });
 
server.tool(
  "create_ticket",
  { title: z.string(), priority: z.enum(["low", "normal", "high"]).default("normal") },
  async ({ title, priority }) => ({
    content: [{ type: "text", text: `Created ticket for "${title}" (${priority})` }],
  })
);
 
await server.connect(new StdioServerTransport());

When to reach for this:

• Your existing service or team is already TypeScript/Node-based, and you want to avoid a second runtime.
• You want compile-time type checking on tool arguments alongside runtime validation from the same schema.
• You're building for local development first, StdioServerTransport is the right choice before adding a network layer.
• You want to share types between your MCP server and an existing TypeScript API surface.

Working Example

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
interface Ticket {
  id: string;
  title: string;
  priority: "low" | "normal" | "high";
  status: "open" | "closed";
}
 
const tickets = new Map<string, Ticket>([
  ["T-1", { id: "T-1", title: "Printer offline", priority: "low", status: "open" }],
  ["T-2", { id: "T-2", title: "VPN outage", priority: "high", status: "closed" }],
]);
let nextId = 3;
 
const server = new McpServer({ name: "tickets-server", version: "1.0.0" });
 
server.tool(
  "create_ticket",
  {
    title: z.string().min(1, "title is required"),
    priority: z.enum(["low", "normal", "high"]).default("normal"),
  },
  async ({ title, priority }) => {
    const id = `T-${nextId++}`;
    tickets.set(id, { id, title, priority, status: "open" });
    return { content: [{ type: "text", text: id }] };
  }
);
 
server.tool(
  "close_ticket",
  { ticketId: z.string() },
  async ({ ticketId }) => {
    const ticket = tickets.get(ticketId);
    if (!ticket) {
      throw new Error(`no ticket with id '${ticketId}'`);
    }
    ticket.status = "closed";
    return { content: [{ type: "text", text: `${ticketId} closed` }] };
  }
);
 
server.resource(
  "ticket",
  "tickets://{ticketId}",
  async (uri, { ticketId }) => {
    const ticket = tickets.get(ticketId as string);
    if (!ticket) {
      throw new Error(`no ticket with id '${ticketId}'`);
    }
    return {
      contents: [
        {
          uri: uri.href,
          text: `${ticket.id} [${ticket.priority}] ${ticket.title} - ${ticket.status}`,
        },
      ],
    };
  }
);
 
server.resource("open-tickets", "tickets://open", async (uri) => {
  const openIds = [...tickets.values()].filter((t) => t.status === "open").map((t) => t.id);
  return { contents: [{ uri: uri.href, text: openIds.join("\n") || "no open tickets" }] };
});
 
await server.connect(new StdioServerTransport());

What this demonstrates:

• Two tools, create_ticket and close_ticket, with Zod schemas that enforce both the type and the allowed values of priority.
• A parameterized resource, tickets://{ticketId}, next to a fixed resource, tickets://open, mirroring the two resource styles from the Python example.
• Thrown Error objects used for validation failures, converted by the SDK into structured error responses.
• The tool's return shape, { content: [...] }, which is the TypeScript SDK's structured result format.

Deep Dive

How It Works

• new McpServer({ name, version }) creates a server instance and wires up the connection and negotiation stages for you, identically to FastMCP in Python.
• server.tool(name, schema, handler) registers a tool under name, using the Zod schema object to build the JSON schema sent to clients during negotiation.
• server.resource(name, uriTemplate, handler) registers a resource; a {placeholder} segment in the URI template is passed to the handler as a parameter.
• The SDK validates incoming tool arguments against the Zod schema before invoking your handler, so malformed input never reaches your code.
• server.connect(transport) starts the server against a chosen transport, StdioServerTransport for local development, an HTTP-based transport for remote deployment.

Error Handling

Throwing a standard Error inside a handler is the correct way to signal failure.

server.tool("divide", { a: z.number(), b: z.number() }, async ({ a, b }) => {
  if (b === 0) {
    throw new Error("cannot divide by zero");
  }
  return { content: [{ type: "text", text: String(a / b) }] };
});

The SDK catches the thrown error and returns a structured error result to the client instead of crashing the process.

Avoid returning a success-shaped result with an error message embedded in the text, the client has no reliable way to distinguish that from a real result.

Tools vs Resources at a Glance

TypeScript Notes

// Zod schemas double as compile-time types via z.infer.
const CreateTicketInput = z.object({
  title: z.string(),
  priority: z.enum(["low", "normal", "high"]).default("normal"),
});
type CreateTicketInput = z.infer<typeof CreateTicketInput>;

Defining the schema once with Zod and deriving the TypeScript type from it keeps the runtime validation and the compile-time type in sync, so a schema change can't silently drift from the type your handler expects.

Parameters & Return Values

Gotchas

• Using a loose Zod type like z.string() for an enum-like value. This lets invalid values like priority: "urgent" through without a schema-level rejection. Fix: use z.enum([...]) for any argument with a fixed set of valid values.
• Returning a plain string from a tool handler instead of the content shape. The SDK expects { content: [...] }, not a bare string. Fix: always wrap the result in the structured content array, even for a simple text response.
• Forgetting await on server.connect(...). The process can exit before the transport finishes attaching, making the server look like it silently does nothing. Fix: always await server.connect(transport) at the top level.
• Mutating a module-level Map without guarding for concurrent sessions. Under HTTP/SSE with multiple clients, overlapping tool calls can race on shared in-memory state. Fix: back real state with a database once you move past local prototyping.
• Naming a tool something generic like run or execute. Vague names give Claude little signal about what the tool actually does, especially once a server has several tools. Fix: name tools after the specific action they perform, create_ticket not run.
• Skipping .min() or format validation on string inputs. An empty title string passes a bare z.string() check and can silently create malformed records. Fix: add the specific Zod refinements (.min(1), .email(), etc.) the field actually needs.

Alternatives

FAQs

server.tool("risky", { n: z.number() }, async ({ n }) => {
  if (n < 0) throw new Error("n must be non-negative");
  return { content: [{ type: "text", text: String(n) }] };
});

Related

• MCP Server Basics - the minimal skeleton this article builds on
• Building an MCP Server with the Python SDK - the same patterns in Python
• How MCP Servers Handle Requests - the lifecycle these handlers plug into
• Testing MCP Servers Before Deployment - exercising these handlers with a mock client
• stdio vs HTTP/SSE MCP Deployment Comparison - choosing a transport beyond local development

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the current Model Context Protocol Python/TypeScript SDKs. Model names, SDK versions, and the MCP spec move quickly - verify current specifics at platform.claude.com/docs and modelcontextprotocol.io before relying on them.