Agent / foldkit-agent-mcp

Diagnostics

The adapter answers some failures without telling the client why, since the cause may carry application internals. Each is a typed diagnostic, reported through foldkit-surface's Diagnostics channel:

`_tag`	`level`	When
`AuthenticateDefect`	`error`	`authenticate` died or threw; the request was answered 500.
`CapabilityDefect`	`error`	A capability's dispatch died; the call was answered a tool error naming no cause.
`RequestDefect`	`error`	Handling a request threw (a projection, a resource read); it was answered an internal error.
`ToolListDefect`	`error`	Listing the tools threw after the Model changed, so no `tools/list_changed` was sent.
`TransportEndDefect`	`warning`	A client transport's `end` threw as its session ended; the session ended anyway.

The host runs outside any Effect context of yours, so the reporter is an option, diagnostics, on handler, httpHandler, httpApp and stdio. Without it, a diagnostic goes to Diagnostics.Reporter's default, Effect's log, or to stderr under stdio:

const reported = AgentMcp.httpHandler({
  authenticate: request => verify(request.headers['authorization']),
  createAgent: ({ principal }) => bindAgentFor(principal),
  diagnostics: diagnostic => Effect.logError(`mcp: ${diagnostic.message}`),
})

In a test, pass Diagnostics.collect().report and assert on reported.

Choosing an adapter

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

Where the agent runs	Adapter
In the page, beside the user	`foldkit-agent-webmcp`
An external MCP client, over stdio or HTTP	`foldkit-agent-mcp`
Another agent, over A2A	`foldkit-agent-a2a`
An Agent Native host	`foldkit-agent-native`

Choosing an adapter#

See also#

Choosing an adapter

See also