How to cache your MCP server's tool list (ttlMs and cacheScope, 2026-07-28 spec)

// server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
  ListToolsRequestSchema,
  CallToolRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const TOOLS = [
  {
    name: "get_order",
    description: "Look up an order by id.",
    inputSchema: {
      type: "object",
      properties: { id: { type: "string" } },
      required: ["id"],
    },
  },
];

export function makeServer() {
  const server = new Server(
    { name: "orders", version: "1.0.0" },
    { capabilities: { tools: {} } },
  );

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS,
    // SEP-2549 cache hints. Borrowed from HTTP Cache-Control.
    // Supplements listChanged; it does not replace it.
    ttlMs: 60_000,       // clients may reuse this list for 60s
    cacheScope: "public" // a shared gateway may cache it too
  }));

  server.setRequestHandler(CallToolRequestSchema, async (req) => ({
    content: [{ type: "text", text: `order ${req.params.arguments?.id}` }],
  }));

  return server;
}

// cachingClient.ts
// Wraps an MCP Client so tools/list honors SEP-2549 ttlMs.
// Inside the TTL window the cached list is returned and NO request
// hits the server.
export class ToolListCache {
  private cache: { tools: unknown[]; cacheScope: string; expiresAt: number } | null = null;
  networkCalls = 0;

  constructor(
    private client: { listTools(): Promise<any> },
    private now: () => number = () => Date.now(),
  ) {}

  async listTools() {
    if (this.cache && this.now() < this.cache.expiresAt) {
      return { tools: this.cache.tools, fromCache: true };
    }
    this.networkCalls++;
    const res = await this.client.listTools();
    const ttlMs = typeof res.ttlMs === "number" ? res.ttlMs : 0;
    this.cache = {
      tools: res.tools,
      cacheScope: res.cacheScope ?? "private",
      expiresAt: this.now() + ttlMs,
    };
    return { tools: res.tools, fromCache: false, ttlMs, cacheScope: res.cacheScope };
  }

  // A tools/list_changed notification must invalidate the cache
  // immediately, regardless of remaining TTL.
  invalidate() {
    this.cache = null;
  }
}

// ttl-cache.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { makeServer } from "./server.js";
import { ToolListCache } from "./cachingClient.js";

async function connect() {
  const [ct, st] = InMemoryTransport.createLinkedPair();
  const server = makeServer();
  const client = new Client({ name: "test", version: "1.0.0" }, { capabilities: {} });
  await Promise.all([server.connect(st), client.connect(ct)]);
  return client;
}

test("tools/list carries ttlMs + cacheScope over the wire", async () => {
  const client = await connect();
  const res = await client.listTools();
  assert.equal(res.ttlMs, 60_000);
  assert.equal(res.cacheScope, "public");
});

test("client serves from cache within TTL, zero extra network calls", async () => {
  const client = await connect();
  let clock = 1_000;
  const cache = new ToolListCache(client, () => clock);
  await cache.listTools();                       // networkCalls -> 1
  clock += 59_000;                               // still inside 60s
  const second = await cache.listTools();
  assert.equal(second.fromCache, true);
  assert.equal(cache.networkCalls, 1);           // no second request
});

test("cache re-fetches after ttlMs expires", async () => {
  const client = await connect();
  let clock = 1_000;
  const cache = new ToolListCache(client, () => clock);
  await cache.listTools();
  clock += 61_000;                               // past the window
  const third = await cache.listTools();
  assert.equal(third.fromCache, false);
  assert.equal(cache.networkCalls, 2);
});

test("listChanged invalidates immediately, even mid-TTL", async () => {
  const client = await connect();
  let clock = 1_000;
  const cache = new ToolListCache(client, () => clock);
  await cache.listTools();
  cache.invalidate();                            // simulate list_changed
  const after = await cache.listTools();
  assert.equal(after.fromCache, false);
  assert.equal(cache.networkCalls, 2);
});