Rebuilding a Remote MCP Server That Never Needed Mcp-Session-Id

Moving it to a shared store does not save you

When the audit lights up, the first fix that comes to mind is usually the same one: move the in-memory map into Redis. I reached for that too.

This is where my expectation was exactly backwards.

// shared-store-check.mjs
const shared = new Map();                   // stands in for Redis
function makeInstance() {
  return { listItems(sessionId) {
    if (!sessionId) { const e = new Error("no session id in request"); e.code = 400; throw e; }
    if (!shared.has(sessionId)) shared.set(sessionId, 0);
    const off = shared.get(sessionId);
    shared.set(sessionId, off + 20);
    return off;
  }};
}

A shared store solves exactly one problem: any instance can read the same state. What the spec removes is the key you use to look that state up. Here is what I measured:

The third row is the dangerous one. Not a single error. Your error-rate dashboard stays flat, and all 200 tool calls report success. The only difference is that every response is the same first page.

The agent keeps working, cheerfully consuming the same twenty items over and over. Meanwhile the shared store accumulated 201 entries that will never be read again, so memory grows without a ceiling.

A 500 would have been far kinder. For detecting failures that never raise, the "measure something other than error rate" approach I described in observing Claude Code with OpenTelemetry applies directly here.

Sorting state into three boxes

Once you accept that the key is gone, the question stops being "where do I move this state" and becomes "who should have owned it." I ended up with three boxes.

State you can simply drop

Transport instances, per-request log buffers, client info captured at initialize. Nothing here needs to survive a call boundary.

Most of my transports map fell into this box. Creating and discarding the transport per request also deleted the cleanup logic that hung off onsessionclosed. This is the cheapest part of the migration, and you can do it before the header goes away.

State you hand back to the client

Pagination offsets, active filters, intermediate progress in a multi-step flow. Anything that exists so the next call can resume.

None of it belongs on the server. Emit it as an opaque token in the tool result and take it back as an argument. MCP already expresses pagination as a cursor / nextCursor round trip, so this stays inside the existing convention.

State keyed by a domain identifier

Draft posts, in-progress uploads, pending approvals. Losing these when a connection drops is a real bug.

A shared store is the right answer here, but the key must not be a session ID. Rekey to something like draft:{userId}:{draftId}. Once I did that, work survived disconnects, and I got a "resume the thing that died halfway" path almost for free.

Implementing the signed cursor

Box two is where the real work is. Since the client now carries the state, design for tampering from the start.

// cursor.mjs
import crypto from "node:crypto";
 
const CURSOR_SECRET = Buffer.from(process.env.MCP_CURSOR_SECRET ?? "", "base64");
if (CURSOR_SECRET.length < 32) {
  // Fail at boot. Every instance must receive the identical value.
  throw new Error("MCP_CURSOR_SECRET must be >=32 bytes (base64)");
}
const CURSOR_VERSION = 1;
const CURSOR_TTL_SEC = 900;
 
export function encodeCursor(state) {
  const payload = { v: CURSOR_VERSION, exp: Math.floor(Date.now() / 1000) + CURSOR_TTL_SEC, ...state };
  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
  const mac = crypto.createHmac("sha256", CURSOR_SECRET).update(body).digest("base64url");
  return `${body}.${mac}`;
}
 
export class CursorError extends Error {
  constructor(reason) {
    super(`invalid cursor: ${reason}`);
    this.code = -32602;      // aligns with JSON-RPC Invalid params
    this.reason = reason;
  }
}
 
export function decodeCursor(token) {
  if (typeof token !== "string" || token.length > 4096) throw new CursorError("malformed");
  const dot = token.indexOf(".");
  if (dot <= 0) throw new CursorError("malformed");
  const body = token.slice(0, dot), mac = token.slice(dot + 1);
  const expected = crypto.createHmac("sha256", CURSOR_SECRET).update(body).digest("base64url");
  const a = Buffer.from(mac), b = Buffer.from(expected);
  // Check length first, or timingSafeEqual throws instead of returning false
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) throw new CursorError("signature");
  let payload;
  try { payload = JSON.parse(Buffer.from(body, "base64url").toString("utf8")); }
  catch { throw new CursorError("payload"); }
  if (payload.v !== CURSOR_VERSION) throw new CursorError(`version ${payload.v}`);
  if (typeof payload.exp !== "number" || payload.exp < Math.floor(Date.now() / 1000)) {
    throw new CursorError("expired");
  }
  return payload;
}

What I verified locally:

Sign plus verify is roughly 9us. Against a tool call that hits an external API in, say, 20ms, that is under 0.05% of the round trip. I had been quietly worried about the cost of going stateless; the measurement was off by orders of magnitude from my worry.

A few judgement calls worth spelling out.

Failing at boot when the secret is missing is deliberately harsh. If one instance in the pool never received the key, only the calls that land on that instance return "invalid cursor" — the same probabilistic failure mode as row three of the earlier table, and the hardest kind to chase. Refusing to start surfaces it in seconds.

I set exp to 15 minutes because most agent workflows I run finish inside that window. A server handling long research tasks might reasonably stretch it. I would not recommend removing the expiry entirely.

Signing rather than encrypting is also intentional. Only put values in the cursor that you would not mind the client reading. The moment something sensitive wants to go in there, that state belongs in box three, not box two.

Exposing the cursor in the tool definition

Server-side work is only half of it. If the schema does not mention the cursor, the model has no way to know it may send one back.

server.registerTool("list_articles", {
  description: "Lists articles newest first. To continue, pass the nextCursor from the previous response as cursor.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Optional search term" },
      cursor: {
        type: "string",
        description: "Pass the previous response's nextCursor verbatim. Do not edit its contents.",
      },
    },
  },
}, async ({ query, cursor }) => {
  let state = { off: 0, q: query ?? "" };
  if (cursor) {
    try {
      state = decodeCursor(cursor);
    } catch (e) {
      // Telling the model how to recover beats raising: it retries correctly next turn
      return {
        isError: true,
        content: [{ type: "text", text: `Cursor is invalid (${e.reason}). Call again without cursor to start over.` }],
      };
    }
  }
  const page = await fetchArticles(state.q, state.off, 20);
  const next = page.length === 20 ? encodeCursor({ off: state.off + 20, q: state.q }) : null;
  return {
    content: [{ type: "text", text: JSON.stringify({ items: page, nextCursor: next }) }],
  };
});

The "do not edit its contents" line exists because models do try to construct cursors by guessing at the format. Saying the token is opaque, in words, cut down those attempts noticeably.

Returning isError rather than throwing comes from the same place. An expired cursor is not an exception; it is a state you recover from by starting over. Put the recovery instruction in the message and the model finds its way back on the next turn.

The order I migrated in

I did not flip everything at once. This sequence leaves a rollback point at each step.

1. Add the audit script to CI and record today's score. Capture the number before you start lowering it, so later steps have something to compare against.
2. Clear out box one. Make transports disposable and delete the onsessionclosed cleanup. Behaviour is unchanged, so this can ship early and safely.
3. Add the cursor path alongside the old one. If cursor arrives, use the new logic; if not, fall back. This is your dual-support window.
4. Scale to two instances and run the reproduction harness against a production-like setup. Only after failures read zero should sticky sessions come off.
5. Confirm the audit score is zero, then delete the session-resident path and the header reads.

Step four carries the weight. If you drop the sticky setting before validating a two-instance topology, the cutover itself becomes your first real test. Doing it in advance meant that on the day, I changed exactly one line of configuration.

Removing the load balancer setting comes last on purpose. Leaving it in place while it goes unused is safer than removing it and needing it back.

Make it countable, then move it

The part that helped most was not rewriting the code. It was turning the failure into a number before touching anything.

Having "0% at one instance, 50% at two" on the table in front of me meant I never trusted a green test suite. The audit score plays the same role at the other end: it tells you the migration is finished with a number rather than a feeling.

If you do one thing, point the audit script at your own MCP server and record the score. Zero means 28 July is a non-event for you. Anything else, and you already know which box each piece of state belongs in.

The specification is still a release candidate, so please verify against the primary source before you write the migration. I hope the measurements save you an evening.