typescript-mcp

MCP TypeScript SDK

MCP TypeScript SDK implements the full Model Context Protocol specification, allowing you to build MCP servers and clients using TypeScript.

Installation

npm install @modelcontextprotocol/sdk --save
# or
yarn add @modelcontextprotocol/sdk

Quickstart: Create an MCP Server

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: "DemoServer", version: "1.0.0" });

// Define a simple addition tool
type AddParams = { a: number; b: number };
server.tool(
  "add",
  { a: z.number(), b: z.number() },
  async ({ a, b }: AddParams) => ({ content: [{ type: "text", text: `${a + b}` }] })
);

// Start listening on stdin/stdout transport
await server.connect(new StdioServerTransport());

Core Concepts

• McpServer: entry point for protocol compliance, message routing, and lifecycle management.
• Resources: read-only data endpoints via server.resource(name, template, handler) and ResourceTemplate.
• Tools: action endpoints via server.tool(name, schema, executor).
• Prompts: reusable message templates via server.prompt(name, schema, builder).
• Transports: connect servers/clients over stdio, HTTP, SSE, or Streamable HTTP (StdioServerTransport, StreamableHttpServerTransport, etc.).

Preferred Transport: Streamable HTTP

Streamable HTTP is the recommended transport for production environments, offering full-duplex streaming, session management, and backward compatibility over older SSE-based transports.

Streamable HTTP Server Example

import express from "express";
import { randomUUID } from "crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";

const app = express();
app.use(express.json());

const server = new McpServer({ name: "StreamableExample", version: "1.0.0" });
const transports: Record<string, StreamableHTTPServerTransport> = {};

app.post('/mcp', async (req, res) => {
  const sid = req.headers['mcp-session-id'] as string | undefined;
  let transport: StreamableHTTPServerTransport;

  if (sid && transports[sid]) {
    transport = transports[sid];
  } else if (!sid && isInitializeRequest(req.body)) {
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (sessionId) => (transports[sessionId] = transport)
    });
    transport.onclose = () => delete transports[transport.sessionId!];
  } else {
    res.status(400).send("Invalid request");
    return;
  }

  await server.connect(transport);
  transport.handleRequest(req, res);
});

const PORT = process.env.PORT ?? 3000;
app.listen(PORT, () => console.log(`MCP Streamable HTTP server listening on ${PORT}`));