How to route MCP requests with Mcp-Method and Mcp-Name headers

// gateway.ts
// A gateway, load balancer, or rate limiter that acts on MCP traffic using
// ONLY the HTTP headers. It never parses the JSON-RPC body. That is the whole
// point of SEP-2243: the method and the target name ride in Mcp-Method and
// Mcp-Name, so infrastructure routes and throttles without deep packet
// inspection.

type RouteDecision =
  | { action: "forward"; pool: string }
  | { action: "reject"; status: number; reason: string };

export function makeGateway(opts: { limits?: Record<string, number> } = {}) {
  const limits = opts.limits ?? {};
  const counts = new Map<string, number>(); // tool name -> calls this window

  // `route` is deliberately given only the headers, never the body, to prove
  // no body parsing happens.
  return function route(headers: Record<string, string>): RouteDecision {
    const method = headers["mcp-method"];
    const name = headers["mcp-name"];

    // 1. Route by method. Reads go to replicas, everything else to primary.
    const pool =
      method === "resources/read" || method === "resources/list"
        ? "read-replicas"
        : "primary";

    // 2. Rate-limit a specific tool by name, header-only. A gateway can shed
    // load on expensive_report without knowing anything else in the payload.
    if (method === "tools/call" && name && name in limits) {
      const n = (counts.get(name) ?? 0) + 1;
      counts.set(name, n);
      if (n > limits[name]) {
        return { action: "reject", status: 429, reason: `rate limit exceeded for ${name}` };
      }
    }

    return { action: "forward", pool };
  };
}

// client.ts
// Attaches the SEP-2243 routing headers to every Streamable HTTP POST.
// Mcp-Method rides on every request. Mcp-Name rides on requests that name a
// tool, resource, or prompt. x-mcp-header lifts a chosen tool argument into a
// custom header so infrastructure can route on it too.

type JsonRpc = {
  jsonrpc: "2.0";
  id: number | string;
  method: string;
  params?: { name?: string; arguments?: Record<string, unknown> };
};

export function buildRequest(
  rpc: JsonRpc,
  opts: { headerParams?: Record<string, string> } = {},
) {
  const headers: Record<string, string> = {
    "content-type": "application/json",
    "mcp-method": rpc.method, // required on every POST
  };

  const name = rpc.params?.name;
  if (name) headers["mcp-name"] = name; // only when a target is named

  // x-mcp-header: promote declared tool arguments into custom headers so a
  // gateway can route on them (for example, a tenant or region).
  for (const [arg, headerName] of Object.entries(opts.headerParams ?? {})) {
    const value = rpc.params?.arguments?.[arg];
    if (value !== undefined) headers[headerName] = String(value);
  }

  return { headers, body: JSON.stringify(rpc) };
}

// server.ts
// A stateless MCP request handler that trusts the SEP-2243 routing headers
// only after it has proven they agree with the JSON-RPC body.
// On disagreement it returns HeaderMismatchError (-32020), the code the
// 2026-07-28 spec assigns to this case.

export const HEADER_MISMATCH = -32020; // HeaderMismatchError (SEP-2243)
export const METHOD_NOT_FOUND = -32601;
export const INVALID_PARAMS = -32602;

type JsonRpc = {
  jsonrpc: "2.0";
  id: number | string;
  method: string;
  params?: { name?: string; arguments?: Record<string, unknown> };
};

const TOOLS: Record<string, (args: Record<string, unknown>) => unknown> = {
  get_order_status: (args) => ({ orderId: args.id, status: "shipped" }),
  expensive_report: (args) => ({ report: `report for ${args.region}`, rows: 10_000 }),
};

