Streamable HTTP

Use httpApp when the MCP server should run behind an Effect HTTP server or be converted to a web-standard Request -> Response handler:

import * as HttpEffect from 'effect/http/HttpEffect'
import { AgentMcp } from 'foldkit-agent-mcp'

const handler = HttpEffect.toWebHandler(
  AgentMcp.httpApp({
    authenticate: request => verify(request.headers['authorization']),
    createAgent: ({ principal }) => bindAgentFor(principal),
    allowedOrigins: ['https://app.example'],
  }),
)

const response = await handler(request)

Unlike stdio, HTTP is multi-session. createAgent runs for a session under the principal authenticate resolves, so different callers do not accidentally share a bound application runtime. authenticate is an Effect, so it may ask a token store: failing with AgentMcp.unauthenticated(reason?) (or Remote's RemoteUnauthenticated, which has the same shape) refuses the caller with a 401 carrying reason, and a defect is a 500 that says nothing of it, logged on the server. It needs no service: provide what it reads from a context built once at startup, not per request.

Underneath, httpHandler exposes the same session/security machinery against a transport-neutral request shape. Use it when integrating with a server stack that is not Effect HTTP:

const server = AgentMcp.httpHandler({
  authenticate: request => verify(request.headers['authorization']),
  createAgent: ({ principal }) => bindAgentFor(principal),
  allowedOrigins: ['https://app.example'],
})

const response = await server.handle({ method, headers, body })