Skip to content

AAK-MCP-STATELESS-004: MCP client never caches tools/list and depends on per-session state

Severity
LOW
Category
MCP Configuration (mcp-config)
Scanner
agent_audit_kit/scanners/mcp_stateless_migration.py
Auto-fixable
No.
SARIF name
McpClientNoToolsListCache

What it detects

Client code calls tools/list (or the SDK alias list_tools) inside a hot path / per-request loop with no caching marker (no lru_cache, TTL cache, dict memoization, or cached_* helper) nearby. Combined with reliance on per-session server state, this pattern multiplies round-trips and breaks under the 2026-07-28 stateless transport, where successive requests can reach different server instances. The 2026-07-28 tools section says the set a client gets must not vary per connection or as a side effect of other requests on the connection, and may vary by the authorization presented, so instances serving different sets to the same authorization are a server defect for the client to detect, not something to design for.

How to fix

Cache the tools/list response client-side with an explicit TTL (ttlMs), per authorization, since the set may vary by the authorization presented, and refresh it on cache miss. Do not rely on notifications/tools/list_changed alone: it is a SHOULD, and goes only to clients subscribed with toolsListChanged: true. Instances that serve different sets to the same authorization are a server defect, so report or refuse that mismatch rather than treating discovery as a hint that may differ.

To confirm the finding is gone, report only this rule:

agent-audit-kit scan . --rules AAK-MCP-STATELESS-004

Limitations

Reads source files only in a project whose root manifest names an MCP SDK in a form AAK-MCP-STATELESS-001 recognises. It fires on a file that calls tools/list (or list_tools(, .tools.list() at least twice, mentions session_id or the session header, and contains none of lru_cache, cached_property, cachetools, TTLCache, ttlMs, ttl_ms, ttlSeconds, ttl_seconds, tools_list_cache, cached_tools, memoize or functools.cache. A single tools/list call inside a per-request handler is not counted, and neither are calls made through the TypeScript SDK's client.listTools(). A source file over 512 KB, a config file over 1 MB or a manifest over 2 MB is not read.

References


All rules. This page is generated from the rule registry when the documentation is built; to change it, change the rule in agent_audit_kit/rules/builtin.py. To give the rule a hand-written write-up, add docs/rules/AAK-MCP-STATELESS-004.md: the page then shows that text, with the registry reference appended under it.