HTTP identity and sessions

initialize creates a session, identified afterwards by Mcp-Session-Id. Unknown or expired sessions return 404 so the client can re-initialize; DELETE terminates one.

A session id is not a bearer token. The authenticated principal owns the session. If a different principal presents the same id, the server treats it as unknown rather than revealing that the session exists.

When a principal contains request-varying fields, provide principalId so the adapter knows which stable identity should own the session.

GET opens the SSE notification stream. Events have ids; reconnecting with Last-Event-ID replays missed events without replaying ones already seen. An event is delivered to one stream for that session, not broadcast across every open connection.

HTTP security rules#

The adapter deliberately keeps protocol identity separate from caller-provided payloads:

• Authentication is the source of principal identity. A principal supplied inside request params is ignored.
• Browser Origin values must be allowlisted. An Origin-bearing request is refused when its origin is not configured. Non-browser clients usually send no Origin and are unaffected.
• A local unauthenticated server should stay local. Bind to localhost; use authentication when exposing the server beyond it.

These rules exist so MCP transport details cannot silently widen the authority already declared by foldkit-agent.

Stdio notes#

Stdio has one caller-provided runtime and no HTTP session layer.

stdout is reserved for MCP messages. A stray console.log corrupts the protocol stream; write diagnostics to stderr.

Choosing an adapter#

All four adapters serve the same AssistantAgent contract through a bound runtime.

See also#

• Agents guide — builder → contract → runtime and the authority model.
• foldkit-agent — the protocol-neutral contract and runtime.
• examples/todo — a focused contract served through adapters.