Repository navigation
Description
Please read this first
- Have you read the docs? Agents SDK docs
- Have you searched for related issues? The closest history is MCP Tools Cache Incorrectly Shared Across Different Agents with Callable Filters #695 (customizable MCP list tool caching) and the cache-scoping fixes in fix(agents-core): invalidate MCP tool caches safely #1605 / fix(mcp): keep cached tool arrays private #1681 / fix: isolate cached MCP tool definitions #1727; none covers this cross-server deletion.
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 atpackages/agents-core/src/mcp.ts:707-710whenever 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 deletescachedMcpTools[serverName]and then scans every key incachedMcpToolsand 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 nameddb:readonlyis cached under the key"db:readonly"— which starts with"db:". Invalidatingdbon the fallback path deletesdb: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-core0.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
BlueX888 commentedon Sep 24, 2026
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:
Observed output:
Happy to open a PR with this fix, or to be assigned if you prefer to take it.