@terreno/mcp 57.20.0 → 58.0.0-beta.1

package/src/docs/versioned/next/how-to/configure-better-auth.md

@@ -4,7 +4,7 @@ Set up Better Auth as the **default** authentication provider for new Terreno ap
 
 ## Overview
 
-Better Auth is the recommended authentication system for new Terreno frontends. Register `BetterAuthApp` on the backend, set `AUTH_PROVIDER=better-auth`, and wire `createBetterAuthClient` + `generateBetterAuthSlice` on the client. Pair with `betterAuthAdapter` when using `@terreno/syncdb`.
+Better Auth is the recommended authentication system for new Terreno frontends. Register `BetterAuthApp` on the backend, set `AUTH_PROVIDER=better-auth`, and on the client create the client with `createBetterAuthClient` and wrap the app in `SessionProvider`, both from `@terreno/syncdb/auth`. Pass the same client to `betterAuthAdapter` for `createSyncDb` and the API client.
 
 JWT/Passport remains available for legacy deployments (`AUTH_PROVIDER=jwt`). Both can run in parallel during migration.
 
@@ -378,17 +378,22 @@ const userSchema = new mongoose.Schema(
 ### 1. Create Better Auth Client
 
 ``````typescript
-import {createBetterAuthClient} from "@terreno/rtk";
+// lib/betterAuth.ts
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
+import {baseUrl} from "@terreno/syncdb/config";
 
 // `scheme` is the app's deep-link scheme (required).
 export const authClient = createBetterAuthClient({
-  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
-  scheme: "yourapp",
+  baseURL: baseUrl,
+  scheme: "yourapp", // app.json "scheme", for OAuth deep links
+  storagePrefix: "yourapp",
 });
 ``````
 
-On web the client authenticates with Better Auth's session cookie. When the web frontend and
-the API are on different sites, use [bearer mode](#frontend-and-api-on-different-sites).
+The client stores its session in `expo-secure-store` on native and AsyncStorage on web.
+Install them in the app with `bunx expo install expo-secure-store @react-native-async-storage/async-storage`.
+
+Install them in the app with `bunx expo install expo-secure-store @react-native-async-storage/async-storage`.
 
 A cookie-authenticated `POST`, `PUT`, `PATCH`, or `DELETE` to any Terreno route is
 authenticated only when its `Origin` (or, without one, its `Referer`) is in `trustedOrigins` or
@@ -406,7 +411,7 @@ the matching Better Auth client plugins and their typed methods:
 
 ``````typescript
 import {router} from "expo-router";
-import {createBetterAuthClient} from "@terreno/rtk";
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
 
 export const authClient = createBetterAuthClient({
   baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
@@ -447,27 +452,54 @@ Notes:
 - **Server first.** A client feature only adds client methods. Turn the feature on in
   `BetterAuthConfig` too, or its calls answer 404.
 
-### 2. Add Session Redux Slice
+### 2. Provide the Session
+
+Wrap the app in `SessionProvider` and read the session with `useSession()`. No Redux store is
+needed.
+
+``````tsx
+// app/_layout.tsx
+import {SessionProvider, useSession} from "@terreno/syncdb/auth";
+import {authClient} from "@/lib/betterAuth";
+import {syncDb} from "@/store/syncdb";
+
+const RootLayout = (): React.ReactElement => (
+  <SessionProvider authClient={authClient} syncDbs={[syncDb]}>
+    <RootNavigator />
+  </SessionProvider>
+);
+
+const RootNavigator = (): React.ReactElement => {
+  const {userId, isLoading} = useSession();
+  if (isLoading) {
+    return <Spinner />;
+  }
+  return userId ? <AppTabs /> : <LoginScreen />;
+};
+``````
+
+The provider reads the session on start and follows Better Auth's session signal, so a
+sign-in or sign-out updates `useSession()` on its own. `logout()` from `useSession()` signs
+out of Better Auth, signs out each `syncDbs` client (create it with `wipeOnSignOut: true` to
+wipe local data), runs `onLogout`, and clears the session.
+
+After an email sign-in, call `refresh()` to resolve the user right away:
 
 ``````typescript
-import {generateBetterAuthSlice} from "@terreno/rtk";
-import {configureStore} from "@reduxjs/toolkit";
-import {authClient} from "./authClient";
-import {api} from "./sdk"; // the app's generated RTK Query API
-
-// Purge the SDK's cached responses on logout or user switch.
-const betterAuth = generateBetterAuthSlice({apisToReset: [api], authClient});
-
-export const store = configureStore({
-  reducer: {
-    betterAuth: betterAuth.reducer, // selectors read `state.betterAuth`
-    // ... other reducers
-  },
-  middleware: (getDefault) => getDefault().concat(...betterAuth.middleware),
-});
+const {refresh} = useSession();
 
-// Call after sign-in, sign-out, and at app startup to copy the session into Redux
-void betterAuth.syncSession(store.dispatch);
+const result = await authClient.signIn.email({email, password});
+if (!result.error) {
+  await refresh();
+}
+``````
+
+For `@terreno/syncdb`, build the auth provider from the same client:
+
+``````typescript
+import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb/auth";
+
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient));
 ``````
 
 ### 3. Add Social Login UI
@@ -476,7 +508,7 @@ Use the SocialLoginButton component:
 
 ``````typescript
 import {SocialLoginButton, Box} from "@terreno/ui";
-import {authClient} from "@/store/authClient";
+import {authClient} from "@/lib/betterAuth";
 
 const LoginScreen = () => {
   return (
@@ -524,7 +556,7 @@ Better Auth's `lastLoginMethod`, which reads a backend cookie that a cross-site
 see.
 
 ``````typescript
-import {createRememberedAccountsStore, toLoginAccountOptions, useRememberedAccounts} from "@terreno/rtk";
+import {createRememberedAccountsStore, toLoginAccountOptions, useRememberedAccounts} from "@terreno/syncdb/auth";
 import {LoginScreen} from "@terreno/ui";
 
 // One store per app, at module scope.
@@ -606,7 +638,7 @@ only the sign-in methods the server enables, and it records each sign-in in the
 [remembered accounts](#4-remember-accounts-on-this-device) store.
 
 ``````typescript
-import {createRememberedAccountsStore, TerrenoLoginScreen} from "@terreno/rtk";
+import {createRememberedAccountsStore, TerrenoLoginScreen} from "@terreno/syncdb/auth";
 import {useLocalSearchParams, useRouter} from "expo-router";
 
 export const rememberedAccounts = createRememberedAccountsStore({rememberIdentity: false});
@@ -670,18 +702,19 @@ What it does:
   the screen has to see the returned session to record it, and it navigates on by itself. Pass
   `onStepChange` to catch the screen landing on its `login` step while your app already holds a
   session (the live-session check failed), and navigate away there; example-frontend's
-  `app/login.tsx` does both, and skips re-syncing Redux in `onSignedIn` when it already holds the
-  user.
-- **Signing out.** Dispatch `generateBetterAuthSlice`'s `logout()`. It keeps the session until
-  `authClient.signOut()` answers, then clears it, so the login screen never opens while the old
-  session is still live. Meanwhile `selectBetterAuthIsSigningOut` is true: show it on the
-  sign-out control. `logout()` leaves `isLoading` alone, so the screen stays put; if your
-  navigator shows a spinner on `selectBetterAuthIsLoading`, show it only while no user is
-  loaded (`isLoading && !userId`), or a session refresh would remount the navigator on its
-  first tab. A sign-out that cannot reach the server leaves a cookie or native session in place
-  and sets the slice's `error` (`SIGN_OUT_FAILED_MESSAGE`); show it. Stop anything that calls the
-  API with the session first: example-frontend's `logout` in `store/index.ts` stops syncdb,
-  then dispatches `logout()`, and its profile screen shows both.
+  `app/login.tsx` does both, and skips `refresh()` in `onSignedIn` when the session already holds
+  the user.
+- **Signing out.** Call `logout()` from `useSession()`. It keeps the session until
+  `authClient.signOut()` answers, then signs out each `syncDbs` client (wiping local data when
+  `wipeOnSignOut` is set) and clears the session, so the login screen never opens while the old
+  session is still live. Meanwhile `isSigningOut` is true: show it on the sign-out control.
+  `logout()` leaves `isLoading` alone, so the screen stays put; if your navigator shows a
+  spinner on `isLoading`, show it only while no user is loaded (`isLoading && !userId`), or a
+  session refresh would remount the navigator on its first tab. A sign-out that cannot reach the
+  server (or that the server refuses, or that outlasts `signOutTimeoutMs`, 10 seconds by default)
+  leaves a cookie or native session in place, wipes nothing, and sets `error` to
+  `SIGN_OUT_FAILED_MESSAGE`; show it. A bearer client that has dropped its token before the
+  request signs out locally. example-frontend's profile screen shows both states.
 - **Sign-up.** The sign-up link hides when the server's sign-up is closed (`signUp: false`).
 - **No email and password.** When the server has `emailPassword` off, the form, the Sign in
   button, and the forgot-password link are left out (`LoginScreen` with `fields={[]}`), and a
@@ -765,7 +798,7 @@ every card to the Better Auth client. Each card shows only when the server's
 [`/terreno/methods`](../reference/api.md#better-auth-authentication) turns its feature on.
 
 ``````typescript
-import {TerrenoAccountSecurityScreen} from "@terreno/rtk";
+import {TerrenoAccountSecurityScreen} from "@terreno/syncdb/auth";
 import {useLocalSearchParams} from "expo-router";
 
 const Security = (): React.ReactElement => {
@@ -869,10 +902,11 @@ Safari block it. The user signs in and is signed out on the next request.
 Use bearer mode in that case. Keep cookie mode when the frontend and API share a site.
 
 ``````typescript
-import {createBetterAuthClient} from "@terreno/rtk";
+import {createBetterAuthClient} from "@terreno/syncdb/auth";
+import {baseUrl} from "@terreno/syncdb/config";
 
 export const authClient = createBetterAuthClient({
-  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  baseURL: baseUrl,
   scheme: "yourapp",
   webAuth: "bearer",
 });
@@ -904,14 +938,23 @@ Content-Security-Policy. `localStorage` is readable by any XSS on the frontend's
 outlives the tab, so a stolen or forgotten token stays usable after the person closes it.
 
 Read the stored token outside the client, without a network call, with
-`getBetterAuthBearerToken({storagePrefix?, bearerStorage?})`. Pass the same options the client
-was created with.
+`getBetterAuthBearerToken({storagePrefix?, bearerStorage?})` from `@terreno/syncdb/auth`. Pass
+the same options the client was created with. Pass it to `betterAuthAdapter` as
+`getBearerToken` so the shared `authProvider` reads the token locally instead of calling
+`get-session` on every request:
+
+``````typescript
+import {betterAuthAdapter, bridgeBetterAuthReactClient, getBetterAuthBearerToken} from "@terreno/syncdb/auth";
+
+export const authProvider = betterAuthAdapter(bridgeBetterAuthReactClient(authClient), {
+  getBearerToken: () => getBetterAuthBearerToken({storagePrefix: "yourapp"}),
+});
+``````
 
 example-frontend shows the whole setup. `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true` turns on
 bearer mode in `lib/betterAuth.ts`. `store/syncdb.ts` passes the stored token to
-`betterAuthAdapter` as `getBearerToken`, and `store/index.ts` registers that adapter with
-`setTokenSource` before it creates the store, so RTK Query, the socket and MCP tools send the
-same token. `e2e/crossSiteBearer.spec.ts` signs in from `localhost:8082` to an API on
+`betterAuthAdapter` as `getBearerToken`, and that one `authProvider` feeds syncdb (and its
+socket), the request client, and MCP tools, so they all send the same token. `e2e/crossSiteBearer.spec.ts` signs in from `localhost:8082` to an API on
 `127.0.0.1:4000` with every `set-cookie` header stripped, then reloads.
 
 ### Server requirements
@@ -938,7 +981,7 @@ same token. `e2e/crossSiteBearer.spec.ts` signs in from `localhost:8082` to an A
 ### Social sign-in in bearer mode
 
 The server adds a single-use, three-minute token to the OAuth callback's redirect, in the URL
-fragment, and the web app exchanges it for the bearer. rtk binds each exchange to a random
+fragment, and the web app exchanges it for the bearer. syncdb binds each exchange to a random
 nonce the tab stored when it started the sign-in, so a token planted in a link is never sent.
 
 1. On the server, list the web app's origin and the one page that reads the token. The origin
@@ -965,7 +1008,7 @@ nonce the tab stored when it started the sign-in, so a token planted in a link i
    navigation, never with `fetch`, an `<img>`, or an `<iframe>`:
 
    ``````typescript
-   import {signInSocialWithHandoff} from "@terreno/rtk";
+   import {signInSocialWithHandoff} from "@terreno/syncdb/auth";
 
    <SocialLoginButton
      provider="google"
@@ -988,10 +1031,12 @@ nonce the tab stored when it started the sign-in, so a token planted in a link i
    before Sentry, analytics, or other third-party scripts start:
 
    ``````typescript
-   import {completeBetterAuthOAuthHandoff} from "@terreno/rtk";
+   import {completeBetterAuthOAuthHandoff} from "@terreno/syncdb/auth";
 
-   await completeBetterAuthOAuthHandoff({client: authClient});
-   await betterAuth.syncSession(store.dispatch);
+   const stored = await completeBetterAuthOAuthHandoff({client: authClient});
+   if (stored) {
+     await refresh(); // useSession().refresh(): SessionProvider read the session before the exchange
+   }
    initSentry();
    ``````
 
@@ -1005,7 +1050,10 @@ nonce the tab stored when it started the sign-in, so a token planted in a link i
 
 4. Show sign-in errors from the query. A failed start or callback comes back with
    `?error=provider_not_found`, `?error=sign_in_failed`, or one of Better Auth's own `error=`
-   codes. The function resolves `false` and leaves `error` in the URL.
+   codes. The function resolves `false` and leaves `error` in the URL. On better-auth 1.6 (the
+   version Terreno 58 pins), a generic OAuth provider's own error (such as `access_denied`)
+   goes to the API's `{basePath}/error` page instead of `errorCallbackURL`.
+   No token is issued either way.
 
 The return page must not redirect, on the server or in the browser, before the function has
 run. A browser carries the fragment through a redirect that has none of its own, so a redirect
@@ -1018,14 +1066,14 @@ the handoff only, so a token never goes to a page on the visitor's own machine,
 start when no other origin is left in `CORS_ORIGINS`. CORS and `trustedOrigins` keep them.
 `app/login.tsx` renders `TerrenoLoginScreen` with `callbackURL="/login"` in bearer mode, so its
 social buttons start with `signInSocialWithHandoff` and come back to the same screen, which finds
-the session and records the method. `app/_layout.tsx` syncs the session only after the exchange
+the session and records the method. `app/_layout.tsx` refreshes the session only after the exchange
 resolves, and leaves a signed-in user on `/login` so the screen can record the sign-in before it
 navigates on.
 
 In an Expo Router app, run the exchange from the entry file, not from a layout. Expo Router
 copies the URL, fragment included, as soon as it is imported, and writes that copy back into
 the address bar when it routes, which would put `ott` and `handoff` back. Importing
-`@terreno/rtk` imports Expo Router too (through `@terreno/ui`). example-frontend's `index.js`
+`@terreno/ui` imports Expo Router too. example-frontend's `index.js`
 first imports `lib/oauthHandoffUrl.ts`, which has no imports and hides `handoff` and `ott` from
 the URL, then `lib/oauthHandoff.ts`, which puts the URL back and calls
 `completeBetterAuthOAuthHandoff` in the same synchronous step, then `expo-router/entry`.
@@ -1049,12 +1097,12 @@ must refuse.
 A signed-in user links Google, GitHub, or a generic OAuth provider from the Security screen. In
 cookie mode `authClient.linkSocial` does this. In bearer mode it can't: its
 `POST /link-social` fetch comes from another site, so the OAuth state cookie it needs on the
-API's origin is never set. Use `linkSocialWithHandoff` from `@terreno/rtk` instead. It needs
+API's origin is never set. Use `linkSocialWithHandoff` from `@terreno/syncdb/auth` instead. It needs
 the same `oauthHandoff` server config as social sign-in, and account linking must be on
 (`accountLinking.mode` other than `never`).
 
 ``````typescript
-import {linkSocialWithHandoff} from "@terreno/rtk";
+import {linkSocialWithHandoff} from "@terreno/syncdb/auth";
 
 const {error} = await linkSocialWithHandoff({
   callbackURL: "/settings/security", // any page on a web origin; sent as an absolute URL
@@ -1125,7 +1173,7 @@ const sessionStorageOrDefault = (): Storage | undefined => {
 };
 
 export const authClient = createBetterAuthClient({
-  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  baseURL: baseUrl,
   bearerStorage: sessionStorageOrDefault(),
   scheme: "yourapp",
   webAuth: "bearer",
@@ -1176,6 +1224,11 @@ Verify the callback URLs in your OAuth provider settings match your `BETTER_AUTH
 
 Check that `trustedOrigins` in your Better Auth config includes your app's deep link scheme (e.g., `"yourapp://"`).
 
+On native, if every request fails before it is sent after an app update, the stored cookie jar
+may hold an entry the Expo plugin cannot read. `createBetterAuthClient` drops such entries on
+read and logs `Discarded … unreadable Better Auth cookie entry`; sign in again to restore the
+session.
+
 ### Social login opens browser but doesn't redirect back
 
 Ensure your mobile app has the proper deep link configuration in `app.json`:
@@ -1220,5 +1273,6 @@ so new accounts cannot be created through the legacy `/auth/signup`.
 
 - [Authentication Architecture](../explanation/authentication.md)
 - [@terreno/api Reference](../reference/api.md#better-auth)
-- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md#better-auth-integration)
+- [@terreno/syncdb Reference: Auth](../reference/syncdb.md#auth)
+- [Upgrade from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md)
 - [Better Auth Documentation](https://better-auth.com/)

package/src/docs/versioned/next/how-to/connect-mcp-service-token.md

@@ -35,13 +35,13 @@ Cap is **10** active tokens per user. List rows show prefix (`mcp_` + eight hex
 Use a session or JWT. A service token cannot mint another token.
 
 ```bash
-curl -X POST "$API/mcp/service-tokens" \
+curl -X POST "$API/mcp/service-tokens/create" \
   -H "Authorization: Bearer $JWT" \
   -H "Content-Type: application/json" \
   -d '{"name":"Perplexity"}'
 ```
 
-Read `data.token` and `data.mcpUrl` from the JSON. List and revoke never return `token`. Do not log the secret.
+Read `data.token` and `data.mcpUrl` from the JSON. Only this create response carries `token`. List, read, revoke, and the synced `mcp/service-tokens` collection never return `token` or `tokenHash`. Do not log the secret.
 
 ## 4. Perplexity custom connector
 
@@ -104,9 +104,17 @@ The token acts as the owning user on **MCP only**. It cannot mint or list tokens
 
 ## 7. Revoke
 
-- **Owner:** Profile → MCP connections → **Revoke** on the row (`DELETE /mcp/service-tokens/:id`).
-- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete the row.
+- **Owner:** Profile → MCP connections → **Revoke** on the row (`POST /mcp/service-tokens/:id/revoke`).
+- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete or tombstone the row.
+
+The token list is a synced collection (`mcp/service-tokens`, owner-scoped), so a revoke from another device or the admin panel shows up on the owner's list as a `revokedAt` update.
 
 Revoked and expired keys fail `tools/call` immediately. Disabled user accounts are refused the same way as over HTTP.
 
+## Upgrading from 57.x
+
+58.0.0 gives `McpServiceToken` String ids. Before deploying, add the `mcp-service-token-string-ids` framework migration to your `migrations/` directory and apply it. Existing tokens keep working and keep their ids as hex strings. See [Run MongoDB migrations](run-mongodb-migrations.md#framework-migrations).
+
 A password reset, Better Auth password change, or "sign out everywhere" (`revoke-sessions` / `revoke-other-sessions`) bumps the user's `tokenEpoch` and ends every key minted before it. The keys show as revoked in the list; mint a new one for each client you still use.
+
+To put `/mcp` on the public internet behind a Cloudflare Tunnel, see [Expose an MCP server safely](expose-mcp-server-safely.md).

package/src/docs/versioned/next/how-to/create-a-terreno-app.md

@@ -58,7 +58,7 @@ cd .. && bunx create-terreno-app my-app --yes
 | Path | Purpose |
 | --- | --- |
 | `backend/` | Express/Mongoose API (`@terreno/api`, Better Auth, admin, sync) |
-| `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`, `@terreno/rtk`) |
+| `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`). No Redux: session from `@terreno/syncdb/auth`, requests through `store/apiClient.ts`, generated hooks in `store/apiSdk.ts` |
 | `Dockerfile` | Consumer backend image (`backend/` only — not the Terreno monorepo) |
 | `.dockerignore` | Excludes local env secrets, dependencies, and build output from the image context |
 | `backend/.env`, `frontend/.env` | Gitignored local-dev defaults (written on scaffold). `backend/.env` sets `NODE_ENV=development`, which turns on the dev-only `POST /__terreno/browser-logs` route |
@@ -69,6 +69,18 @@ cd .. && bunx create-terreno-app my-app --yes
 
 Generated `@terreno/*` dependencies pin to `^<create-terreno-app version>` at scaffold time.
 
+### Frontend data and session wiring
+
+| File | What it does |
+| --- | --- |
+| `frontend/lib/betterAuth.ts` | `createBetterAuthClient` from `@terreno/syncdb/auth`, pointed at `baseUrl` from `@terreno/syncdb/config` |
+| `frontend/store/syncdb.ts` | `authProvider` (Better Auth session token) and the `syncDb` client for synced collections |
+| `frontend/store/apiClient.ts` | `createApiClient` from `@terreno/syncdb/api` with the same `authProvider`, `App-Version` / `App-Platform` headers, and `getAdminAuthHeaders` for `AdminProvider` |
+| `frontend/store/apiSdk.ts` | Typed hooks for non-synced routes (`useGetAuthMeQuery`, `usePatchAuthMeMutation`, ...). The scaffold ships the `/auth/me` hooks; `bun run sdk` regenerates the file for every route |
+| `frontend/app/_layout.tsx` | `ApiClientProvider` + `SessionProvider` (`useSession()` gives `userId`, `isLoading`, `refresh`, `logout`) + `SyncDbProvider`; starts `syncDb` after login |
+
+`bun run sdk` runs the `api-sdk` script: `terreno-syncdb-codegen --schema $OPENAPI_URL --api-out ./store/apiSdk.ts` (default schema `http://localhost:4000/openapi.json`). Never edit `apiSdk.ts` by hand.
+
 ## 2. Install dependencies
 
 ```bash
@@ -122,7 +134,7 @@ Health check: `curl http://localhost:4000/health` → `"healthy":true`.
 Terminal 2 — web UI (port `8082`):
 
 ```bash
-(cd frontend && bun run sdk)   # after backend is up; regenerates OpenAPI hooks
+(cd frontend && bun run sdk)   # after backend is up; regenerates store/apiSdk.ts
 (cd frontend && bun run web)
 ```
 

package/src/docs/versioned/next/how-to/debug-with-mcp.md

@@ -399,26 +399,21 @@ terreno logs --entries 100 --level error --sources backend,browser,metro,app
 
 ### Inspect client state
 
-Check authentication and non-synced RTK Query cache state:
+Client state lives in `@terreno/syncdb`: synced collections in the local store, and the session in
+`SessionProvider`. There is no Redux store to inspect (the `get_rtk_state` tool and
+`terreno state --slice` were removed with `@terreno/rtk` in Terreno 58). Use the SyncDB tools in
+the next step for data, and `read_logs` / `last_error` above for failed request-client calls.
 
-```json
-{"name":"get_client_state","arguments":{"slice":"rtk","query":"todos"}}
-```
-
-The tool reads `globalThis.__TERRENO_STORE__` registered by the app, using CDP when the MCP process
-cannot access the app heap directly. It also detects a SyncDB client created with `debug: true`, and
-its `layer` field reports what it found: `rtk`, `syncdb`, `syncdb+rtk` (both payloads returned), or
-`none` (with a setup hint). On web it returns `none`, as shown in step 5. `get_rtk_state` is a
-deprecated alias for one release. `slice: "auth"` prefers the Better Auth slice and falls back to
-legacy JWT auth; pass `betterAuth` to request that exact slice.
+CLI equivalent of `get_syncdb_state`:
 
 Sensitive fields whose names include `password`, `token`, `secret`, `authorization`, or `cookie` are
-returned as `[REDACTED]`; use this summary to inspect cache state, never to retrieve credentials.
+returned as `[REDACTED]` in MCP summaries; use them to inspect state, never to retrieve credentials.
+
 
 The CLI equivalent is:
 
 ```bash
-terreno state --slice rtk --query todos
+terreno state --collection todos
 ```
 
 ### Inspect and change SyncDB state

package/src/docs/versioned/next/how-to/enable-mcp-oauth.md

@@ -64,6 +64,10 @@ Booting with an issuer that has a path, a consent URL that is not a URL, or regi
 
 ## 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`).
@@ -183,3 +187,5 @@ Refresh tokens rotate on every use. If an old refresh token comes back, Terreno
 - 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/src/docs/versioned/next/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/src/docs/versioned/next/how-to/expose-mcp-tools.md

@@ -71,10 +71,21 @@ import {getMCPTools} from "@terreno/ai";
 const tools = getMCPTools(req.user);
 ```
 
-`useMCPTools()` from `@terreno/rtk` uses the official MCP v2 client with automatic
-version negotiation. It no longer constructs JSON-RPC or parses SSE responses by
-hand; the SDK supplies the `2026-07-28` `_meta` envelope and required
-`Mcp-Method` / `Mcp-Name` routing headers.
+To list the signed-in user's tools in an app, use `useMCPTools` from
+`@terreno/syncdb/app` with the same auth provider you pass to `createSyncDb`:
+
+```typescript
+import {useMCPTools} from "@terreno/syncdb/app";
+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