@terreno/mcp 58.0.0 → 58.0.1

package/dist/docs/versioned/58.0.0/how-to/enable-mcp-oauth.md

@@ -0,0 +1,191 @@
+# Enable MCP OAuth for a JWT app
+
+Let Claude.ai custom connectors, ChatGPT apps, and other remote MCP clients connect to your app's `POST /mcp` through OAuth 2.1. Terreno runs the authorization server; your app hosts one consent screen. A Terreno JWT is the usual way to approve that screen. An app with its own session sets `req.user` first. See [Apps without a Terreno JWT](#apps-without-a-terreno-jwt).
+
+Use [a service token](connect-mcp-service-token.md) when the client can only hold a static Bearer key (Perplexity, Cursor, Claude Code). For a headless client that can perform a token request, use [client credentials](#headless-clients-client-credentials) instead.
+
+## Prerequisites
+
+- A `TerrenoApp` backend with at least one MCP tool ([Expose MCP tools](expose-mcp-tools.md))
+- A public https origin for the API, for example `https://api.example.com`
+- A signed-in page in your app that can call the API with the user's JWT
+
+## 1. Turn on `mcpOAuth`
+
+MCP OAuth is off until you set `enabled: true`. Without it the app has no `/oauth/*` routes, no `.well-known/oauth-*` documents, and no OAuth challenge on `/mcp`.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpOAuth: {
+    consentUrl: "https://app.example.com/oauth/consent",
+    enabled: true,
+    issuer: "https://api.example.com",
+  },
+});
+```
+
+- `issuer` is the API's public origin, with no path. Every discovery URL and endpoint is built from it, so it must be the origin clients reach.
+- `consentUrl` is the page from step 2.
+
+### Choose how clients get a `client_id`
+
+Dynamic client registration (`POST /oauth/register`) is a separate opt-in and stays off by default. The endpoint is unauthenticated: anyone who can reach your API can create a client with any name and a redirect on an allowed host. The consent screen is then the only thing between that client and a user's grant, so a convincing name is enough to phish an approval.
+
+- **Registration off (default).** Create each client yourself and give its `client_id` to the client (Claude.ai custom connectors accept one under advanced settings). `/oauth/register` returns 404 and the metadata has no `registration_endpoint`.
+
+  ```typescript
+  import {McpOAuthClient} from "@terreno/api";
+
+  await McpOAuthClient.create({
+    clientId: "claude-connector",
+    clientName: "Claude",
+    grantTypes: ["authorization_code", "refresh_token"],
+    redirectUris: ["https://claude.ai/api/mcp/auth_callback"],
+    responseTypes: ["code"],
+  });
+  ```
+
+  A loopback redirect (`localhost`, `127.0.0.1`, or `[::1]`) matches any port. Register one URI, for example `http://127.0.0.1:33418/callback`, and a native client can send `http://127.0.0.1:<ephemeral>/callback` with the same scheme, host, path, and query. The authorization code is sent to the port the client used. `localhost` and `127.0.0.1` do not match each other. Every other redirect URI must match exactly. There is no per-client opt-out. Another process on that host can listen on a different port and receive the code. PKCE `S256` is what stops that process from exchanging it.
+
+- **Registration on.** Turn it on only when clients you cannot pre-register must connect. Set `dynamicClientRegistration: true` and list `allowedRedirectHosts`, which limits where a registered client may send codes. Claude.ai redirects to `claude.ai`, ChatGPT to `chatgpt.com`. Use `*.example.com` for subdomains, and add `localhost` only if you want local clients with loopback `http://` redirects. Keep rate limiting on.
+
+  ```typescript
+  mcpOAuth: {
+    allowedRedirectHosts: ["claude.ai", "chatgpt.com"],
+    consentUrl: "https://app.example.com/oauth/consent",
+    dynamicClientRegistration: true,
+    enabled: true,
+    issuer: "https://api.example.com",
+  },
+  ```
+
+Booting with an issuer that has a path, a consent URL that is not a URL, or registration on with no redirect hosts throws. Full option list: [API reference → MCP OAuth](../reference/api.md#mcp-oauth).
+
+## 2. Host the consent screen
+
+If the backend serves `@terreno/admin-spa` (`AdminSpaServeApp`), it already has one: set `consentUrl` to `${issuer}/console/oauth/consent` (use your `basePath` if it is not `/console`) and skip to step 3. Any signed-in user can approve there, and the page uses the Better Auth session cookie. See [admin-spa reference](../reference/admin-spa.md#mcp-oauth-consent-route).
+
+To build your own page instead:
+
+The client sends the user's browser to `/oauth/authorize`. Terreno checks the client, redirect URI, and PKCE, stores a pending request, and redirects to `consentUrl?request=<id>`. Your page:
+
+1. Makes sure the user is signed in (send them through login and back if not, keeping `request`).
+2. Loads the request to show who is asking:
+
+   ```http
+   GET /oauth/authorize/<request>
+   Authorization: Bearer <user JWT>
+   ```
+
+   Response: `{data: {clientName, redirectHost, scope, expiresAt, …}}`. Show the client name and redirect host so the user can spot a client they did not start.
+
+3. Posts the decision with the same JWT, then sends the browser to the returned URL:
+
+   ```http
+   POST /oauth/authorize/<request>/approve   # or /deny
+   Authorization: Bearer <user JWT>
+   ```
+
+   ```typescript
+   const {data} = await approve(requestId);
+   window.location.assign(data.redirectUrl);
+   ```
+
+The three endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequest`, `denyMcpOAuthRequest`), so `bun run sdk` generates hooks for them. A request expires after 10 minutes (400 `Authorization request expired`), and a decided request cannot be decided again (409). The endpoints refuse `mcp_` and OAuth bearers, so an agent cannot approve itself.
+
+### Apps without a Terreno JWT
+
+`authenticateMiddleware()` calls `next()` when `req.user` is already set, so the consent routes do not require a JWT or a Better Auth session. Set the approving user in `addMiddleware`, which runs before these routes. Limit that to the consent paths. `GET /oauth/authorize` stays the unauthenticated redirect that starts the flow.
+
+The user object needs `_id`. Approve issues the grant to that id and records that user's `tokenEpoch`. `userForThisRequest` must resolve a session the app has already verified, such as a signed session cookie. Do not set `req.user` from an unverified header or query parameter. That user becomes the subject of the grant.
+
+```typescript
+new TerrenoApp({userModel: User, mcpOAuth: {consentUrl, enabled: true, issuer}})
+  .addMiddleware(async (req, _res, next) => {
+    if (!req.path.startsWith("/oauth/authorize/")) {
+      next();
+      return;
+    }
+    const user = await userForThisRequest(req);
+    if (user) {
+      req.user = user;
+    }
+    next();
+  });
+```
+
+Call `GET /oauth/authorize/<request>` and `POST .../approve` or `.../deny` with no `Authorization` header. `mcp_` and `mcpat_` bearers are still rejected on those routes.
+
+## 3. Connect a client
+
+Give the client the MCP URL, `https://api.example.com/mcp`. It discovers the rest:
+
+1. `POST /mcp` without credentials returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"`.
+2. The client reads that document, then `/.well-known/oauth-authorization-server`.
+3. It uses the `client_id` you gave it, or registers itself at `/oauth/register` when `dynamicClientRegistration` is on, then runs the browser flow through your consent screen, and exchanges the code at `/oauth/token` for an access token (`mcpat_…`, one hour) and a refresh token (`mcprt_…`, 30 days).
+
+For Claude.ai: **Settings → Connectors → Add custom connector**, paste the MCP URL, and connect. For ChatGPT: create a connector with the MCP URL and choose OAuth.
+
+## Headless clients (client credentials)
+
+A sandbox or another server has no browser, so it cannot run the authorization-code flow. Create a confidential client bound to a service-account user. The helper returns the secret once. Store it, then exchange it at `POST /oauth/token`. Dynamic registration stays public-only and still rejects client secrets.
+
+```typescript
+import {McpOAuthClient} from "@terreno/api";
+
+const {client, clientSecret} = await McpOAuthClient.issueConfidential({
+  clientName: "Sandbox agent",
+  tokenEndpointAuthMethod: "client_secret_basic", // or "client_secret_post"
+  userId: serviceAccount._id,
+});
+```
+
+`client_secret_basic` sends `Authorization: Basic` with the form-encoded `client_id:client_secret`. `client_secret_post` sends `client_id` and `client_secret` in the form body. The client must use the method it was created with.
+
+```bash
+# Form-encode the id and secret before base64. A raw colon join breaks when either value contains '%' or ':'.
+AUTH=$(node -e 'const [id, secret] = process.argv.slice(1); process.stdout.write(Buffer.from(`${encodeURIComponent(id)}:${encodeURIComponent(secret)}`).toString("base64"))' "$CLIENT_ID" "$CLIENT_SECRET")
+curl -X POST https://api.example.com/oauth/token \
+  -H "Authorization: Basic $AUTH" \
+  -d grant_type=client_credentials
+```
+
+The response is an `mcpat_…` access token and no refresh token. It acts as `userId`, with `credential: "oauth"`. Disabling that user, or bumping `tokenEpoch`, ends the token the same way it ends an authorization-code token. `McpOAuthClient.revoke(clientId)` ends every token that client holds, and a revoked client cannot start a new authorization or token grant. `deleteOne`, `findOneAndDelete`, and `deleteMany` do the same. `bulkWrite` skips those hooks, so use `revoke` when a bulk write removes clients.
+
+## 4. Check it
+
+```bash
+curl -i -X POST https://api.example.com/mcp \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+# HTTP/1.1 401 … WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"
+
+curl https://api.example.com/.well-known/oauth-authorization-server
+```
+
+## What changes on `/mcp`
+
+- Every request that cannot be authenticated, including `initialize` and `tools/list`, gets the 401 challenge. A rejected credential adds `error="invalid_token"` so clients refresh.
+- JWTs, Better Auth sessions, and `mcp_` service tokens keep working.
+- Tools see the approving user. `getCurrentRequestContext()?.credential` is `"oauth"`, so permission code can treat an agent's token differently from the user's own session (for example, no admin bypass). See [Request credential](../reference/api.md#request-credential).
+- Scopes are not enforced for you. A token can call every tool its user can, whatever scope it was granted. If `scopesSupported` lists scopes with different meanings (for example `["read", "write"]`), add `requireOAuthScope("write")` to the permissions of the methods and actions that need it. The granted scopes are in `getCurrentRequestContext()?.oauthScopes`.
+
+## Revoking access
+
+- The client revokes with `POST /oauth/revoke`. Revoking a refresh token ends the whole chain.
+- Disabling the user stops their tokens at the next call.
+- A password reset, Better Auth password change, or session revocation (anything that bumps `tokenEpoch`) ends every grant approved before it: the next `/mcp` call, refresh, or code exchange fails and the chain is revoked. The user reconnects the client.
+- Server-side, revoke everything a user granted with `McpOAuthToken.updateMany({userId, revokedAt: {$exists: false}}, {$set: {revokedAt: DateTime.now().toJSDate()}})`.
+
+Refresh tokens rotate on every use. If an old refresh token comes back, Terreno assumes it leaked and revokes every token issued from that approval; the user reconnects the client. The revoke is final: Terreno records the revoked approval, so a refresh or code exchange that was already in flight cannot issue a new token for it.
+
+## Security notes
+
+- Public clients use PKCE `S256` only. `plain` PKCE is rejected. Confidential clients use `client_credentials` with `client_secret_basic` or `client_secret_post`. `private_key_jwt` is not supported. Dynamic registration cannot create a confidential client.
+- Tokens, codes, and refresh tokens are stored as SHA-256 hashes.
+- Registration, authorize, token, and revoke count against the `auth` [rate-limit](rate-limiting.md) bucket. Turn rate limiting on in production, since registration is unauthenticated.
+- If a browser-based client (such as the MCP Inspector) runs discovery from another origin, allow that origin in `corsOrigin`.
+
+To put `/mcp` on the public internet behind a Cloudflare Tunnel, see [Expose an MCP server safely](expose-mcp-server-safely.md).

package/dist/docs/versioned/58.0.0/how-to/expose-mcp-server-safely.md

@@ -0,0 +1,140 @@
+# Expose an MCP server safely
+
+Put a Terreno backend's `POST /mcp` on the public internet with OAuth 2.1 for interactive clients, service tokens for static-key clients, and a Cloudflare Tunnel in front, so no inbound port is open on the host. The admin console stays behind Cloudflare Access.
+
+This guide fits any Terreno backend with MCP tools. It is written for the single-binary MCP server from the `bootstrap-mcp-server` skill, which serves `/mcp` and the admin console (including its OAuth consent screen at `/console/oauth/consent`) from one origin.
+
+## Prerequisites
+
+- A Terreno backend with at least one MCP tool ([Expose MCP tools](expose-mcp-tools.md))
+- A domain on Cloudflare, for example `example.com`, and `cloudflared` on the host that runs the backend
+- A hostname for the server, for example `mcp.example.com`
+
+## What is public and what is not
+
+| Path | Who calls it | Exposure |
+| --- | --- | --- |
+| `POST /mcp` | MCP clients | Public. Every request needs a Bearer credential. |
+| `/.well-known/oauth-protected-resource/mcp`, `/.well-known/oauth-authorization-server` | MCP clients during discovery | Public |
+| `/oauth/authorize`, `/oauth/token`, `/oauth/register`, `/oauth/revoke` | MCP clients and the user's browser | Public, rate limited |
+| `/console` (including `/console/oauth/consent`), `/api/auth` | Operators, and any user approving an OAuth connection (they sign in and approve in the console) | Behind Cloudflare Access when every OAuth approver is in the Access policy; otherwise public, guarded by Better Auth and the `admin` check |
+| `/admin` | The console's admin API | Behind Cloudflare Access when `/console` is |
+| `/health` | Uptime checks | Public |
+
+MCP clients cannot complete a Cloudflare Access login, so the first three rows must bypass Access. Everything else does not need to.
+
+## 1. Pick the credential for each client
+
+| Client | Credential | Guide |
+| --- | --- | --- |
+| Claude.ai custom connectors, ChatGPT connectors | OAuth 2.1 access token (`mcpat_…`) | [Enable MCP OAuth](enable-mcp-oauth.md) |
+| Perplexity, Cursor, Claude Code, MCP Inspector | Service token (`mcp_…`) | [Connect an MCP client with a service token](connect-mcp-service-token.md) |
+| A headless service you run | OAuth client credentials | [Enable MCP OAuth](enable-mcp-oauth.md#headless-clients-client-credentials) |
+
+Every credential acts as one user and gets that user's MCP permissions. Mint service tokens for the person who uses them, not for an admin account.
+
+## 2. Configure the backend for a public origin
+
+```typescript
+const publicUrl = "https://mcp.example.com";
+
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {enabled: true, publicMcpUrl: publicUrl},
+  mcpOAuth: {
+    allowedRedirectHosts: ["claude.ai", "chatgpt.com"],
+    consentUrl: `${publicUrl}/console/oauth/consent`,
+    dynamicClientRegistration: true,
+    enabled: true,
+    issuer: publicUrl,
+  },
+  rateLimit: {store: "memory", trustProxy: "loopback"}, // cloudflared on the same host
+});
+```
+
+- `issuer` must be the exact origin clients reach. Discovery documents, the `WWW-Authenticate` challenge, and token audiences are built from it. If it says `http://localhost:4000`, every remote client fails discovery.
+- Keep `allowedRedirectHosts` to the clients you support. With dynamic client registration on, anyone can register a client, and this list is what stops a registered client from sending authorization codes to a host you did not choose.
+- Turn rate limiting on. Registration and token requests are unauthenticated.
+- Set `trustProxy` for the proxy in front of the app. With `cloudflared` on the same host, every request arrives from `127.0.0.1`; `"loopback"` tells Express to read the client address from `X-Forwarded-For` instead. Confirm with one request that `req.ip` is your public address. Without it, every visitor shares one rate-limit bucket.
+- Set `BETTER_AUTH_URL` to the same public origin so console sign-in cookies are issued for it.
+
+## 3. Create a named tunnel
+
+Use a named tunnel. A quick tunnel (`cloudflared tunnel --url …`) gets a new `trycloudflare.com` hostname on every run, so the `issuer`, the discovery documents, and every client registered against the old hostname break. Cloudflare documents quick tunnels as a testing tool.
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create mcp
+cloudflared tunnel route dns mcp mcp.example.com
+```
+
+Write `~/.cloudflared/config.yml`:
+
+```yaml
+tunnel: mcp
+credentials-file: /home/<user>/.cloudflared/<tunnel-id>.json
+ingress:
+  - hostname: mcp.example.com
+    service: http://127.0.0.1:4000
+  - service: http_status:404
+```
+
+Run it as a service (`sudo cloudflared service install`), and check:
+
+```bash
+curl -s https://mcp.example.com/health
+curl -si -X POST https://mcp.example.com/mcp | grep -i www-authenticate
+```
+
+The second command prints `WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"`. If the URL in it is not your public hostname, fix `issuer`.
+
+## 4. Close the direct path
+
+The tunnel makes an outbound connection, so the backend needs no inbound port. Block the backend port (4000 above) at the host firewall so the only way in is through Cloudflare, where Access and Cloudflare's own protections apply. Do not port-forward it from a router.
+
+## 5. Put the console behind Cloudflare Access
+
+In Cloudflare Zero Trust, add a **self-hosted** Access application for `mcp.example.com` with these paths, and an Allow policy for your operators' emails or identity-provider group:
+
+- `/console`
+- `/admin`
+- `/api/auth`
+
+That works only when every user who approves an OAuth connection is in the policy, because approving needs the console's consent screen, its sign-in page, and Better Auth. When people outside the policy connect clients too, leave `/console` and `/api/auth` out of the Access application and rely on Better Auth sign-in and the `admin` check. You can still keep `/admin` behind Access, since only operators (who are in the policy) call it.
+
+Do not add `/mcp`, `/.well-known`, or the other `/oauth/*` paths. An Access application on the bare hostname covers them too, so scope it to paths.
+
+Access is a second layer, not a replacement: the admin routes still require `admin: true`, and the console still requires a Better Auth session.
+
+## 6. Connect a client and check it
+
+1. Claude.ai: **Settings → Connectors → Add custom connector**, paste `https://mcp.example.com/mcp`, connect, approve on the consent page.
+2. If you registered `mcpAdminModels()` ([Manage MCP from the admin panel](manage-mcp-in-admin.md)), open **MCP OAuth clients** and **MCP OAuth connections** in the console and confirm the new client and connection.
+3. Static-key client: mint a token with `POST /mcp/service-tokens` (signed in as that user), then run `tools/list` with `Authorization: Bearer mcp_…`.
+
+## Revoking access
+
+- One service token: delete it on **MCP service tokens**, or the owner calls `DELETE /mcp/service-tokens/<id>`.
+- Every MCP credential one user holds: run the `mcp-sign-out-everywhere` admin script.
+- One OAuth connection: delete it on **MCP OAuth connections**, or have the client call `/oauth/revoke`.
+- Everything a user holds: disable the user, or reset their password or revoke their sessions (both bump `tokenEpoch`). Their OAuth grants and service tokens stop working on the next request. See [Enable MCP OAuth](enable-mcp-oauth.md#revoking-access).
+- Cut all traffic at once: stop the tunnel (`sudo systemctl stop cloudflared`).
+
+## Security checklist
+
+- [ ] `issuer` and `BETTER_AUTH_URL` equal the tunnel hostname
+- [ ] Named tunnel, not a quick tunnel
+- [ ] Backend port closed to inbound traffic
+- [ ] `rateLimit` on, with `trustProxy` set so `req.ip` is the visitor, not the proxy
+- [ ] `allowedRedirectHosts` lists only supported clients
+- [ ] Access covers `/console` and `/api/auth` only when every OAuth approver is in the policy (`/admin` can always be covered), and never `/mcp`, `/.well-known`, or `/oauth/*`
+- [ ] MCP tools expose only the methods each model needs (`mcp: {methods: ["list", "read"]}` unless writes are intended)
+- [ ] Credentials are minted per person, never shared from an admin account
+
+## Related
+
+- [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md)
+- [Connect an MCP client with a service token](connect-mcp-service-token.md)
+- [Expose MCP tools](expose-mcp-tools.md)
+- [Manage MCP from the admin panel](manage-mcp-in-admin.md)
+- [Rate limiting](rate-limiting.md)

package/dist/docs/versioned/58.0.0/how-to/expose-mcp-tools.md

@@ -0,0 +1,252 @@
+# Expose Model Context Protocol Tools
+
+Turn a `modelRouter` model into Model Context Protocol (MCP) tools that an LLM can call, reusing the permissions, query filters, population, and lifecycle hooks you already declared for REST.
+
+## Prerequisites
+
+- A working Terreno backend using `TerrenoApp`
+- At least one model registered with `modelRouter`
+
+## Steps
+
+### 1. Add an `mcp` config to a model router
+
+```typescript
+import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  mcp: {
+    excludeFields: ["internalNote"],
+    maxLimit: 25,
+    methods: ["list", "read", "create", "update", "delete"],
+  },
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    delete: [Permissions.IsOwner],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+  },
+  queryFields: ["completed", "title"],
+  queryFilter: OwnerQueryFilter,
+});
+```
+
+`methods` defaults to `["list", "read"]`, and `maxLimit` defaults to 50. A method whose `permissions` array is empty is never exposed as a tool, so REST and MCP cannot drift apart.
+
+### 2. Start the server
+
+`TerrenoApp` mounts `POST /mcp` automatically as soon as any model has an `mcp` config. Every other verb on `/mcp` returns a JSON-RPC 405. No extra registration is needed.
+
+Tools are named `{prefix}_{method}` — `todos_list`, `todos_read`, and so on.
+
+The endpoint speaks the `2026-07-28` MCP revision through the TypeScript SDK v2
+`createMcpHandler`. It is stateless: every request carries its protocol version,
+client identity, and capabilities, so requests can land on any backend instance.
+The SDK's stateless legacy fallback remains enabled, so 2025-era clients continue
+to work while clients migrate.
+
+### 3. Call the tools
+
+Point any MCP client at `POST /mcp`. Auth order on the Bearer header is:
+
+1. `mcp_…` service token, when `mcpServiceTokens` is enabled
+2. `mcpat_…` OAuth access token, when `mcpOAuth` is enabled
+3. Better Auth session
+4. JWT
+
+The credential type that won is recorded as `getCurrentRequestContext()?.credential` (`"mcp-service-token"`, `"oauth"`, `"better-auth-session"`, or `"jwt"`), so a permission function can refuse delegated agent tokens where it would trust the user's own session. Remote clients that need OAuth (Claude.ai connectors, ChatGPT apps) are covered in [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md).
+
+The resolved user is what permission checks run against, so an LLM never sees more than that user could see over REST. Mint and paste a static key with [Connect an MCP client with a service token](connect-mcp-service-token.md).
+
+`initialize` and `tools/list` are the unauthenticated catalog (unless `mcpOAuth` is enabled, which makes every unauthenticated `/mcp` request a 401 challenge). Identity is enforced on `tools/call`. GET `/mcp` is Streamable HTTP **405** (`Method not allowed.`) — there is no GET SSE stream; Perplexity still uses that 405 as a successful probe.
+
+Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP. Service tokens are MCP-only: they are rejected on `/mcp/service-tokens` and are not accepted on REST, sync, or admin.
+
+To run the same tools in-process (for example inside a chat route), use `getMCPTools`:
+
+```typescript
+import {getMCPTools} from "@terreno/ai";
+
+const tools = getMCPTools(req.user);
+```
+
+To list the signed-in user's tools in an app, use `useMCPTools` from
+`@terreno/syncdb/mcp` with the same auth provider you pass to `createSyncDb`:
+
+```typescript
+import {useMCPTools} from "@terreno/syncdb/mcp";
+import {authProvider} from "@/store/syncdb";
+
+const {tools, isLoading, error, refetch} = useMCPTools({authProvider});
+```
+
+The hook reads the token from `authProvider.getToken()` on every fetch, so Better Auth
+sessions work as well as JWT. It uses the official MCP v2 client with automatic version
+negotiation; the SDK supplies the `2026-07-28` `_meta` envelope and the required
+`Mcp-Method` / `Mcp-Name` routing headers. Install `@modelcontextprotocol/client` in the app (optional peer of
+`@terreno/syncdb`).
+
+## Naming tools
+
+The default prefix is the lowercase model name run through a simple pluralizer: `Todo` → `todos`, `Category` → `categories`, `Status` → `statuses`. Irregular nouns need an explicit prefix:
+
+```typescript
+mcp: {toolPrefix: "people"} // person_list -> people_list
+```
+
+## Filtering list results
+
+Only fields listed in `queryFields` can be filtered, exactly as in REST. A filter value may be an exact value or an operator object:
+
+```json
+{"completed": false, "title": {"$in": ["Buy milk", "Walk dog"]}}
+```
+
+Allowed operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$all`, `$size`, `$exists`, and `$regex` (with `$options`). Operators that can execute code or ignore indexes — `$where`, `$expr`, `$function`, `$accumulator`, `$jsonSchema`, `$text` — are rejected with an error rather than silently dropped, so the model can correct itself.
+
+Filters can be combined with top-level `$and` / `$or`, whose branches are validated against `queryFields` too:
+
+```json
+{"$or": [{"completed": true}, {"title": {"$regex": "^Urgent"}}]}
+```
+
+`queryFilter` still runs after the filter is built, so an `OwnerQueryFilter` keeps scoping results to the calling user no matter what the LLM sends.
+
+## Populating references
+
+Population comes from the model router's `populatePaths`, exactly as it does over REST. A tool may pass `populate` to request a **subset** of those declared paths — it can never introduce a new one, so the `fields` allowlist on each declared path always applies and a caller cannot pull back a whole referenced document:
+
+```typescript
+populatePaths: [{fields: ["name", "email"], path: "ownerId"}],
+```
+
+`{"populate": "ownerId"}` is accepted; anything undeclared is refused with an error listing the allowed paths. Models with no `populatePaths` don't get a `populate` parameter at all.
+
+## Hiding fields
+
+`excludeFields` removes fields from both the generated tool schemas and the responses:
+
+- A bare name (`"hash"`) is removed at **every depth**, including inside arrays and populated refs, so a redacted name cannot leak through a nested document.
+- A dot path (`"metadata.secretKey"`) removes exactly that location, following arrays of subdocuments element-wise.
+
+The list tool's `sort` argument accepts only the router's sortable fields (`queryFields`, fields in the router's `sort`, and `sortFields`) minus `excludeFields`. Sorting on any other field returns an error that lists the allowed fields, because result order would reveal the hidden values.
+
+## Customizing responses
+
+`mcpResponseHandler` shapes MCP responses independently of the REST `responseHandler`, which is useful for returning compact summaries to an LLM:
+
+```typescript
+mcp: {
+  mcpResponseHandler: async (value, method) => {
+    if (Array.isArray(value)) {
+      return value.map((todo) => ({id: String(todo._id), title: todo.title}));
+    }
+    return {id: String(value._id), title: value.title};
+  },
+}
+```
+
+`excludeFields` is applied after your handler runs.
+
+## Lifecycle hooks
+
+`preCreate`, `postCreate`, `preUpdate`, `postUpdate`, `preDelete`, and `postDelete` all run for MCP calls. An MCP tool call is JSON-RPC rather than HTTP, so `createMCPRequest` builds a stub Express-shaped `request` (`MCPRequest`):
+
+- `user` — the authenticated MCP user
+- `body` — the hook-stage payload after write denylist + transform, not the raw tool args (on delete, `id` is in `body`, not `params`)
+- `headers` / `query` / `params` — always `{}` (MCP does not forward HTTP headers)
+- `isMCPRequest` — `true`
+
+REST `responseHandler` gets the same stub with an empty `body`.
+
+```typescript
+import type {MCPRequest} from "@terreno/api";
+
+preCreate: (body, req) => {
+  if ((req as unknown as MCPRequest).isMCPRequest) {
+    // e.g. tag records created by an assistant
+    return {...body, source: "assistant"};
+  }
+  return body;
+},
+```
+
+A hook that reads `req.headers` or `req.query` gets an empty object instead of a crash, but anything genuinely HTTP-specific (cookies, IP address) is unavailable — branch on `isMCPRequest` when that matters.
+
+## Logging and error reporting
+
+Every generated tool call emits a structured backend audit log with stable
+`mcpTool`, `mcpMethod`, and `mcpModel` labels plus the active Terreno request
+context (`requestId`, `userId`, and trace fields when present):
+
+- successful calls log at `info` with `durationMs`
+- expected refusals (permissions, not found, invalid filters) log at `warn`
+- caught database, transform, and lifecycle-hook failures log at `error`
+
+When `USE_SENTRY_LOGGING=true`, expected failures are mirrored as Sentry logs.
+Unexpected exceptions and caught internal causes are also captured with
+`Sentry.captureException`, preserving their original stack. The client still
+receives the stable MCP error text — internal exceptions and stack traces stay
+server-side. Tool arguments are not logged.
+
+## Actions as tools
+
+A verb that is not CRUD belongs in a [modelRouter action](../explanation/model-router-actions.md). Add `mcp` to the action to expose the same implementation as a tool, instead of writing it twice:
+
+```typescript
+export const todoRouter = modelRouter("/todos", Todo, {
+  collectionActions: {
+    bulkComplete: {
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      handler: async ({body, user}) => completeTodos(body.ids, user),
+      mcp: {description: "Mark several todos complete", name: "todos_bulk_complete"},
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+    },
+  },
+  instanceActions: {
+    markComplete: {
+      handler: async ({doc}) => markComplete(doc),
+      mcp: {name: "todos_mark_complete"},
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+    },
+  },
+  permissions: { /* CRUD */ },
+});
+```
+
+- `todos_mark_complete` takes `{id}`; an instance action's tool input is `{id, ...body}` (or `{id, ...query}` for GET). `todos_bulk_complete` takes `{ids}`.
+- The tool runs the action's own `permissions` and RBAC `access`, before and after loading the document, exactly as REST does. It does not need `mcp` on the router, and the router's CRUD permissions do not apply.
+- The handler sees `req.isMCPRequest === true`. Its return value is the tool's JSON text. Touching `res` fails the call, so return values instead of writing to `res`.
+- `body` / `query` must be a `z.object()`, and instance actions cannot define `id` in it. Tool names must be unique; a duplicate fails at boot.
+
+Audit log lines for action tools carry `mcpTool`, `mcpModel`, and `mcpAction` labels.
+
+## Custom tools
+
+CRUD tools cover one model at a time, and actions cover one model's verbs. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
+
+```typescript
+import {registerMCPTool} from "@terreno/api";
+import {z} from "zod";
+
+registerMCPTool({
+  name: "users_todo_statuses",
+  description: "List every user with each of their todos and completed status. Admin only.",
+  zodSchema: z.object({}).strict(),
+  handler: async (_args, user) => {
+    if (!user?.admin) {
+      return {
+        content: [{type: "text", text: JSON.stringify({error: "Permission denied: admin required"})}],
+        isError: true,
+      };
+    }
+    // load users + todos and return JSON text
+    return {content: [{type: "text", text: JSON.stringify({users: []})}]};
+  },
+});
+```
+
+The example backend registers this as `users_todo_statuses` from `example-backend/src/api/usersTodoStatus.ts`.

package/dist/docs/versioned/58.0.0/how-to/generate-the-client-sdk.md

@@ -0,0 +1,33 @@
+# Generate the client SDK
+
+Run this after any backend change to routes, models, permissions, or OpenAPI docs. The
+backend must serve `/openapi.json` (Terreno `TerrenoApp` / `setupServer` does).
+
+1. Start the backend: `bun run backend:dev` (port 4000).
+2. Generate both SDK files from the app's frontend package:
+
+```bash
+bunx terreno-syncdb-codegen \
+  --schema http://localhost:4000/openapi.json \
+  --out ./store/syncDbSdk.ts \
+  --api-out ./store/apiSdk.ts \
+  --config ./syncdb-codegen.json
+```
+
+3. Commit both generated files. Never edit them by hand.
+
+| File | Holds | Use for |
+|------|-------|---------|
+| `store/syncDbSdk.ts` | Collection hooks + `SYNC_COLLECTIONS` | Synced collections (`useTodos`, `useCreateTodo`) |
+| `store/apiSdk.ts` | Typed query/mutation hooks + request builders | Every other route (`useGetAuthMeQuery`, `usePostAuthForgotPasswordMutation`) |
+
+A route missing from `apiSdk.ts` is missing from the OpenAPI spec. Document it in the
+backend (modelRouter actions are documented automatically; hand-written routes use
+`createOpenApiBuilder`) and regenerate. To leave routes out, add `excludePaths` to
+`syncdb-codegen.json`:
+
+```json
+{"excludePaths": ["/admin/", "^/internal/"]}
+```
+
+Reference: [`@terreno/syncdb` codegen](../reference/syncdb.md#codegen).

package/dist/docs/versioned/58.0.0/how-to/github-actions-ci.md

@@ -0,0 +1,41 @@
+# GitHub Actions CI (Terreno)
+
+CircleCI is the CI/CD of record; see [CircleCI](circleci.md). The GitHub
+Actions CI and deploy workflows below are disabled
+(`push.branches-ignore: ["**"]`) and kept only for rollback. This page
+describes how they behaved if one is ever re-enabled.
+
+## Docs site (`docs-deploy.yml`)
+
+`Build docs site` is often the longest PR job because TypeDoc regenerates API
+pages. The site builds only the current docs tree; `website/versioned_docs/` is
+markdown for the MCP server.
+
+PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
+`master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
+
+| Behavior | PR preview | `master` production |
+| --- | --- | --- |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted | Prebuilt archives unpacked under `/<version>/` |
+| JS minify | Off | On |
+| Local search index | Skipped | Built |
+| Generated API + component MDX | Restored from cache when `api`/`ui` hashes match | Same cache, then full generate on miss |
+| TypeDoc workspace `tsc` | Once per generate | Same |
+| Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
+
+Do not rely on `/57.1.0/…` URLs in a PR deploy preview.
+
+## Other high-cost jobs
+
+| Workflow | What we skip or reuse |
+| --- | --- |
+| `e2e-ci`, `admin-spa-ci`, `admin-spa-integration` | Playwright Chromium under `~/.cache/ms-playwright`, keyed on `bun.lock`. E2E shards share one compile job (`workspace-dist` artifact) so required check names stay `E2E · <spec>`. |
+| `fingerprint-gate` | Master iOS/Android hashes cached per `pull_request.base.sha` (skips a second `bun run compile`) |
+| `maestro-e2e` | Demo export + static server only when `demo/`, `ui/`, or `.maestro/flows/demo/` change |
+| `example-backend-docker` | Buildx runs only when the image recipe changes (`Dockerfile`, lockfile, `package.json`). Source-only PRs skip; CD preview deploy still builds the image. `load: true` stays off. |
+| `cd` Cloud Run deploys | Runs a local wrapper around `google-github-actions/deploy-cloudrun` that retries only the transient GitHub WIF subject-token timeout, up to three attempts; IAM, image, and configuration failures fail immediately. The backend preview runs for every example-frontend PR preview, including frontend-only changes, so the Netlify build targets an isolated `pr-<number>` backend instead of production. The frontend deploy waits for that backend's healthy `/health` response before publishing to Netlify, and per-PR concurrency cancels duplicate deploys to the same alias. CD runs the built container against the configured Secret Manager values, including the Cloud Tasks `JOBS_*` env, and requires a healthy `/health` response before pushing or deploying. Preview Cloud Run uses `--memory=1Gi` and `--cpu-boost`, overwrites revision secrets, and binds `PORT` before MongoDB connect. Before deploy it rebuilds traffic with `--set-tags` / `--clear-tags` so a not-Ready tagged revision is omitted (`--remove-tags` leaves that revision in the spec and Cloud Run rejects the update). It then deploys `--no-traffic` without `--tag`, sets `--revision-suffix=pr<n>-<run_id>-<run_attempt>`, and tags the new Ready revision afterward. |
+| Bun install | `.github/actions/setup-bun-workspace` pins Bun `1.4.4` and runs `bun install --frozen-lockfile` with no `~/.bun/install/cache`. CircleCI measurements: cache restore (~15–73s) exceeded the install savings (~9s). See [circleci.md](circleci.md#bun-install-is-uncached). |
+
+Playwright e2e on CircleCI groups specs into five shards (`e2e-auth`,
+`e2e-app`, `e2e-admin-core`, `e2e-admin-table`, `e2e-syncdb`). The retained GHA
+twin still lists one spec per matrix entry for rollback.