Agent / foldkit-agent-mcp

HTTP identity, sessions, and origin security

initialize creates a session tracked by Mcp-Session-Id; unknown or expired sessions return HTTP 404 so clients re-initialize, and DELETE closes the session.

A session ID is bound to the authenticated principal—never treated as a bearer token—so another principal presenting the same ID receives 404. Provide principalId when your principal object contains per-request fields. GET opens an SSE notification stream supporting Last-Event-ID replay, delivering each event to one stream per session.

Three HTTP rules keep transport headers from widening contract authority:

  • Identity comes from authenticate: Any principal fields inside JSON-RPC params are ignored.
  • Browser Origin must be allowlisted: Requests carrying an Origin header outside allowedOrigins are refused.
  • Unauthenticated servers stay local: Bind local development servers to localhost and require authenticate anywhere exposed over a network.

Keep stdout clean over stdio

stdio serves one caller-provided runtime with no HTTP session layer. Because stdout carries JSON-RPC frames and Effect's default Node logger writes to stdout, avoid console.log and let stdio send its diagnostics to stderr (or pass a custom diagnostics handler).