@electric-ax/agents 0.2.4 → 0.4.0

package/docs/entities/agents/horton.md

@@ -8,7 +8,7 @@ outline: [2, 3]
 
 # Horton agent
 
-The built-in assistant registered by the Electric Agents dev server. Horton can chat conversationally, search the web, read and edit files, run shell commands, dispatch workers for isolated subtasks, and spawn long-lived coders for code changes.
+The built-in assistant registered by the Electric Agents dev server. Horton can chat conversationally, search the web, read and edit files, run shell commands, and dispatch workers for isolated subtasks.
 
 **Source:** [`packages/agents/src/agents/horton.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/horton.ts)
 
@@ -35,8 +35,6 @@ Horton is configured with `ctx.electricTools` plus the base Horton tool set:
 | `brave_search` | Web search via the Brave Search API.                     |
 | `fetch_url`    | Fetch a URL and return it as markdown.                   |
 | `spawn_worker` | Dispatch a subagent for an isolated subtask.             |
-| `spawn_coder`  | Spawn a long-lived `coder` entity backed by Claude Code or Codex. |
-| `prompt_coder` | Send a follow-up prompt to an existing coder.            |
 
 `brave_search` requires `BRAVE_SEARCH_API_KEY` in the environment; without it the tool errors at call time.
 
@@ -53,7 +51,7 @@ After the first agent run completes, Horton calls `generateTitle()` (Haiku) to s
 | Type name         | `horton`                                          |
 | Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)     |
 | Title model       | `claude-haiku-4-5-20251001`                       |
-| Tools             | `ctx.electricTools` + base Horton tool set, coder tools, plus docs/skill tools when configured |
+| Tools             | `ctx.electricTools` + base Horton tool set, plus docs/skill tools when configured |
 | Working directory | Passed at bootstrap (defaults to `process.cwd()`) |
 | Title generation  | Yes, after the first run if no title tag exists   |
 
@@ -89,4 +87,3 @@ registry.define("my-assistant", {
 ## Related
 
 - [Worker](./worker) — the subagent type Horton dispatches via `spawn_worker`.
-- [Coder](./coder) — the coding-session entity Horton dispatches via `spawn_coder`.

package/docs/index.md

@@ -22,7 +22,7 @@ Every step — runs, tool calls, text deltas, state changes — is appended to t
 
 <EntityOverviewDiagram />
 
-Start with the [Quickstart](/docs/agents/quickstart) to run the built-in `horton`, `worker`, and `coder` entities and connect your own app in a few minutes. The [Usage overview](/docs/agents/usage/overview) summarises the full developer surface in a single page.
+Start with the [Quickstart](/docs/agents/quickstart) to run the built-in `horton` and `worker` entities and connect your own app in a few minutes. The [Usage overview](/docs/agents/usage/overview) summarises the full developer surface in a single page.
 
 ## How it works
 
@@ -135,6 +135,8 @@ await ctx.agent.run()
 
 Functions the LLM can call during the agent loop. Each tool has a name, description, parameters (defined with [TypeBox](https://github.com/sinclairzx81/typebox) or any [Standard Schema](https://standardschema.dev) validator), and an execute function. Tools run in the handler's context and have access to the entity's state and coordination primitives. See [Defining tools](/docs/agents/usage/defining-tools) and the [`AgentTool` reference](/docs/agents/reference/agent-tool).
 
+External tools, resources, and prompts can also be loaded from [Model Context Protocol](https://modelcontextprotocol.io) servers — declared in `mcp.json`, the desktop app's `settings.json`, or programmatically. See [MCP servers](/docs/agents/usage/mcp-servers).
+
 ```ts
 const searchKbTool: AgentTool = {
   name: "search_kb",
@@ -198,7 +200,7 @@ console.log(db.collections.texts.toArray)
 
 ## Next steps
 
-- [Quickstart](/docs/agents/quickstart) — run the built-in `horton`, `worker`, and `coder` entities and connect your own app.
+- [Quickstart](/docs/agents/quickstart) — run the built-in `horton` and `worker` entities and connect your own app.
 - [Usage overview](/docs/agents/usage/overview) — the full developer surface on one page.
 - [Defining entities](/docs/agents/usage/defining-entities) — entity types, schemas, and configuration.
 - [Writing handlers](/docs/agents/usage/writing-handlers) — handler lifecycle and the `ctx` API.

package/docs/quickstart.md

@@ -49,7 +49,7 @@ npx electric-ax agents quickstart
 This:
 
 1. Starts Postgres, Electric, and the Electric Agents runtime server in Docker (the runtime serves both the API and the web UI on `http://localhost:4437`).
-2. Starts a built-in **Horton** runtime in the foreground that registers the `horton`, `worker`, and `coder` entity types.
+2. Starts a built-in **Horton** runtime in the foreground that registers the `horton` and `worker` entity types.
 3. Prints onboarding commands you can copy into a second terminal.
 
 Leave this terminal running. Press `Ctrl-C` to stop the built-in Horton runtime — the runtime server containers keep running in the background until you call [`electric agents stop`](#stop-the-dev-environment).
@@ -186,7 +186,7 @@ npx electric-ax agents stop --remove-volumes # stop containers and wipe data
 
 ```sh
 npx electric-ax agents start          # runtime server + UI (background, Docker)
-npx electric-ax agents start-builtin  # built-in Horton, worker, and coder (foreground)
+npx electric-ax agents start-builtin  # built-in Horton and worker (foreground)
 ```
 
 See the [CLI reference](./reference/cli#start) for the full set of commands.

package/docs/reference/handler-context.md

@@ -59,10 +59,6 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
     id: string,
     schema: T
   ): SharedStateHandle<T>
-  useCodingAgent(
-    sessionId: string,
-    opts: UseCodingAgentOptions
-  ): Promise<CodingSessionHandle>
   send(
     entityUrl: string,
     payload: unknown,
@@ -107,43 +103,12 @@ interface HandlerContext<TState extends StateProxy = StateProxy> {
 | `spawn(type, id, args?, opts?)`   | `Promise<EntityHandle>`                                           | Spawn a child entity. `opts` accepts `tags`, `observe`, `initialMessage`, and `wake`. See [`EntityHandle`](./entity-handle).                                                                                                               |
 | `observe(source, opts?)`          | `Promise<EntityHandle \| SharedStateHandle \| ObservationHandle>` | Observe a source. Return type depends on source type: `EntityHandle` for entities, `SharedStateHandle & ObservationHandle` for db, `ObservationHandle` otherwise. Use `entity()`, `cron()`, `entities()`, `db()` helpers to build sources. |
 | `mkdb(id, schema)`                | `SharedStateHandle<T>`                                            | Create a new shared state stream. See [`SharedStateHandle`](./shared-state-handle).                                                                                                                                                        |
-| `useCodingAgent(sessionId, opts)` | `Promise<CodingSessionHandle>`                                    | Spawn or attach to the built-in `coder` entity for a Claude Code or Codex CLI session. Requires the `coder` type to be registered.                                                                                                         |
 | `send(entityUrl, payload, opts?)` | `void`                                                            | Send a message to another entity. `opts` accepts `type` and `afterMs` (delay in milliseconds).                                                                                                                                             |
 | `recordRun()`                     | `RunHandle`                                                       | Record a non-LLM run in the built-in `runs` collection, so observers using `wake: "runFinished"` are notified when external work completes.                                                                                               |
 | `setTag(key, value)`              | `Promise<void>`                                                   | Set a tag on this entity.                                                                                                                                                                                                                  |
 | `removeTag(key)`                  | `Promise<void>`                                                   | Remove a tag from this entity.                                                                                                                                                                                                             |
 | `sleep()`                         | `void`                                                            | End the handler without running an agent. The entity remains idle until the next wake.                                                                                                                                                     |
 
-## Coding sessions
-
-`useCodingAgent()` is a convenience wrapper around the built-in `coder` entity type.
-
-```ts
-type CodingAgentType = "claude" | "codex"
-
-interface UseCodingAgentOptions {
-  agent: CodingAgentType
-  nativeSessionId?: string
-  importFrom?: { agent: CodingAgentType; sessionId: string }
-  cwd?: string
-  wake?: Wake
-}
-
-interface CodingSessionHandle {
-  readonly entityUrl: string
-  readonly sessionId: string
-  readonly agent: CodingAgentType
-  meta(): CodingSessionMeta | undefined
-  status(): "initializing" | "idle" | "running" | "error" | undefined
-  run: Promise<void>
-  send(prompt: string): void
-  readonly events: ReadonlyArray<CodingSessionEventRow>
-  readonly messages: ReadonlyArray<CodingSessionEventRow>
-}
-```
-
-By default, `useCodingAgent()` observes the coder with `wake: "runFinished"`, so the caller wakes when a prompt finishes. Pass a change wake if you need per-event updates.
-
 ## RunHandle
 
 `recordRun()` is for handlers that perform work outside `ctx.agent.run()` but still want to expose run lifecycle events.

package/docs/reference/mcp-registry.md

@@ -0,0 +1,189 @@
+---
+title: McpRegistry
+titleTemplate: "... - Electric Agents"
+description: >-
+  API reference for the MCP Registry — addServer, applyConfig,
+  subscribe, reauthorize, and the lifecycle of an MCP server entry
+  inside the runtime.
+outline: [2, 3]
+---
+
+# McpRegistry
+
+The MCP registry owns the live set of [Model Context Protocol](https://modelcontextprotocol.io) servers a runtime is connected to. It manages stdio subprocesses and HTTP clients, drives the OAuth state machine, and emits push-based snapshots so embedders can render UI without polling.
+
+**Source:** `@electric-ax/agents-mcp` (re-exported as `McpRegistry` from `@electric-ax/agents`)
+
+`BuiltinAgentsServer.mcpRegistry` exposes the instance that the embedded runtime owns; the [usage guide](/docs/agents/usage/mcp-servers) walks through registering servers from agent-host code.
+
+```ts
+interface Registry {
+  addServer(cfg: McpServerConfig): Promise<AddServerResult>
+  applyConfig(cfg: McpConfig): Promise<AddServerResult[]>
+  removeServer(name: string): Promise<void>
+  list(): ReadonlyArray<ListedEntry>
+  get(name: string): Entry | undefined
+  finishAuth(server: string, code: string, state?: string): Promise<AddServerResult>
+  reauthorize(name: string): Promise<void>
+  disable(name: string): Promise<void>
+  enable(name: string): Promise<AddServerResult>
+  subscribe(handler: RegistrySubscriber): () => void
+}
+```
+
+## Methods
+
+| Method                      | Description                                                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `addServer(cfg)`            | Register or reconfigure a single server. Idempotent on unchanged `(name, url, transport, authMode, scopes, command, args)`. |
+| `applyConfig(cfg)`          | Replace the full set of registered servers. Adds new ones, reconfigures changed ones, and removes anything not in `cfg`. |
+| `removeServer(name)`        | Tear down a single server: close the transport, drop tokens from the in-memory cache, remove the entry.                  |
+| `list()`                    | Returns the current snapshot as a plain array — same shape as the `servers` field of [`RegistrySnapshot`](#registrysnapshot). |
+| `get(name)`                 | Internal lookup of a single entry, with the live `transport` handle and the resolved `provider`. Used by IPC handlers.    |
+| `finishAuth(name, code, state?)` | Complete the OAuth authorization-code flow for an `authenticating` server. Called by the embedder after intercepting the redirect URI. |
+| `reauthorize(name)`         | Force a fresh OAuth flow without removing the entry. Closes the transport, drops cached tokens (hooks remain registered), and rebuilds in place. |
+| `disable(name)`             | Pause a server. Closes the transport but keeps the entry; tokens stay in the cache.                                       |
+| `enable(name)`              | Re-add a previously-disabled server using its last-known config.                                                          |
+| `subscribe(handler)`        | Push-based view of registry state. The handler fires synchronously with a sentinel snapshot, then on every mutation. Returns an unsubscribe function. |
+
+## `addServer` vs `applyConfig`
+
+Both feed the same internal pipeline; pick by what you have:
+
+- **`addServer(cfg)`** — register one server. Use when you're adding an entry in response to a user action, a per-session tool, or a one-off integration.
+- **`applyConfig({ servers })`** — replace the full set. Anything in the registry that isn't in `cfg.servers` is removed; existing entries with unchanged config are left alone (no transport churn). This is what the file-based loaders for `mcp.json` and the desktop `settings.json` compile down to.
+
+Idempotency is the load-bearing property: editors save spuriously, file watchers fire double events on macOS, and most apps re-apply the same baseline on every restart. Calling `applyConfig` with the same shape twice does nothing the second time, so it's safe to wire to noisy upstreams.
+
+## `AddServerResult`
+
+`addServer` and `finishAuth` return a discriminated union so the caller can react without inspecting the registry afterwards:
+
+```ts
+type AddServerResult =
+  | { state: "ready"; id: string; toolCount: number }
+  | { state: "authenticating"; id: string; authUrl: string }
+  | { state: "error"; id: string; error: McpToolError }
+```
+
+| State            | Meaning                                                                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `ready`          | Connected and tools listed; calls available at the next agent wake.                                                                |
+| `authenticating` | OAuth required. `authUrl` is the URL to send the user to. The desktop's `openAuthorizeUrl` hook opens it in a sandboxed BrowserWindow automatically. |
+| `error`          | Connect, transport, or auth-config failure. `error.kind` and `error.message` describe what went wrong.                              |
+
+`applyConfig` returns one `AddServerResult` per server in the supplied config (in the same order).
+
+## Lifecycle of an entry
+
+Every entry transitions through one of five statuses, surfaced on the snapshot. The states that matter to UI:
+
+| Status           | Meaning                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| `connecting`     | Transport is being built (DCR, HTTPS discovery) or reconnecting.                                 |
+| `authenticating` | OAuth flow needed; `authUrl` is set, browser window is open.                                      |
+| `ready`          | Transport connected; tools listed and callable.                                                   |
+| `error`          | Transport or auth-config failure. The entry stays in `list()` so the UI can surface the failure. |
+| `disabled`       | Operator paused the server via `disable(name)`. Recoverable through `enable(name)`.              |
+
+Transitions are atomic with respect to subscribers: every state change fires a single snapshot in which the entry shows its new status. `reauthorize` mutates entries in place — the row never disappears from `list()`, even mid-rebuild, so renderers don't see a flicker.
+
+## `subscribe(handler)` and `RegistrySnapshot`
+
+```ts
+type RegistrySubscriber = (snapshot: RegistrySnapshot) => void
+
+interface RegistrySnapshot {
+  seq: number
+  servers: ReadonlyArray<ListedEntry>
+}
+```
+
+Subscribing is the primary way to drive a UI off the registry. The first invocation is synchronous and carries `seq: 0` as a sentinel — embedders treat it as the bootstrap snapshot, not part of the event stream. After that, every mutation increments `seq` (1, 2, 3, …) and broadcasts the full snapshot. A late subscriber still sees `seq: 0` on its first delivery; emitted events continue from the registry's current counter.
+
+Handlers must not throw. The registry catches exceptions per subscriber so a misbehaving consumer can't break the others, but the catch is a safety net, not a feature — log and swallow inside your handler.
+
+```ts
+const off = registry.subscribe((snap) => {
+  if (snap.seq === 0) {
+    // bootstrap — render the initial list
+  } else {
+    // diff against the previous snapshot, or just re-render
+  }
+})
+// ...
+off()
+```
+
+## `ListedEntry`
+
+The shape of each `servers[]` entry inside a snapshot:
+
+```ts
+interface ListedEntry {
+  name: string
+  status: McpServerStatus
+  toolCount: number
+  transport?: "http" | "stdio"
+  authMode?: "none" | "apiKey" | "clientCredentials" | "authorizationCode"
+  authUrl?: string
+  error?: McpToolError
+  tools: Array<{ name: string; description?: string; inputSchema: unknown }>
+  capabilities?: unknown
+}
+```
+
+| Field          | Type                                              | Description                                                                                  |
+| -------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `name`         | `string`                                          | The server's stable identifier.                                                              |
+| `status`       | `McpServerStatus`                                 | Current lifecycle state — see the table above.                                               |
+| `toolCount`    | `number`                                          | Number of tools the server advertises. `0` until `status === "ready"`.                       |
+| `transport`    | `"http" \| "stdio"`                               | The transport variant in use.                                                                |
+| `authMode`     | `string`                                          | `none` / `apiKey` / `clientCredentials` / `authorizationCode`. UI badges + "show Authorize" check use this. |
+| `authUrl`      | `string`                                          | Set while `status === "authenticating"`. The URL to open for OAuth consent.                  |
+| `error`        | [`McpToolError`](#mcptoolerror)                   | Set while `status === "error"`.                                                              |
+| `tools`        | `Array<{ name; description?; inputSchema }>`      | Tool metadata as advertised by the server. Each becomes `mcp__<server>__<tool>` for the LLM. |
+| `capabilities` | `unknown`                                         | Server-declared MCP capabilities object (resources, prompts, etc.).                          |
+
+## `McpToolError`
+
+```ts
+interface McpToolError {
+  kind: McpToolErrorKind
+  message: string
+  details?: unknown
+}
+
+type McpToolErrorKind =
+  | "auth_unavailable"
+  | "transport_error"
+  | "timeout"
+  | "server_error"
+  | "tool_not_found"
+```
+
+The same shape surfaces on entry-level `error` (when `addServer` fails to connect) and on individual tool calls. See the [usage guide's failure modes table](/docs/agents/usage/mcp-servers#failure-modes).
+
+## `RegistryOpts`
+
+`BuiltinAgentsServer` constructs the registry on your behalf. You only see this shape if you instantiate `agents-mcp` directly (e.g. from a custom embedder):
+
+```ts
+interface RegistryOpts {
+  publicUrl?: string
+  openAuthorizeUrl?: (url: string, server: string) => void
+}
+
+function createRegistry(opts: RegistryOpts): Registry
+```
+
+| Field              | Description                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `publicUrl`        | Base URL used to construct the OAuth `redirect_uri` (full URI is `<publicUrl>/oauth/callback/<server-name>`). MUST be stable across restarts — DCR registers it with the auth server and persists it in the keychain, so a value that drifts forces re-authorization on every launch. Embedders that listen on an ephemeral port should pass a fixed loopback literal (the desktop uses `http://127.0.0.1:53117`); nothing actually listens at the URL — the embedder's BrowserWindow intercepts the redirect by prefix. |
+| `openAuthorizeUrl` | Hook invoked when an `authorizationCode` server first needs consent. Receives the SDK-generated authorize URL. The desktop opens it in a sandboxed `BrowserWindow`; headless embedders can read the URL from the `authenticating` envelope of `addServer` and surface it themselves. |
+
+## See also
+
+- [MCP servers usage guide](/docs/agents/usage/mcp-servers) — the practical walkthrough of registering servers, OAuth, persistence, and the per-agent allowlist.
+- [`McpServerConfig`](/docs/agents/reference/mcp-server-config) — schema for the `cfg` argument to `addServer` / `applyConfig`.
+- [`BuiltinAgentsServer`](/docs/agents/usage/embedded-builtins) — host options that affect MCP, including `extraMcpServers` and `openAuthorizeUrl`.

package/docs/reference/mcp-server-config.md

@@ -0,0 +1,226 @@
+---
+title: McpServerConfig
+titleTemplate: "... - Electric Agents"
+description: >-
+  Schema reference for MCP server entries — transports, auth modes, and
+  persistence callbacks accepted by Registry.addServer, applyConfig, and
+  the mcp.json / settings.json layers.
+outline: [2, 3]
+---
+
+# McpServerConfig
+
+Shape of a server entry in the MCP registry. Identical between declarative (`mcp.json`, desktop `settings.json`) and programmatic (`Registry.addServer`) creation paths.
+
+**Source:** `@electric-ax/agents` (re-exported from `@electric-ax/agents-mcp`)
+
+```ts
+type McpServerConfig = McpHttpServerConfig | McpStdioServerConfig
+```
+
+The variant is selected by the `transport` field.
+
+## McpHttpServerConfig
+
+Streamable HTTP transport per the current MCP spec.
+
+```ts
+interface McpHttpServerConfig {
+  name: string
+  transport: "http"
+  url: string
+  auth: McpAuthConfig
+  timeoutMs?: number
+}
+```
+
+| Field       | Type            | Required | Description                                                                  |
+| ----------- | --------------- | -------- | ---------------------------------------------------------------------------- |
+| `name`      | `string`        | Yes      | Stable identifier. Used as the keychain account, the IPC verb argument, and the `mcp__<name>__<tool>` tool prefix. |
+| `transport` | `"http"`        | Yes      | Discriminator selecting the HTTP variant.                                    |
+| `url`       | `string`        | Yes      | The MCP server's HTTPS endpoint. Streamable transport with SSE inside.       |
+| `auth`      | `McpAuthConfig` | Yes      | One of the auth modes below. Use `{ mode: "none" }` for unauthenticated servers. |
+| `timeoutMs` | `number`        | No       | Per-call timeout override. Default `30000` (30 seconds).                     |
+
+## McpStdioServerConfig
+
+Locally-spawned subprocess speaking the MCP stdio protocol.
+
+```ts
+interface McpStdioServerConfig {
+  name: string
+  transport: "stdio"
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  auth?: McpAuthConfig
+  timeoutMs?: number
+}
+```
+
+| Field       | Type                     | Required | Description                                                              |
+| ----------- | ------------------------ | -------- | ------------------------------------------------------------------------ |
+| `name`      | `string`                 | Yes      | Stable identifier (see HTTP variant).                                    |
+| `transport` | `"stdio"`                | Yes      | Discriminator selecting the stdio variant.                               |
+| `command`   | `string`                 | Yes      | Executable name or absolute path. Resolved against `PATH`.               |
+| `args`      | `string[]`               | No       | CLI arguments. `${workspaceRoot}` is the only built-in expansion.        |
+| `env`       | `Record<string, string>` | No       | Environment variables for the subprocess. Inherits the parent's `PATH`.  |
+| `auth`      | `McpAuthConfig`          | No       | Typically `{ mode: "none" }`. Defaults to `none` when omitted.           |
+| `timeoutMs` | `number`                 | No       | Per-call timeout override. Default `30000`.                              |
+
+The subprocess is spawned lazily on the first tool call, kept alive across calls, and restarted on crash. One process per server, multiplexed via JSON-RPC `id`.
+
+## McpAuthConfig
+
+Discriminated union covering the four supported credential modes.
+
+```ts
+type McpAuthConfig =
+  | { mode: "none" }
+  | ApiKeyAuth
+  | ClientCredentialsAuth
+  | AuthorizationCodeAuth
+```
+
+### `none`
+
+```ts
+{ mode: "none" }
+```
+
+No authentication. Required for stdio servers that don't need credentials; rare for HTTP servers.
+
+### `apiKey`
+
+```ts
+interface ApiKeyAuth {
+  mode: "apiKey"
+  key: string
+  headerName?: string  // default "Authorization"
+  valuePrefix?: string // e.g. "Bearer "
+}
+```
+
+| Field         | Type     | Required | Description                                                                  |
+| ------------- | -------- | -------- | ---------------------------------------------------------------------------- |
+| `key`         | `string` | Yes      | Raw secret. Inline at the call site (e.g. `process.env.X_API_KEY`).          |
+| `headerName`  | `string` | No       | HTTP header name. Defaults to `Authorization`.                               |
+| `valuePrefix` | `string` | No       | Prepended to the key. Use `"Bearer "` for bearer tokens; empty for raw keys. |
+
+### `clientCredentials`
+
+OAuth 2.1 client-credentials grant. Unattended; no user interaction.
+
+```ts
+interface ClientCredentialsAuth {
+  mode: "clientCredentials"
+  tokenUrl: string
+  clientId: string
+  clientSecret: string
+  scopes?: string[]
+  audience?: string
+  resource?: string
+}
+```
+
+| Field          | Type       | Required | Description                                                                 |
+| -------------- | ---------- | -------- | --------------------------------------------------------------------------- |
+| `tokenUrl`     | `string`   | Yes      | OAuth token endpoint.                                                       |
+| `clientId`     | `string`   | Yes      | Inline at the call site (e.g. `process.env.X_CLIENT_ID`).                   |
+| `clientSecret` | `string`   | Yes      | Inline at the call site (e.g. `process.env.X_CLIENT_SECRET`).               |
+| `scopes`       | `string[]` | No       | Requested OAuth scopes.                                                     |
+| `audience`     | `string`   | No       | Auth0/OIDC `audience` claim, when the auth server requires it.              |
+| `resource`     | `string`   | No       | RFC 8707 resource indicator.                                                |
+
+The runtime exchanges the credentials for a short-lived access token, retries the exchange on 401, and never surfaces user-facing errors during steady state.
+
+### `authorizationCode`
+
+OAuth 2.1 authorization-code grant with PKCE. Requires a one-time browser flow per user.
+
+```ts
+interface AuthorizationCodeAuth {
+  mode: "authorizationCode"
+  scopes?: string[]
+  resource?: string
+  redirectUri?: string
+  client?: OAuthClientInfo
+  tokens?: OAuthTokens
+  onTokensChanged?: (tokens: OAuthTokens) => void | Promise<void>
+  onClientRegistered?: (client: OAuthClientInfo) => void | Promise<void>
+  oauthProviderRef?: string
+}
+```
+
+| Field                | Type                                          | Required | Description                                                                                                                              |
+| -------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `scopes`             | `string[]`                                    | No       | Requested OAuth scopes.                                                                                                                  |
+| `resource`           | `string`                                      | No       | RFC 8707 resource indicator.                                                                                                             |
+| `redirectUri`        | `string`                                      | No       | Override the default `${publicUrl}/oauth/callback/<server>` sentinel. Most embedders don't need this.                                    |
+| `client`             | `OAuthClientInfo`                             | No       | Pre-registered OAuth client (`client_id`, optional `client_secret`). When present, RFC 7591 Dynamic Client Registration is skipped.       |
+| `tokens`             | `OAuthTokens`                                 | No       | Pre-existing tokens to seed the in-process cache. The OAuth flow is skipped on boot; refresh-token rotation still happens transparently. |
+| `onTokensChanged`    | `(tokens) => void \| Promise<void>`           | No       | Fires after initial auth and on every refresh. Wire to a persistence layer if tokens should survive process restarts.                    |
+| `onClientRegistered` | `(client) => void \| Promise<void>`           | No       | Fires once after RFC 7591 DCR completes. Pair with `client` on the next boot to skip DCR.                                                |
+| `oauthProviderRef`   | `string`                                      | No       | Reference into a per-process map of pre-built `OAuthClientProvider` instances. Escape hatch for mTLS, OIDC quirks, etc.                  |
+
+### `OAuthTokens`
+
+```ts
+interface OAuthTokens {
+  accessToken: string
+  refreshToken?: string
+  expiresAt?: number  // Unix seconds
+}
+```
+
+### `OAuthClientInfo`
+
+```ts
+interface OAuthClientInfo {
+  clientId: string
+  clientSecret?: string
+  // RFC 7591 metadata (issued_at, expires_at, redirect_uris, …)
+  // — preserved verbatim from the DCR response.
+  [key: string]: unknown
+}
+```
+
+## Validation
+
+`mcp.json` and programmatic configs are validated when first applied:
+
+- `transport` must be `"http"` or `"stdio"`.
+- `auth.mode` must be one of `none` / `apiKey` / `clientCredentials` / `authorizationCode`.
+- `mcp.json` rejects forbidden reference keys (`clientIdRef`, `clientSecretRef`, `valueRef`, …) — secrets must be passed inline at the call site, not declared as references.
+- Inline `${VAR}` placeholders in `mcp.json` are expanded against `process.env` before validation.
+
+Invalid entries surface as `error`-state entries in `Registry.list()` with a structured `McpToolError`. The rest of the registry continues to operate.
+
+## Persistence helpers
+
+Two opt-in helpers from `@electric-ax/agents-mcp` produce auth-config slices that satisfy the persistence callback contract:
+
+```ts
+import { keychainPersistence, filePersistence } from "@electric-ax/agents-mcp"
+
+const tokens = await keychainPersistence({ server: "honeycomb" })
+// → { tokens?, client?, onTokensChanged, onClientRegistered }
+
+await registry.addServer({
+  name: "honeycomb",
+  transport: "http",
+  url: "https://mcp.honeycomb.io/mcp",
+  auth: { mode: "authorizationCode", scopes: ["mcp:read"], ...tokens },
+})
+```
+
+| Helper                              | Backing store                                                         | Notes                                                                |
+| ----------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `keychainPersistence({ server })`   | macOS `security`, Linux `secret-tool`. Throws on Windows.             | Service `electric-agents`, accounts `tokens:<server>` / `client:<server>`. |
+| `filePersistence({ path, server })` | Mode-`0600` JSON file. Refuses to read files with looser permissions. | Use for CI / containers without an OS keychain.                      |
+
+## See also
+
+- [MCP servers usage guide](/docs/agents/usage/mcp-servers) — programmatic, file-based, and desktop-settings paths end-to-end.
+- [`McpRegistry`](/docs/agents/reference/mcp-registry) — the API that consumes this config (`addServer` / `applyConfig` / lifecycle).
+- [`BuiltinAgentsServer`](/docs/agents/usage/embedded-builtins) — host options that affect MCP, including `extraMcpServers` and `openAuthorizeUrl`.

package/docs/usage/clients-and-react.md

@@ -35,9 +35,6 @@ const membersDb = await client.observe(
 )
 console.log(membersDb.collections.members.toArray)
 
-// Observe a built-in coder session by id.
-const coderDb = await client.observe(codingSession("feature-work"))
-console.log(coderDb.collections.events.toArray)
 ```
 
 ### Types
@@ -68,7 +65,6 @@ The same source helpers used by `ctx.observe()` can be used with `AgentsClient`.
 | Helper              | Use case                                             |
 | ------------------- | ---------------------------------------------------- |
 | `entity(url)`       | Observe one entity by URL.                           |
-| `codingSession(id)` | Observe a built-in `coder` entity by session id.     |
 | `entities({ tags })` | Observe the entity membership stream matching tags. |
 | `db(id, schema)`    | Observe a shared-state stream.                       |
 | `cron(expression)`  | Build a cron source for wake subscriptions.          |