Skip to content

MCP tool cache: invalidating server 'X' deletes the cached tools of an unrelated server named 'X:suffix' via the unscoped prefix-scan fallback #1976

Closed

Description

@BlueX888

Please read this first

Describe the bug

invalidateServerToolsCache in packages/agents-core/src/mcpToolCache.ts deletes the cached tools of an unrelated server when the unrelated server's name extends the invalidated name with a colon suffix. Invalidating docs can wipe the cached tools of a server named docs:extra.

Mechanism (packages/agents-core/src/mcpToolCache.ts:53-66 on current main):

  • The per-server key registry cachedMcpToolKeysByServer (filled at packages/agents-core/src/mcp.ts:707-710 whenever a server's tools are cached) exists precisely to scope deletion to the keys that server registered; the registry-hit branch deletes only those keys and returns.
  • When cachedMcpToolKeysByServer[serverName] is absent, the function falls through to a fallback that deletes cachedMcpTools[serverName] and then scans every key in cachedMcpTools and deletes each one starting with `${serverName}:`.
  • The default cache key is the server's own name (defaultMCPToolCacheKey, packages/agents-core/src/mcp.ts:599-605), so a server named db:readonly is cached under the key "db:readonly" — which starts with "db:". Invalidating db on the fallback path deletes db:readonly's cached tools, and its registry entry is left dangling (the early-return branch that cleans up the registry is skipped).

The fallback path is not exotic: the server shims call invalidateServerToolsCache for their own name on every connect() / close() / invalidateToolsCache(), so after a first invalidation has consumed the registry entry, every later invalidation of that same name takes the fallback path. An invalidation of a name that was never cached takes it directly.

The observable effect is over-invalidation: the unrelated server's next tool lookup cannot be served from cache and re-issues a tools/list RPC even though nothing about that server changed.

Debug information

  • Agents SDK version: current main @ 58844c7f (@openai/agents-core 0.18.0 source)
  • Does the issue reproduce with the latest Agents SDK release? Yes — the same unscoped prefix-scan fallback is present in tag v0.18.0
  • Runtime: Node.js via vitest 5.0.0; Operating system: macOS (darwin, arm64)
  • Occurs consistently (deterministic; no timing involved)

Repro steps

A self-contained test — drop it into packages/agents-core/test/zzrepro-mcp-cache.test.ts and run TEST_STDIO_MODE=off pnpm exec vitest run packages/agents-core/test/zzrepro-mcp-cache.test.ts:

import { beforeEach, describe, expect, it, vi } from 'vitest';
import { getAllMcpTools, invalidateServerToolsCache } from '../src/mcp';
import { NodeMCPServerStdio } from '../src/shims/mcp-server/node';
import type { CallToolResultContent, MCPTool } from '../src/mcp';
import { cachedMcpTools, cachedMcpToolKeysByServer } from '../src/mcpToolCache';

class StubServer extends NodeMCPServerStdio {
  public toolList: any[];
  constructor(name: string, tools: any[]) {
    super({ command: 'noop', name });
    this.toolList = tools;
    this.cacheToolsList = true;
  }
  async connect(): Promise<void> {}
  async close(): Promise<void> {}
  async listTools(): Promise<any[]> {
    if (this.cacheToolsList && !this._cacheDirty && this._toolsList) {
      return this._toolsList;
    }
    this._cacheDirty = false;
    this._toolsList = this.toolList;
    return this.toolList;
  }
  async callTool(): Promise<CallToolResultContent> {
    return [];
  }
}

function toolNamed(name: string): MCPTool {
  return {
    name,
    description: '',
    inputSchema: {
      type: 'object',
      properties: {},
      required: [],
      additionalProperties: false,
    },
  };
}

describe('invalidateServerToolsCache wipes an unrelated colon-suffixed server', () => {
  beforeEach(() => {
    for (const key of Object.keys(cachedMcpTools)) delete cachedMcpTools[key];
    for (const key of Object.keys(cachedMcpToolKeysByServer))
      delete cachedMcpToolKeysByServer[key];
  });

  it('cache-level: invalidating "docs" deletes the cached tools of "docs:extra"', async () => {
    const extra = new StubServer('docs:extra', [toolNamed('search')]);
    await getAllMcpTools({ mcpServers: [extra] });

    console.log('BEFORE invalidate("docs"): cachedMcpTools keys =',
      JSON.stringify(Object.keys(cachedMcpTools)));
    console.log('BEFORE invalidate("docs"): registry keySets    =',
      JSON.stringify(Object.keys(cachedMcpToolKeysByServer)));

    // e.g. a "docs" server's shim invalidates its name again after a first
    // invalidation already consumed the registry entry
    await invalidateServerToolsCache('docs');

    console.log('AFTER  invalidate("docs"): cachedMcpTools keys =',
      JSON.stringify(Object.keys(cachedMcpTools)));
    console.log('AFTER  invalidate("docs"): registry keySets    =',
      JSON.stringify(Object.keys(cachedMcpToolKeysByServer)));

    // an unrelated server must keep its cached tools
    expect(Object.keys(cachedMcpTools)).toContain('docs:extra');
  });

  it('e2e: invalidating "db" twice (shims re-invalidate on connect()/close()) makes "db:readonly" refetch', async () => {
    const db = new StubServer('db', [toolNamed('query')]);
    const dbReadonly = new StubServer('db:readonly', [toolNamed('read')]);
    const listCalls = vi.spyOn(dbReadonly, 'listTools');

    await getAllMcpTools({ mcpServers: [db, dbReadonly] });
    console.log('after first getAllMcpTools: db:readonly listTools calls =',
      listCalls.mock.calls.length);

    await invalidateServerToolsCache('db'); // first invalidation consumes the registry entry
    await invalidateServerToolsCache('db'); // every shim connect()/close() re-invalidates -> fallback path

    const tools = await getAllMcpTools({ mcpServers: [dbReadonly] });
    console.log('db:readonly tools after second invalidate("db"):',
      JSON.stringify(tools.map((t) => t.name)));
    console.log('db:readonly listTools calls =', listCalls.mock.calls.length);

    // cached tools should still serve without another tools/list RPC
    expect(listCalls).toHaveBeenCalledTimes(1);
  });
});

Actual output on main @ 58844c7f (both tests fail):

BEFORE invalidate("docs"): cachedMcpTools keys = ["docs:extra"]
BEFORE invalidate("docs"): registry keySets    = ["docs:extra"]
AFTER  invalidate("docs"): cachedMcpTools keys = []
AFTER  invalidate("docs"): registry keySets    = ["docs:extra"]

AssertionError: expected [] to include 'docs:extra'
 ❯ test/zzrepro-mcp-cache.test.ts:83:41

and

after first getAllMcpTools: db:readonly listTools calls = 1
db:readonly tools after second invalidate("db"): ["read"]
db:readonly listTools calls = 2

AssertionError: expected "listTools" to be called 1 times, but got 2 times
 ❯ test/zzrepro-mcp-cache.test.ts:108:23

The first block shows the cache entry for docs:extra deleted while its registry entry is left dangling; the second shows the unrelated db:readonly server being forced to re-issue a tools/list RPC after db alone was invalidated twice.

Expected behavior

Invalidating server X should only remove the cached tools that belong to server X — the keys it registered in cachedMcpToolKeysByServer, plus its own bare cachedMcpTools[serverName] entry. A server named X:suffix is a different server (different server.name) and its cache must be untouched; on the registry-miss path the function should not run the unscoped ${serverName}: prefix scan at all, since every cached key is registered under its own server's name at write time (packages/agents-core/src/mcp.ts:707-710).

This is in line with the repository's own history of treating mis-scoped MCP tool caches as bugs (#695, #1605, #1681, #1727).

I have a fix on a branch of my fork (BlueX888/openai-agents-js @ fix/prep-mcp-cross-server-cache-wipe, commit 93a33957): when the registry entry is absent, delete only cachedMcpTools[serverName] and drop the prefix scan, with a regression test in packages/agents-core/test/mcpCache.test.ts (colon-prefixed pair, double invalidation, asserts the suffixed server still serves from cache). Verified with pnpm exec vitest run packages/agents-core/test/mcpCache.test.ts (69 passed) and the full pnpm test (228 test files, 6960 passed / 3 skipped). Since pull requests are limited to collaborators, I am not opening one — maintainers are welcome to take the branch from the fork if useful, or I can rework it to preference.

Activity

  1. BlueX888 commented on Sep 24, 2026

    @BlueX888
    ContributorAuthor

    Reproduced this. Root cause: packages/agents-core/src/mcpToolCache.ts:63 fallback scans all cache keys and deletes every key starting with , wiping unrelated servers named X:suffix when the registry entry is absent

    Minimal reproduction:

    TEST_STDIO_MODE=off pnpm exec vitest run packages/agents-core/test/zzrepro-mcp-cache.test.ts
    

    Observed output:

    AFTER invalidate("docs"): cachedMcpTools keys = [] while registry keySets = ["docs:extra"]; db:readonly listTools calls = 2 after invalidating only 'db' twice
    

    Happy to open a PR with this fix, or to be assigned if you prefer to take it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions