How to use the streamable HTTP transport for MCP

1# For Express
2npm install @modelcontextprotocol/sdk express zod
3npm install -D @types/express typescript
4
5# For Hono
6npm install @modelcontextprotocol/sdk hono zod
7npm install -D typescript

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
3import { z } from "zod";
4
5const server = new McpServer({
6  name: "streamable-http-demo",
7  version: "1.0.0",
8});
9
10server.tool(
11  "get-weather",
12  "Get current weather for a city",
13  { city: z.string() },
14  async ({ city }) => ({
15    content: [{ type: "text", text: `Weather in ${city}: 22°C, sunny` }],
16  })
17);
18
19const app = createMcpExpressApp(server);
20
21app.listen(3000, () => {
22  console.error("Streamable HTTP MCP server on http://localhost:3000/mcp");
23});

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2import { createMcpHonoApp } from "@modelcontextprotocol/sdk/server/hono.js";
3import { serve } from "@hono/node-server";
4import { z } from "zod";
5
6const server = new McpServer({
7  name: "hono-mcp-server",
8  version: "1.0.0",
9});
10
11server.tool(
12  "ping",
13  "Check if the server is alive",
14  {},
15  async () => ({
16    content: [{ type: "text", text: "pong" }],
17  })
18);
19
20const app = createMcpHonoApp(server);
21
22serve({ fetch: app.fetch, port: 3000 }, () => {
23  console.error("Hono MCP server running on port 3000");
24});

1// Session lifecycle:
2// 1. Client sends POST /mcp with {"method": "initialize"}
3// 2. Server responds with Mcp-Session-Id: abc123 header
4// 3. Client includes Mcp-Session-Id: abc123 in all future requests
5// 4. Client sends DELETE /mcp with Mcp-Session-Id to end session
6
7// The SDK handles all of this automatically.
8// To inspect sessions for debugging, you can add middleware:
9
10import express from "express";
11const debugApp = express();
12
13debugApp.use((req, _res, next) => {
14  console.error(`[${req.method}] ${req.path}`);
15  console.error(`  Session: ${req.headers["mcp-session-id"] || "new"}`);
16  next();
17});

1import express from "express";
2
3const ALLOWED_ORIGINS = [
4  "https://claude.ai",
5  "https://your-app.com",
6];
7
8function originValidation(
9  req: express.Request,
10  res: express.Response,
11  next: express.NextFunction
12) {
13  const origin = req.headers.origin;
14  if (origin && !ALLOWED_ORIGINS.includes(origin)) {
15    res.status(403).json({ error: "Origin not allowed" });
16    return;
17  }
18  next();
19}
20
21// Apply before MCP routes
22app.use("/mcp", originValidation);

1# Start your server
2node dist/http.js
3
4# In another terminal, run MCP Inspector
5npx -y @modelcontextprotocol/inspector --transport http --url http://localhost:3000/mcp
6
7# Then configure your host:
8# .cursor/mcp.json
9{
10  "mcpServers": {
11    "my-http-server": {
12      "url": "http://localhost:3000/mcp"
13    }
14  }
15}