Skip to content

AAK-MCP-STATELESS-001: Reliance on Mcp-Session-Id header / protocol-level session id

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

What it detects

Server or client code reads, writes, asserts, or constants the Mcp-Session-Id header. The ratified MCP 2026-07-28 spec removes the Mcp-Session-Id header and the protocol-level session, replacing them with explicit server-minted state handles (SEP-2567); SEP-1442 / SEP-2575 make the initialization handshake optional so stateless is the default. After the final spec lands on 2026-07-28, code that depends on this header (or on the session it represented) will silently break: any MCP request can land on any server instance, and sticky routing / shared session stores at the protocol layer are no longer guaranteed.

How to fix

Migrate to the 2026-07-28 stateless transport: route on the Mcp-Method header instead of Mcp-Session-Id, drop the per-connection session id, and treat each request as independently addressable. If per-server state is genuinely required, persist it behind an out-of-band identity (auth subject, OAuth sub, tool argument) rather than the removed session header.

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

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

Limitations

Runs only when a manifest at the project root names an MCP SDK: mcp, modelcontextprotocol or model-context-protocol as a dependency in pyproject.toml ([project] and optional dependencies, [dependency-groups], Poetry, uv or PDM) or on a requirements*.txt line, an @modelcontextprotocol/sdk, @anthropic-ai/mcp or @anthropic-ai/claude-agent-sdk dependency in package.json, io.modelcontextprotocol in a Maven or Gradle build, or an mcp or modelcontextprotocol line in Cargo.toml. A framework that wraps the SDK (fastmcp), the Rust SDK crate rmcp, a dependency declared only in setup.py, and a manifest in a subdirectory (svc/package.json) do not count. When it runs, it looks in source files for the header text Mcp-Session-Id (any case) or the constant MCP_SESSION_ID. 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-001.md: the page then shows that text, with the registry reference appended under it.