How to build a Node.js MCP server for your existing API

mkdir orders-mcp-server && cd orders-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "start:http": "node dist/http.js"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

const BASE_URL = process.env.ORDERS_API_URL ?? "http://localhost:4000";
const API_KEY = process.env.ORDERS_API_KEY ?? "dev-key";

export class ApiError extends Error {
  constructor(
    public status: number,
    message: string,
  ) {
    super(message);
  }
}

type Options = { method?: "GET" | "POST"; retries?: number };

// One place that talks to the existing API: auth header, timeout, and a
// retry for reads only. Writes are never retried automatically.
export async function api<T>(
  path: string,
  { method = "GET", retries = 0 }: Options = {},
): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    try {
      const res = await fetch(`${BASE_URL}${path}`, {
        method,
        headers: { authorization: `Bearer ${API_KEY}` },
        signal: AbortSignal.timeout(8000),
      });
      const body = (await res.json().catch(() => ({}))) as { error?: string };
      if (!res.ok) {
        if (res.status >= 500 && attempt < retries) continue;
        throw new ApiError(res.status, body.error ?? `HTTP ${res.status}`);
      }
      return body as T;
    } catch (err) {
      if (err instanceof ApiError) throw err;
      if (attempt < retries) continue; // network error or timeout
      throw new ApiError(0, "The orders API did not respond in time.");
    }
  }
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { api, ApiError } from "./api.js";

type Order = {
  id: string;
  status: string;
  customerEmail: string;
  totalCents: number;
  items: string[];
};

const orderId = z
  .string()
  .regex(/^ord_[a-z0-9]{6,}$/, "Order IDs look like ord_1a2b3c");

// Tool results are text the model reads. Keep them short and structured.
const ok = (data: unknown) => ({
  content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
});

// Errors go back as a result with isError, not a thrown exception, so the
// model can read the reason and recover or explain it to the user.
const fail = (err: unknown) => ({
  isError: true,
  content: [
    {
      type: "text" as const,
      text: err instanceof ApiError ? err.message : "Unexpected error.",
    },
  ],
});

// Never write to stdout in a stdio server: it carries the protocol itself.
const log = (...args: unknown[]) => console.error("[orders-mcp]", ...args);

// One function builds the server with all its tools, so the same tools can be
// served over stdio (server.ts) or over HTTP (http.ts).
export function buildServer(): McpServer {
  const server = new McpServer({ name: "orders", version: "1.0.0" });

  server.registerTool(
    "get_order",
    {
      title: "Get order",
      description:
        "Look up one order by its ID and return its status, items and total in cents. Use list_orders if you do not have the ID.",
      inputSchema: { orderId },
      annotations: { readOnlyHint: true },
    },
    async ({ orderId }) => {
      log("get_order", orderId);
      try {
        return ok(await api<Order>(`/orders/${orderId}`, { retries: 1 }));
      } catch (err) {
        return fail(err);
      }
    },
  );

  server.registerTool(
    "list_orders",
    {
      title: "List orders",
      description: "List orders, optionally filtered by status.",
      inputSchema: {
        status: z
          .enum(["processing", "shipped", "delivered", "cancelled"])
          .optional()
          .describe("Only return orders with this status"),
      },
      annotations: { readOnlyHint: true },
    },
    async ({ status }) => {
      log("list_orders", status ?? "all");
      try {
        const query = status ? `?status=${status}` : "";
        return ok(await api<{ orders: Order[] }>(`/orders${query}`, { retries: 1 }));
      } catch (err) {
        return fail(err);
      }
    },
  );

  // The only write action. It needs an explicit confirm flag, and the API itself
  // refuses to cancel anything that has already shipped.
  server.registerTool(
    "cancel_order",
    {
      title: "Cancel order",
      description:
        "Cancel an order that is still processing. This cannot be undone. Ask the user to confirm first, then call with confirm set to true.",
      inputSchema: {
        orderId,
        confirm: z
          .literal(true)
          .describe("Must be true; set it only after the user agrees"),
      },
      annotations: {
        readOnlyHint: false,
        destructiveHint: true,
        idempotentHint: false,
      },
    },
    async ({ orderId }) => {
      log("cancel_order", orderId);
      try {
        return ok(
          await api<Order>(`/orders/${orderId}/cancel`, { method: "POST" }),
        );
      } catch (err) {
        return fail(err);
      }
    },
  );

  return server;
}

