Agent / foldkit-agent-mcp

HttpHandlerOptions

interface · packages/agent-mcp/src/http.ts:70

interface HttpHandlerOptions<Model, Context_, Principal, ByName, ByTag> {
  readonly createAgent: (context: {
    readonly principal: Principal
    readonly sessionId: string
  }) => Agent.AgentRuntime<Model, Context_, Principal, ByName, ByTag>
  readonly authenticate?:
    | ((request: HttpRequest) => Effect.Effect<Principal, Unauthenticated>)
    | undefined
  readonly principalId?: ((principal: Principal) => string) | undefined
  readonly allowedOrigins?: ReadonlyArray<string> | undefined
  readonly sessionTtlMs?: number | undefined
  readonly clock?: (() => number) | undefined
  readonly replayBuffer?: number | undefined
  readonly serverInfo?:
    | {
        readonly name: string
        readonly version: string
      }
    | undefined
}

Members

HttpHandlerOptions.createAgent

property · packages/agent-mcp/src/http.ts:76

readonly createAgent: (context: {
  readonly principal: Principal
  readonly sessionId: string
}) => Agent.AgentRuntime<Model, Context_, Principal, ByName, ByTag>

Binds a runtime for one authenticated caller.

Called once per session, so no two principals ever share a runtime.

HttpHandlerOptions.authenticate

property · packages/agent-mcp/src/http.ts:92

readonly authenticate?:
  | ((request: HttpRequest) => Effect.Effect<Principal, Unauthenticated>)
  | undefined

Resolves the caller from the request: an Effect, so it may ask a token store. Failing with Unauthenticated refuses it, a 401 carrying reason; a defect is a 500 that says nothing of it, logged. It needs nothing: provide what it reads (a session store) from a context built once, not per request. It runs in a fiber of its own, outside an httpApp request's, so a client that leaves does not interrupt it.

The principal comes from here and nowhere else: a principal taken from request params would let any caller claim any identity.

HttpHandlerOptions.principalId

property · packages/agent-mcp/src/http.ts:103

readonly principalId?: ((principal: Principal) => string) | undefined

A stable identity for a principal, used to bind a session to its creator.

Defaults to a structural key, so an authenticate that returns a fresh object per request still matches its own session. Supply this when a principal carries fields that differ between requests of the same caller, such as an issued-at or a token id.

HttpHandlerOptions.allowedOrigins

property · packages/agent-mcp/src/http.ts:110

readonly allowedOrigins?: ReadonlyArray<string> | undefined

Origins a browser may call from. A request carrying an Origin that is not listed is refused, which is what stops a page on another site from driving a local server through DNS rebinding.

HttpHandlerOptions.sessionTtlMs

property · packages/agent-mcp/src/http.ts:113

readonly sessionTtlMs?: number | undefined

Idle sessions are dropped after this long. Defaults to 30 minutes.

HttpHandlerOptions.clock

property · packages/agent-mcp/src/http.ts:116

readonly clock?: (() => number) | undefined

Injected for tests. Defaults to Date.now.

HttpHandlerOptions.replayBuffer

property · packages/agent-mcp/src/http.ts:119

readonly replayBuffer?: number | undefined

Events kept per stream for Last-Event-ID resumption. Defaults to 100.

HttpHandlerOptions.serverInfo

property · packages/agent-mcp/src/http.ts:121

readonly serverInfo?:
  | {
      readonly name: string
      readonly version: string
    }
  | undefined