export function handleMcpRequest(headers: Record<string, string>, body: JsonRpc) {
  const headerMethod = headers["mcp-method"];
  const headerName = headers["mcp-name"];
  const { id, method, params } = body;

  // The contract that makes header-only routing safe: the server rejects any
  // request whose headers lie about the body. A gateway can then act on the
  // header alone, because the server guarantees the header matches the body.
  if (headerMethod !== method) {
    return err(id, HEADER_MISMATCH, `Mcp-Method "${headerMethod}" != body method "${method}"`);
  }
  const bodyName = params?.name;
  if (bodyName !== undefined && headerName !== bodyName) {
    return err(id, HEADER_MISMATCH, `Mcp-Name "${headerName}" != body params.name "${bodyName}"`);
  }

  if (method === "tools/call") {
    const fn = TOOLS[params?.name as string];
    if (!fn) return err(id, INVALID_PARAMS, `unknown tool ${params?.name}`);
    return { jsonrpc: "2.0", id, result: { structuredContent: fn(params?.arguments ?? {}) } };
  }
  return err(id, METHOD_NOT_FOUND, `method not found: ${method}`);
}

function err(id: number | string, code: number, message: string) {
  return { jsonrpc: "2.0", id, error: { code, message } };
}

// routing.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { handleMcpRequest, HEADER_MISMATCH } from "./server.ts";
import { makeGateway } from "./gateway.ts";
import { buildRequest } from "./client.ts";

test("client attaches Mcp-Method on every request and Mcp-Name when a tool is named", () => {
  const { headers } = buildRequest({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: { name: "get_order_status", arguments: { id: "A-1" } },
  });
  assert.equal(headers["mcp-method"], "tools/call");
  assert.equal(headers["mcp-name"], "get_order_status");
});

test("a request with no named target carries Mcp-Method but no Mcp-Name", () => {
  const { headers } = buildRequest({ jsonrpc: "2.0", id: 2, method: "tools/list" });
  assert.equal(headers["mcp-method"], "tools/list");
  assert.equal(headers["mcp-name"], undefined);
});

test("gateway routes by method using headers only, never the body", () => {
  const route = makeGateway();
  // Note: route() is only ever handed headers. There is no body in scope.
  assert.deepEqual(route({ "mcp-method": "resources/read", "mcp-name": "file://x" }), {
    action: "forward",
    pool: "read-replicas",
  });
  assert.deepEqual(route({ "mcp-method": "tools/call", "mcp-name": "get_order_status" }), {
    action: "forward",
    pool: "primary",
  });
});

test("gateway rate-limits a tool by header name alone", () => {
  const route = makeGateway({ limits: { expensive_report: 2 } });
  const h = { "mcp-method": "tools/call", "mcp-name": "expensive_report" };
  assert.equal(route(h).action, "forward"); // 1
  assert.equal(route(h).action, "forward"); // 2
  const third = route(h); // 3 -> over the limit
  assert.equal(third.action, "reject");
  assert.equal((third as { status: number }).status, 429);
});

test("x-mcp-header promotes a tool argument into a custom routing header", () => {
  const { headers } = buildRequest(
    {
      jsonrpc: "2.0",
      id: 3,
      method: "tools/call",
      params: { name: "expensive_report", arguments: { region: "eu-west-1" } },
    },
    { headerParams: { region: "x-mcp-header-region" } },
  );
  assert.equal(headers["x-mcp-header-region"], "eu-west-1");
});

test("server rejects a Mcp-Method that disagrees with the body (-32020)", () => {
  const res = handleMcpRequest(
    { "mcp-method": "resources/read", "mcp-name": "get_order_status" }, // header lies
    { jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: "get_order_status" } },
  );
  assert.equal((res as any).error.code, HEADER_MISMATCH);
});

test("server rejects a Mcp-Name that disagrees with the body (-32020)", () => {
  const res = handleMcpRequest(
    { "mcp-method": "tools/call", "mcp-name": "delete_everything" }, // name lies
    { jsonrpc: "2.0", id: 5, method: "tools/call", params: { name: "get_order_status" } },
  );
  assert.equal((res as any).error.code, HEADER_MISMATCH);
});

test("server dispatches when headers and body agree (client -> gateway -> server)", () => {
  const rpc = {
    jsonrpc: "2.0" as const,
    id: 6,
    method: "tools/call",
    params: { name: "get_order_status", arguments: { id: "A-42" } },
  };
  const { headers, body } = buildRequest(rpc);
  const decision = makeGateway()(headers);
  assert.equal(decision.action, "forward");
  const res = handleMcpRequest(headers, JSON.parse(body));
  assert.deepEqual((res as any).result.structuredContent, { orderId: "A-42", status: "shipped" });
});