// Local use: Claude Desktop, Cursor or Claude Code start this file and talk to
// it over stdin/stdout.
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { buildServer } from "./tools.js";

await buildServer().connect(new StdioServerTransport());
console.error("[orders-mcp] ready");

// Starts the mock API and the built server, then calls each tool like a client would.
import { spawn } from "node:child_process";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const mock = spawn(process.execPath, ["--import", "tsx", "src/mock-api.ts"], {
  stdio: "inherit",
});
await new Promise((resolve) => setTimeout(resolve, 1000));

const client = new Client({ name: "smoke-test", version: "1.0.0" });
await client.connect(
  new StdioClientTransport({
    command: process.execPath,
    args: ["dist/server.js"],
  }),
);

function show(label: string, result: unknown) {
  console.log(`\n== ${label}\n${JSON.stringify(result, null, 1)}`);
}
async function call(name: string, args: Record<string, unknown>) {
  try {
    return await client.callTool({ name, arguments: args });
  } catch (err) {
    return { rejected: (err as Error).message };
  }
}

show("tools", (await client.listTools()).tools.map((t) => t.name));
show("get_order", await call("get_order", { orderId: "ord_1a2b3c" }));
show("list_orders shipped", await call("list_orders", { status: "shipped" }));
show("bad id", await call("get_order", { orderId: "nope" }));
show("cancel without confirm", await call("cancel_order", { orderId: "ord_1a2b3c" }));
show("cancel shipped", await call("cancel_order", { orderId: "ord_4d5e6f", confirm: true }));
show("cancel processing", await call("cancel_order", { orderId: "ord_1a2b3c", confirm: true }));

await client.close();
mock.kill();

npm run build && npx tsx src/smoke-test.ts

tools: get_order, list_orders, cancel_order

get_order ord_1a2b3c            -> status: processing
get_order "nope"                -> isError: Order IDs look like ord_1a2b3c at orderId
cancel_order (no confirm)       -> isError: Invalid input: expected true at confirm
cancel_order ord_4d5e6f         -> isError: cannot cancel an order that is shipped
cancel_order ord_1a2b3c, true   -> status: cancelled

{
  "mcpServers": {
    "orders": {
      "command": "node",
      "args": ["/absolute/path/to/orders-mcp-server/dist/server.js"],
      "env": {
        "ORDERS_API_URL": "https://api.example.com",
        "ORDERS_API_KEY": "your-key-here"
      }
    }
  }
}

claude mcp add orders -e ORDERS_API_URL=https://api.example.com -e ORDERS_API_KEY=your-key-here -- node /absolute/path/to/orders-mcp-server/dist/server.js

// Remote use: the same tools over HTTP, using the SDK's Streamable HTTP
// transport with Node's built-in http module (no framework needed).
import { createServer } from "node:http";
import { timingSafeEqual } from "node:crypto";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { buildServer } from "./tools.js";

const PORT = Number(process.env.PORT ?? 3333);
const TOKEN = process.env.MCP_TOKEN ?? "";
if (!TOKEN) throw new Error("Set MCP_TOKEN before exposing this server");

// A shared bearer token is enough for one team. For many users, use OAuth so
// each person's assistant acts with that person's own permissions.
function authorized(header: string | undefined): boolean {
  const given = Buffer.from(header ?? "");
  const expected = Buffer.from(`Bearer ${TOKEN}`);
  return given.length === expected.length && timingSafeEqual(given, expected);
}

createServer(async (req, res) => {
  if (req.url !== "/mcp") {
    res.writeHead(404).end();
    return;
  }
  if (!authorized(req.headers.authorization)) {
    res.writeHead(401, { "content-type": "application/json" }).end('{"error":"unauthorized"}');
    return;
  }

  // Stateless mode: a fresh server and transport per request, so any
  // instance behind a load balancer can answer.
  const server = buildServer();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => {
    transport.close();
    server.close();
  });
  await server.connect(transport);
  await transport.handleRequest(req, res);
}).listen(PORT, () => console.error(`[orders-mcp] http://localhost:${PORT}/mcp`));

[orders-mcp] http://localhost:3333/mcp
without token: 401
tools: get_order, list_orders, cancel_order
get_order: processing