everyapp 0.2.2 → 0.3.0-rc.1

package/skills/everyapp/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: everyapp
+description: Create, run, deploy and manage private web apps on Cloudflare with everyapp (Every App). Use before running any everyapp command, to deploy an app, set a secret, query its database, check the Gateway, or answer any "how do I" question about Every App.
+---
+
+everyapp: self-hosted platform for private web apps on Cloudflare. While
+publishing is paused the command is `pnpm everyapp` (never `npx everyapp`),
+run from the Every App checkout or from an app's directory (its package.json
+links the CLI).
+
+Docs: two worlds. The user docs (https://everyapp.com/docs) are short and
+for the person. The agent docs are yours: https://everyapp.com/llms.txt
+lists every page with a one-line summary; a page is Markdown at its URL
+plus .md (https://everyapp.com/docs/agent/manifest.md); in a checkout they
+are landing-page/content/agent/*.md. Pages: setup (driving setup for a
+person, every handoff), cli (every command and flag), json (the --json
+protocol), errors (every code and its fix), troubleshooting (by symptom),
+status (the report, every line, and its fixes in order), manifest
+(everyapp.config.ts), identity (headers, token, env, SDK), secrets
+(secrets vs Gateway settings vs capabilities), dev (dev vs production),
+email, events (webhooks, email alerts, the signature, every event type,
+emit()), mcp (tools, connector, OAuth), deploy (the pipeline, what the policy
+check refuses), providers (API providers: the catalog, registering one,
+a spec's fields), access (Cloudflare Access), workspace (the workspace from
+the terminal and from an AI client: every command and every tool), gateway
+(everything a Gateway offers: apps vs MCP apps vs the compact MCP surface,
+people, groups and caps, the CLI by job, what to suggest next, other MCP
+servers), build (the build-every-app skill as a page), patterns (its
+example-patterns index), repo/* (security model, capabilities, runbooks).
+Step-by-step setup of each
+integration (the Gateway, Access, email, DataForSEO, Context, OpenRouter,
+OpenAI, Workers AI, Google, Microsoft 365, Slack; every catalog provider by
+id in setup/providers.md): setup/README.md beside this file.
+Answering "how do I": fetch the page for the subject and answer from it
+with the exact command or manifest field, naming the page. A failed
+command: look its code up on errors (anchor: the code, lowercased) before
+trying anything else. Never guess a flag: cli has them all.
+Building an app: the Gateway signs people in, so never build a login page
+or auth; read the user with the SDK (identity page), and scope every query
+by user.id: the Gateway admits every member of the organization. A new app
+edits everyapp.config.ts for name, resources, public, providers,
+capabilities, secrets and email (manifest page), and the Gateway gives it
+nothing it doesn't declare there. AI: list the provider, providers:
+["openai"] (or openrouter, workers-ai), and call it with the SDK's
+createGatewayFetch({ env, for: request }), a fetch for
+http://every-app-gateway.internal/api/ai/<provider>/... (an OpenAI client
+takes it as fetch, with http://every-app-gateway.internal/api/ai/openai/v1
+as baseURL; the other two base URLs and the code are on the identity
+page); the Gateway holds the key, never the app, and a provider the
+manifest doesn't list is refused provider_not_allowed 403. A capability
+(members, email, an OAuth client, DataForSEO) is listed under
+capabilities with access and a why and called with listMembers(),
+sendEmail() or integrationFetch() (secrets page); an OAuth client with
+scope sets (google-workspace, microsoft-365, slack) is listed with
+scopes: [...] and held to them; after a schema change run pnpm run
+db:generate; a value only dev needs goes in .dev.vars, never in git (dev
+page). The way back: the first row of the app's sidebar (or of its page
+header when it has no sidebar) is a muted "‹ Every App" link to
+GATEWAY_URL (aria-label "Back to Every App"), above the app's own name,
+so every app on the Gateway reads the same; put nothing else about the
+Gateway in the footer.
+
+Pass --json. One JSON event per line; "done" = success; exit 2 = show the
+user the last action_required (url, code), then run its data.rerun (the same
+command, unless it names another); exit 1 = show the error; if data.authorize
+is set, ask before using data.rerun. waiting: true = keep reading (5 min
+for the device login, up to 15 for the owner link).
+
+State:   pnpm everyapp status --json   (data.fixes says what to run when something is off;
+         data.next says what to do next: at most four { code, command | url, note, why }
+         from the Gateway's state, never repeating a fix; tell the person
+         each why and offer the command or page; data.apps[].setup says what each
+         app needs set: ready, settings, unmet (each with why and docs), and
+         command, pnpm everyapp configure <app>)
+Gateway: pnpm everyapp setup --domain <host> --json   (install, upgrade, repair;
+         a fresh install runs 5-20 min: build, certificate, then up to 15 min
+         waiting for the owner link, so give it a long timeout or background
+         it and keep reading; run data.rerun as given (a needsTerminal rerun
+         goes to the person))
+New app: pnpm everyapp create ../<id> --json   (from the every-app folder: the
+         app is its own repository beside it, linked to the checkout; a bare
+         <id> makes apps/<id> inside the checkout instead) then cd into it and
+         edit src/; the manifest is everyapp.config.ts
+Run:     pnpm everyapp dev   (long-running, human-facing: start it in the
+         background and read the printed URL; no --json; --port when 8787 is
+         taken; stop it with Ctrl-C/SIGINT to the everyapp process, never a
+         pattern kill of vite or workerd; a pnpm install or deploy meanwhile
+         rebuilds the SDK and breaks dev for a few seconds)
+Ship:    pnpm everyapp deploy --json   (from the app directory; safe to repeat;
+         also upgrades the Gateway to this checkout when it has to rebind).
+         No Gateway yet: action_required install_gateway; ask the user, run
+         its data.rerun (setup), then deploy again. done.data.publicRoutes
+         lists the routes the manifest opens to the internet without
+         sign-in; tell the person which.
+Release: someone else's app, without a clone: pnpm everyapp install
+         https://github.com/<owner>/<repo> --json (its latest release's
+         everyapp-release.tar.gz; a tarball URL or file works too). NO_RELEASE:
+         the repository publishes none; clone it, pnpm install in it, then
+         this checkout's pnpm everyapp deploy from its directory. Never
+         build a repository from its URL yourself.
+         To publish one: pnpm everyapp release, then attach the
+         tarball to a GitHub release of the app's repository, or give
+         the repository the Release workflow that does it on every push
+         (pnpm pack-for-app <app> --workflow from this checkout;
+         docs/runbooks/app-releases.md).
+Data:    pnpm everyapp db migrate (local)   pnpm everyapp db query "<sql>" [--local] --json
+         (a production write stops with CONFIRMATION_REQUIRED: add --yes only
+         if the user said so). pnpm everyapp db restore --json undoes the last
+         deploy's migrations (and every write since): only when the user asks.
+Postgres: an app with resources.hyperdrive or migrations.dialect "postgresql"
+         reads POSTGRES_DATABASE_URL (and <BINDING>_ORIGIN_URL) from
+         .everyapp/secrets.env, which the user writes; never print, commit or
+         ask for its values in chat. deploy runs drizzle-kit migrate before
+         the upload.
+Secrets: pnpm everyapp configure <app> --json   sets up an app: every setting its
+         manifest declares, each where it is held (an AI key or a capability's
+         client on the Gateway, once for every app; the app's own secrets on
+         its Worker, after its first deploy); live at once, no deploy. At a
+         terminal it shows what is set (names only), asks for each required
+         setting that isn't with a hidden prompt (why, where to get it and its
+         guide above), which member of an any-of group, then offers the
+         optional ones; from you (no prompt): NAME=value lines on stdin (one
+         per line, from a command's output) or --from-env (each unset
+         setting from the variable of its own name; stdin isn't read then).
+         A value never goes on the command line (VALUE_ON_COMMAND_LINE). One
+         name at a time: pnpm everyapp secret set NAME [--app <id>] --json
+         (the value from a hidden prompt, stdin, or --from-env VAR). The name
+         decides where it goes. A Gateway setting (OPENAI_API_KEY, EMAIL_FROM,
+         GOOGLE_WORKSPACE_CLIENT_ID, …) is set on the Gateway from any
+         directory. An app's own secret must be listed under `secrets` in its
+         everyapp.config.ts and is set after its first deploy, from the app's
+         directory or from anywhere with --app <id> (SECRET_NOT_DECLARED: add
+         it there first). secret unset NAME [--app <id>]; secret list [<app>]
+         --json (one app's settings, where each is held and whether it is set,
+         with data.app.setup; elsewhere with no app named: the Gateway's names
+         and every app's settings).
+Needs setup: read data.apps[].setup; for each unmet setting show its why and docs
+         and read its setup guide (.claude/skills/everyapp/<setup>); then run
+         setup.command, pnpm everyapp configure <app>, without a value passing
+         through the chat: tell the person to run it in their own terminal (it
+         asks for each setting with a hidden prompt and says where to get it)
+         and say when done; or drive it yourself, --json always: NAME=value
+         lines on stdin from a command's output, or --from-env for variables
+         the person exported before starting you. Never a value on the command
+         line; never ask for, print, repeat or invent a value. An app whose
+         setup.ready is false doesn't open (status shows "needs setup"; deploy
+         warns APP_NEEDS_SETUP and puts the command under next); an any-of
+         group (setup.groups) needs one member set, not all: configure asks
+         which.
+Email:   pnpm everyapp email set --sender "*@<domain>" --inbound <address> --json
+         In the app's directory, after its first deploy; nothing is deployed. --sender
+         replaces the From addresses the Gateway lets the app name (everyapp.config.ts
+         lists capabilities.email); --inbound replaces the addresses routed to its
+         email() handler (everyapp.config.ts declares email: { inbound: true }) and
+         makes the Email Routing rules now. EMAIL_ROUTING_DISABLED needs the user's
+         yes: rerun with --enable-email-routing only if they said so. email unset
+         senders|inbound clears; email show prints both.
+Access:  pnpm everyapp access on --json   (Cloudflare Access in front of the Gateway
+         and its apps: finds or creates the Zero Trust team (--team NAME when the
+         account has none: permanent, ask the user), keeps both sign-in methods
+         (Sign in with Cloudflare for the account's members, the one-time PIN for
+         everyone else), keeps the allow policy with every member's and invitee's
+         email, puts two Access applications in front of the hosts with the
+         Gateway's MCP, OAuth and /health and each app's public routes let through
+         (an app host's /mcp only where its manifest sets mcp), and sets the three
+         CLOUDFLARE_ACCESS_* Gateway settings in one version. Rerunnable; run again
+         after inviting someone. access off asks (--yes); access show reports. Each
+         existing member then signs in once with their password through Access;
+         tell the user who (done.data.signIn).
+Set up:  what the Gateway holds for apps, end to end (the provider's side, the
+         key or OAuth client, configure or secret set, the check): read
+         setup/README.md in this skill first, then the file it names, each on
+         its own with the file-reading tool (together they pass a shell's
+         output cap). Cloudflare and the Gateway
+         (setup/gateway.md), Cloudflare Access (setup/access.md), email
+         (setup/email.md), API keys (setup/dataforseo.md, context.md,
+         openrouter.md, openai.md, workers-ai.md), OAuth clients
+         (setup/google.md, microsoft-365.md, slack.md), any other catalog
+         provider (setup/providers.md#<id>, generated from the catalog); a
+         provider registered on the Gateway has no file: pnpm everyapp
+         provider show <id> prints its spec. A key or client secret
+         never goes through the chat: README.md says the three ways it gets in.
+Remove:  pnpm everyapp delete <id> --json   never add --purge, --force-dns,
+         --allow-delete-*, --allow-downgrade, or --yes to delete unless the
+         user asked.
+MCP apps: pnpm everyapp mcp on dataforseo --json   offers a data provider's
+         tools (dataforseo_<tool>) to members' AI clients through the Gateway's
+         /mcp with the Gateway's key (DATAFORSEO_API_KEY, setup/dataforseo.md);
+         no page, nothing to deploy (the launcher lists it under "MCP apps").
+         pnpm everyapp mcp add <url> --auth bearer --json   does the same for
+         any remote MCP server (Streamable HTTP): <id>_<tool>, its credential
+         a Gateway setting <ID>_MCP_TOKEN set with secret set and pinned to
+         the URL's origin (setup/remote-mcp.md). add looks at the server once
+         and only warns. mcp list shows each app's kind, on/off/needs setup,
+         tools and key; mcp show <id> its URL, credential and every tool with
+         its risk; mcp tool <id> <tool> --risk read|write|destructive or --off
+         overrides one tool; mcp refresh <id> re-lists. mcp off <id> stops
+         serving and keeps access (mcp on is instant); mcp remove <id> deletes
+         it (the key stays; before 2026-10-25 off deleted it). The credential
+         never goes through the chat (setup/README.md's three ways). provider
+         on|off still run mcp on|off through launch week; provider list is the
+         API providers' list. You, owners and admins get it;
+         others are granted in Admin → Apps → Manage access. An owner or admin
+         caps an app's provider calls per month in Admin → Usage (off by
+         default): past it a provider tool answers a tool error naming the
+         cap, and an app's brokered call gets 429 app_monthly_cap_exceeded
+         until the next UTC month.
+APIs:    pnpm everyapp provider add stripe.json --json   registers an API
+         provider the catalog doesn't have on the Gateway: a JSON spec (hosts,
+         auth, settings named after its id, STRIPE_…; never a value; fields
+         and rules on the providers page), from a file or an https URL. Then
+         pnpm everyapp secret set STRIPE_API_KEY (it names the provider and
+         the hosts the key goes to, and binds the key to them: a row replaced
+         with --replace needs the key set again). An app lists it under
+         capabilities like a catalog provider and calls integrationFetch().
+         provider list (the catalog and the rows), provider show <id> (the
+         whole spec; --save writes .everyapp/providers/<id>.json for dev),
+         provider remove <id> (PROVIDER_IN_USE while an app lists it).
+Workspace: pnpm everyapp workspace rename "Acme Corp" --json   renames the workspace
+         (the Gateway's organization: the name in the switcher and in invitations;
+         1 to 64 characters, no line breaks). Nothing is deployed; members see it
+         on their next page. Owners and admins can do the same under Manage
+         workspace → Rename. WORKSPACE_NOT_CLAIMED: the Gateway has no owner yet.
+Roles:   pnpm everyapp workspace role <email> owner|admin|member --json   sets a
+         member's role in the workspace under the Cloudflare login (the Users
+         page does the same). Owners are peers and the workspace always keeps
+         one: the last owner's role is refused (LAST_OWNER); someone still
+         invited isn't a member yet (MEMBER_NOT_FOUND).
+Manage:  pnpm everyapp workspace --help   the rest of Manage workspace from the
+         terminal, under the Cloudflare login: show, users, invite (prints the
+         link; nothing is mailed), invite-link, uninvite, deactivate, reactivate,
+         remove (--yes), reset-link, groups, group create|set|delete|members|apps,
+         apps, app set|access|cap, usage, activity, tokens, token revoke,
+         connections, connection revoke; --json on each. --org <slug> acts on
+         another organization (a name two organizations share is refused:
+         ORG_AMBIGUOUS; scripts pass the slug or id). deactivate and remove keep
+         the last owner who can act (LAST_OWNER); a ban is account-wide, so
+         deactivate checks every organization the person owns.
+Events:  pnpm everyapp events add <url> --events 'cap.*,member.*' --json   sends
+         those Gateway events to a webhook (Slack workflow, Zapier, n8n), signed;
+         the generated secret is data.secret, shown once: hand it to the person,
+         never invent or echo one. --email admins mails owners and admins instead.
+         events list|test <id>|deliveries --dead|redeliver <id>; events types lists
+         types. An app emits its own with emit() (app.<id>.<name>), declaring
+         nothing. Everything: /docs/agent/events.
+Tools:   an app's AI tools are defineTools() in src/tools.ts; the Gateway
+         serves them at https://<gateway>/mcp as <app>_<tool> (dev:
+         http://<app-id>.localhost:8787/mcp) and snapshots them at deploy.
+         How to write, connect and debug them: mcp.md beside this file.
+Wipe:    pnpm everyapp teardown --account-id <id> --dry-run --json   deletes
+         EVERYTHING Every App made in one Cloudflare account (the Gateway too):
+         only on a dedicated test account the user names, never one they use.
+         Always --dry-run --json first and show the user data.plan. It needs
+         EVERYAPP_TEST_ACCOUNTS=<id> and CLOUDFLARE_API_TOKEN scoped to that
+         account in the environment, which the user sets. Without --confirm it
+         stops with TEARDOWN_CONFIRMATION_REQUIRED (authorize): never add
+         --confirm <id> unless the user explicitly asked for the deletion.
+
+Security: the Gateway signs people in and passes identity to the app in a
+         header the SDK verifies (everyApp(), getEveryAppUser(),
+         requireEveryAppUser(), a tool call's identity); never read who the
+         user is from a client-supplied header, cookie or parameter. Routes
+         are private unless listed under `public` in everyapp.config.ts; a
+         public route is open to the internet and does its own checks.
+         Before opening a pull request that touches identity, public routes,
+         tools, secrets or queries, review the changes locally against the
+         app boundaries in security-review.md beside this file: in Claude
+         Code, /security-review (its built-in review of the branch's pending
+         changes) pointed at that file; any other agent reads git diff
+         against the list there. No CI job and no API key: the review runs
+         where you run. Fix what it finds, or say in the pull request why a
+         finding is a false positive. What the Gateway promises and what an
+         app must do itself: docs/threat-model.md in the Every App checkout
+         (https://everyapp.com/docs/agent/repo/threat-model).
+
+Only a person can: approve the Cloudflare login, open the owner link, pick
+a workers.dev subdomain, pay for Workers Paid, buy a domain. Interactive
+setup optionally offers browser deployment: a Yes/No prompt (default No),
+then a hidden Cloudflare API token prompt. Never ask for its value in chat.
+It then offers Cloudflare Access (Yes by default; the team name asked for
+when the account has none); under --json neither is asked, and --yes
+answers No to both.
+Handing off: stop, tell the person in one or two lines what to do (the
+action's url and code, what to click, what to come back with), and resume
+with data.rerun when they say it is done. Two more only a person can do:
+pick the account (choose_account: data.choices, each with its rerun) and
+confirm in a terminal a Worker changed outside everyapp (rerun_interactive,
+data.needsTerminal: true: hand them the command without --json; adding it
+back loops). https://everyapp.com/docs/agent/setup.md has the words for
+each handoff and the order of a whole setup.
+Full reference: https://everyapp.com/docs/agent/cli.md (every command and flag),
+https://everyapp.com/llms.txt (every page).

package/skills/everyapp/mcp.md

@@ -0,0 +1,336 @@
+# Agent tools (MCP)
+
+An app never speaks MCP. It describes its tools with `defineTools()` in
+src/tools.ts and passes them to `everyApp(handler, { tools })`; the Gateway
+snapshots that catalog and serves AI clients at `https://<gateway>/mcp` (every
+app the caller can use, tools named `<app-id>_<tool>`). An app's own host
+serves `https://<app-host>/mcp` (that app alone) only when everyapp.config.ts
+says `mcp: { by: "gateway", why: "..." }`; leave it out (the default), and
+point clients at the Gateway. Never add an MCP server, an /mcp route, a login
+or a token check to an app. Full reference: https://everyapp.com/docs/agent/mcp.md (in a
+checkout landing-page/content/agent/mcp.md); the person's steps: https://everyapp.com/docs/connect-ai.
+
+## Define tools: src/tools.ts
+
+The starter's shape (starter/src/tools.ts, shortened; the queries and their zod
+schemas live in starter/src/server/todos.ts, shared with the server functions):
+
+```ts
+import { ToolError, defineTools } from "@every-app/sdk/server";
+import { z } from "zod";
+import * as todos from "@/server/todos";
+
+export const tools = defineTools(
+  {
+    list_todos: {
+      description: "List the user's todos, completed ones included.",
+      risk: "read",
+      input: z.object({}).strict(),
+      handler: (_input, { user }) => todos.listTodos(user.id),
+    },
+    create_todo: {
+      description: "Add a todo. The server assigns its id.",
+      risk: "write",
+      idempotent: false,
+      input: todos.createTodoInput,
+      handler: (input, { user }) => todos.createTodo(user.id, input),
+    },
+    delete_todo: {
+      description: "Delete one todo for good.",
+      risk: "destructive",
+      input: todos.deleteTodoInput,
+      handler: async (input, { user }) =>
+        (await todos.deleteTodo(user.id, input)) ?? raise("No todo with that id"),
+    },
+  },
+  {
+    instructions:
+      "Never guess todo ids: call list_todos first when an id isn't already known.",
+  },
+);
+
+/** A message the model may read; any other error reaches it as "Internal error". */
+function raise(message: string): never {
+  throw new ToolError(message);
+}
+```
+
+Register them once, in src/entry.worker.ts:
+`export default everyApp<Env>(async (request) => tanstackEntry.fetch(request), { tools });`
+
+Names:   lowercase snake_case, a letter first, at most 48 characters; on the
+         Gateway connector `<app-id>_<tool>` must fit 64 or the tool is skipped.
+Fields:  `description` (required; the model reads it; over 2048 characters the
+         Gateway skips the tool), `risk` (required), `input` (required: zod 4.2
+         or later, any Standard Schema with JSON Schema support, or a plain
+         `{ jsonSchema, validate }`; it must describe an object),
+         `handler(input, context)` (required), `idempotent` (boolean, sent as
+         `annotations.idempotentHint`), `title`, `output` (an object schema,
+         validated and sent as `structuredContent`), `openWorld`. Second
+         argument `{ instructions }`: guidance across the tools, at most 2048;
+         on the Gateway connector it is clipped to 1024 and placed after the
+         app list, and Claude Code shows the model only the first 4,096
+         characters of the whole (Codex's docs ask that the first 512 stand
+         alone), so put what matters first.
+Risk:    "read": listed and callable for every caller (`readOnlyHint: true`).
+         "write": hidden from read-only connections (`read_only_connection`).
+         "destructive": hidden from every AI client until approvals exist
+         (`destructive_requires_approval`): absent from tools/list, a call
+         answers `-32602 Unknown tool: <name>`. Keep the handler.
+Context: the handler's second argument: `user` (the verified caller: `id`,
+         `email`, `orgId`, `orgRole`, `channel: "mcp"`, `actor.sub` of
+         `pat:<token id>`, `oauth:<connection id>` or `access:<email>`,
+         `scopes` of `["mcp:read"]` or `["mcp:read", "mcp:write"]`, and
+         `toolCall` with this call's `id` and `name`), `env`, `ctx`, `request`
+         (the internal `POST /__everyapp/tools/call`), `callId`. Scope every
+         read and write by `user.id`: a client never supplies a user id.
+Results: a string (one text block), any JSON value (a JSON text block), a value
+         checked by `output` (text plus `structuredContent`), or
+         `toolResult({ text, structured })`. At most 1 MiB reaches the client.
+Errors:  throw `new ToolError("No todo with that id")` for a message the model
+         may read (`isError: true`). Any other error is logged in the app as
+         `[everyapp] tool "<name>" failed (ref <callId>): …` and reaches the
+         client only as `Internal error in <app-id> (ref <callId>)`.
+A bad definition throws at module load (`defineTools: tool "<name>" needs a risk: "read", "write" or "destructive"`),
+so the Worker fails rather than serving a catalog without the tool; a schema with
+no object JSON Schema form only skips that tool with a warning (`TOOLS_CATALOG` in dev).
+
+MCP apps: the Gateway also serves tools that aren't any app's, with no page
+and nothing to deploy, on the same /mcp under the same access rules: a data
+provider's built in (DataForSEO: `dataforseo_<tool>`, once the operator runs
+`pnpm everyapp mcp on dataforseo` and sets DATAFORSEO_API_KEY), and any remote
+MCP server added by URL (`pnpm everyapp mcp add <url> --auth bearer`, its tools
+`<id>_<tool>`). For a remote server the Gateway holds the credential (the
+Gateway setting `<ID>_MCP_TOKEN`, pinned to the URL's origin), forwards each
+call, and decides each tool's risk from the server's annotations (no hint
+counts as `write`; `mcp tool <id> <tool> --risk …` overrides one). `mcp off`
+stops serving and keeps access; `mcp remove` deletes it. Never wrap a
+remote MCP server in an app of your own to put it behind the Gateway: add it
+(setup/remote-mcp.md, SKILL.md "MCP apps").
+
+## What the Gateway does with them
+
+Snapshot: the Gateway stores each app's catalog in D1 with the app version it
+came from, taken when the app is activated (the first deploy: the CLI waits
+for the app to go live, so the catalog exists before anyone connects), when a
+deploy through the Gateway (a browser install) finishes a new version, on the first app-host request each
+isolate sees after a self-hosted redeploy, when `/mcp` or the consent page
+finds a missing or outdated snapshot (synced within the request, 3 s budget),
+and when a call reports a drifted `catalogHash` or `unknown_tool`. The CLI's
+deploy syncs nothing itself. One sync: `POST /__everyapp/tools/list` (15 s, a
+5 MiB response; no count cap per app: a catalog is bounded by its per-tool
+limits, the response size and one atomic D1 write); status `ok`, `empty`,
+`unsupported` (SDK older than 0.3) or `error` (retried at most every 5
+minutes); logged as `mcp.catalog.sync`.
+Calls:   `tools/list` never calls the app. `tools/call` checks the arguments
+         against the snapshot, mints a 120 s identity JWT for that one call
+         (`chan: "mcp"`, explicit scopes, `tc: { id, name }`), makes one
+         `POST /__everyapp/tools/call` (30 s) and audits one `mcp_tool_calls` row.
+Built-ins (Gateway connector only; always loaded in Claude Code):
+         `everyapp_list_apps` (the apps this connection can use),
+         `everyapp_whoami` (user, org, access), `everyapp_search_tools`
+         (`{ query?, app?, limit? }`: finds callable tools by words, by app
+         id or both, with their input schemas; read-only), and the two call
+         wrappers `everyapp_call_read` and `everyapp_call_write`
+         (`{ name, arguments? }`: run one app tool by its `<app-id>_<tool>`
+         name; the read wrapper runs read tools only with `mcp:read` alone,
+         the write wrapper is hidden from read-only connections). A wrapped
+         call is the same one call: same policy, checks and identity, and
+         one audit row naming the inner tool with `via` set to the wrapper.
+Workspace tools (Gateway connector only; every admin action of the UI, listed
+         in full mode to a caller whose role reaches each; a read-only
+         connection never sees a write one; a token bound to one app or a
+         connection consented to some apps sees none of them; never a
+         credential that opens the Gateway; one audit row per call under app
+         `everyapp`): owners and admins get
+         `everyapp_workspace_show`, `everyapp_workspace_users`,
+         `everyapp_workspace_invite` (never the link), `everyapp_workspace_uninvite`,
+         `everyapp_workspace_role`, `everyapp_workspace_deactivate`,
+         `everyapp_workspace_reactivate`, `everyapp_workspace_reset_email`,
+         `everyapp_workspace_groups`, `everyapp_workspace_group_create`,
+         `everyapp_workspace_group_set`, `everyapp_workspace_group_delete`,
+         `everyapp_workspace_group_members`, `everyapp_workspace_group_members_set`,
+         `everyapp_workspace_group_apps`, `everyapp_workspace_group_apps_set`,
+         `everyapp_workspace_apps`, `everyapp_workspace_app_set`,
+         `everyapp_workspace_app_access`, `everyapp_workspace_app_access_set`,
+         `everyapp_workspace_app_cap`, `everyapp_workspace_usage`,
+         `everyapp_workspace_activity`, `everyapp_workspace_rename`, and the
+         events tools `everyapp_workspace_events`, `everyapp_workspace_events_add`
+         (a generated signing secret comes back once, in that answer: it opens
+         nothing on the Gateway, so the person stores it in the receiver now),
+         `everyapp_workspace_events_set`, `everyapp_workspace_events_remove`
+         (asks `confirm: true`; Cap alerts is turned off instead),
+         `everyapp_workspace_events_test`, `everyapp_workspace_event_deliveries`
+         and `everyapp_workspace_event_redeliver`; owners alone get
+         `everyapp_workspace_remove` and `everyapp_workspace_app_delete`
+         (both ask `confirm: true`); every member gets their own
+         `everyapp_my_tokens`, `everyapp_revoke_token`, `everyapp_my_connections`
+         and `everyapp_revoke_connection`. A user is an email or id, an app a
+         manifest id or row id, a group a name or `grp_` id, an event
+         subscription a name or `sub_` id. MCP apps, the
+         `mcp` commands as tools: `everyapp_mcp_list`, `everyapp_mcp_show`,
+         `everyapp_mcp_add` (a credential's setting name, never its value; the
+         answer names `secret set`), `everyapp_mcp_on`, `everyapp_mcp_off`,
+         `everyapp_mcp_refresh`, `everyapp_mcp_tool`, and for owners
+         `everyapp_mcp_remove` (`confirm: true`). Full reference:
+         /docs/agent/mcp#workspace-tools.
+Provider tools (Gateway connector only; one audit row per call like the
+         workspace tools): every member gets `everyapp_provider_list` (the
+         API providers this Gateway brokers, catalog and rows, with their
+         settings and hints and which of this organization's apps list
+         each; set-ness and the key binding for owners and admins only);
+         owners and admins on a self-hosted Gateway also get
+         `everyapp_provider_add` (`{ spec }`: the spec object, never a URL,
+         never a replace of a row that is there) and
+         `everyapp_provider_remove` (`{ id }`: refuses a built-in, a row
+         whose key is set, and a row an app lists). A hosted Gateway hides
+         both writers. No key is ever set through a tool: `everyapp secret
+         set NAME` from the terminal. Full reference:
+         /docs/agent/mcp#provider-tools.
+Listing: full (the built-ins, the workspace tools, then every tool) until a connection's full list
+         would pass 256 tools or 1 MiB, then compact (the built-ins only:
+         find tools with `everyapp_search_tools`, run them through the
+         wrappers or by name); `X-EveryApp-Tools: full|compact` chooses
+         for any caller that can set a header, `?tools=` on /mcp for a
+         personal token, an Access caller or Claude Code (the header first
+         when both are given); claude.ai, Claude Desktop and ChatGPT need
+         the OAuth resource to equal the URL typed, so for them the query
+         form fails to connect and the bare /mcp gets the automatic rule.
+         Compact hides nothing: an unlisted tool is still callable; a
+         hidden one stays `Unknown tool`. A read-only connection is told
+         to use `everyapp_call_read` alone.
+Changes: 2026-07-28 clients (Claude Code) hold a `subscriptions/listen` stream
+         re-read every 30 s, so a change reaches them within about half a
+         minute; the Gateway ends it after 30 minutes (an app host after 10,
+         and never past the token's expiry) and the client opens a new one,
+         few enough an hour that Claude Code keeps listening indefinitely;
+         2025-era clients get `notifications/tools/list_changed` and a
+         new `Mcp-Session-Id` on their next request (a stale session's
+         `tools/list` answers 404, so the client initializes again).
+         `tools/list` carries `ttlMs: 60000` (a minute's cache).
+
+## Local: pnpm everyapp dev
+
+`pnpm everyapp dev` prints `http://<app-id>.localhost:8787/mcp` under "MCP" in
+its ready block: a local ToolBus with the Gateway's policy, argument checks and
+identity contract, serving the app's live `defineTools()` catalog, re-read
+every 2 s, so an edit shows on the next request. In the default stub mode any
+bearer value acts as the seeded dev user; in `--mode mirror` it takes a
+personal access token from the local Gateway. Each call prints
+`MCP  <tool>  <outcome>  <ms>ms` or `MCP  <tool>  blocked: <reason>` (two
+spaces between parts; outcome and reason codes are printed as words: `tool
+error`, `destructive requires approval`). Claude Code:
+
+```bash
+claude mcp add --transport http todo-local http://<app-id>.localhost:8787/mcp --header "Authorization: Bearer dev"
+```
+
+Caveat: the dev ToolBus declares `listChanged: false`, so Claude Code sees
+tools added to `defineTools()` only after reconnecting (`/mcp`, the server).
+
+## Connecting a person
+
+Claude Code (2.1.81 and later), then `/mcp`, choose **everyapp**, choose
+**Authenticate**, allow in the browser; `everyapp_whoami` confirms the account:
+
+```bash
+claude mcp add --transport http everyapp https://<gateway>/mcp
+```
+
+claude.ai, Claude Desktop, ChatGPT: a custom connector with the URL
+`https://<gateway>/mcp`; the client identifies itself with a Client ID
+Metadata Document (CIMD), finds the OAuth server from the 401 challenge, and
+the consent page opens. Cursor, Gemini CLI, MCP Inspector: the same URL, after
+dynamic client registration (`/oauth/register`; `MCP_DCR_ENABLED` controls it).
+Consent page: the organization, **All apps I can use, including future ones**
+or **Only these apps**, read & write (default) or **Read only**, then
+**Allow**. It grants `mcp:read` and, for read & write, `mcp:write`; an app
+shown as `(no AI tools yet)` has a snapshot with no tools; one with no
+snapshot yet shows no hint (its tools load on first use).
+Scripts and anything that takes a header: a personal access token. In the
+Gateway open **Admin** (the sidebar footer's **Manage workspace**; owners and
+admins only), tab **Tokens**, heading **Personal access tokens**, button
+**New token**: a name, **All my apps** or one app, an expiry (default
+90 days). The token is `epat_…`, shown once, read & write. Send it as
+`Authorization: Bearer epat_…` to `https://<gateway>/mcp` (a token made for one
+app sees that app alone):
+
+```bash
+claude mcp add --transport http everyapp https://<gateway>/mcp --header "Authorization: Bearer $EVERYAPP_TOKEN"
+```
+
+`https://<app-host>/mcp` takes the same header only where that app's manifest
+sets `mcp: { by: "gateway", why }`; on any other app host the path is the app's
+own private route and an MCP-only token gets 403 `token_scope` everywhere.
+
+Disconnecting: **AI connections** in the account menu at the bottom of the
+sidebar (`/settings/connections`) lists each OAuth connection; revoking one
+makes the client's next request fail `invalid_token`. Removing or
+deactivating a person ends all of theirs; tokens are revoked on Admin, Tokens.
+
+Other servers worth having beside the Gateway's (Cloudflare's API server for
+the owner, read before write; nothing else): [setup/gateway.md](setup/gateway.md),
+"Optional: MCP servers worth having beside Every App". Offer one in a line;
+never add it unasked.
+
+## Troubleshooting
+
+Tools missing after a deploy, in order: (1) the client's cache: tools/list is
+good for 60 s and a held stream polls every 30 s, so list tools again after a
+minute; (2) the snapshot: read `mcp.catalog.sync` in the Gateway's logs
+(`unsupported`: an SDK older than 0.3; `error`: the app's tools endpoint
+failed, retried in 5 minutes; a self-hosted redeploy is noticed from the app
+host's next request in each isolate); (3) hidden on purpose: destructive
+tools are never listed, write tools are hidden from a read-only connection
+(`everyapp_whoami` shows `access`), and a tool whose namespaced name passes 64
+characters, whose description passes 2048 or whose schema isn't an object is
+dropped with a warning (dev prints it as `TOOLS_CATALOG`); unlisted is not
+hidden: a compact listing (the instructions' first line says the connection
+"lists its tools compactly") leaves every app tool out of tools/list on
+purpose, and each is found by `everyapp_search_tools` and callable by name or
+through `everyapp_call_read`/`everyapp_call_write`, while a hidden tool stays
+`Unknown tool` there too; (4) the person
+cannot open the app: it is absent from `everyapp_list_apps`; grant access in
+Admin (a connection made with **Only these apps** needs a reconnect to add one).
+401 vs 403 on `/mcp`: 401 means no credential or one that doesn't verify (an
+expired or revoked token, a bearer that isn't `epat_` on an app host, the token
+of a revoked connection); its body depends on the surface. On
+`https://<gateway>/mcp` with OAuth on: an empty body and
+`WWW-Authenticate: Bearer realm="OAuth", resource_metadata="…/.well-known/oauth-protected-resource/mcp", scope="mcp:read"`
+(`error="invalid_token"` added when a token was sent); a revoked connection's
+token gets `{"error":"invalid_token","error_description":"This connection was revoked or lost its access. Connect again."}`.
+On `https://<app-host>/mcp` (where the manifest sets `mcp`), and on the Gateway with OAuth off:
+`{"error":"unauthenticated"}` with `WWW-Authenticate: Bearer realm="every-app"`
+(`error="invalid_token"` when a bearer was sent; the app host adds
+`error_description="Use a personal access token here, or connect <gateway>/mcp"`).
+An app host without `mcp` in its manifest answers `/mcp` as the app does (usually 404),
+and one with `by: "gateway"` but no catalog to serve answers 503 `{"error":"mcp_unavailable"}`.
+403 `{"error":"forbidden","reason":…}` means the credential verified and was
+refused: `token_scope` (scopes without `mcp:read` or `mcp:write`, an
+MCP-only token on a page route, or any route of a host without `mcp`), `no_app_access` (app host: the person cannot
+open this app), `not_connected`, `organization_unresolved`, `account_deactivated`, `organization_suspended`.
+OAuth off: `MCP_OAUTH_ENABLED` is `false`, or `GATEWAY_URL` is neither https
+nor http on exactly localhost or 127.x: `/oauth/*` and the discovery documents
+answer 404 `oauth_disabled`, `/mcp` takes `epat_` tokens only and its 401 says
+`WWW-Authenticate: Bearer realm="every-app"` with no authorization server. Turn
+it on with `pnpm everyapp secret set MCP_OAUTH_ENABLED`, entering `true` (live at once).
+DCR off or limited: with `MCP_DCR_ENABLED` `false`, `/oauth/register` answers
+404 `registration_disabled`; CIMD clients still connect, Cursor cannot. While
+on: 5 registrations a minute and 20 a day per client address, 200 a day per
+self-hosted Gateway, then `429 rate_limited` (wait, or use a CIMD client); past
+60 requests a minute per address on `/oauth/register` or `/oauth/token`, 429 `Too many attempts.`
+Behind Cloudflare Access: `pnpm everyapp access on` lets `/mcp`, `/mcp/*`,
+`/oauth/token`, `/oauth/register`, `/.well-known/*` and `/health` through on the Gateway
+host, and `/mcp` on an app host only where its manifest sets `mcp`, so OAuth and tokens keep working; the consent
+page stays behind Access. With Managed OAuth on the Gateway's Access application
+instead, Access is the OAuth server: the person must have signed in to the Gateway
+in a browser once (else `403 not_connected`), gets read & write to every app, no connection row.
+
+## Sources
+
+- packages/sdk/src/server/tools.ts, toolsEndpoint.ts, everyApp.ts; packages/sdk/src/internal/tools.ts, protocol.ts
+- packages/toolbus/src/server.ts, http.ts, builtins.ts, policy.ts, dev/index.ts
+- apps/every-app-gateway/src/server/toolbus/catalog-sync.ts, gateway-mcp.ts, app-host-mcp.ts; src/server/app-activation.ts, deploy/run.ts; src/server/mcp-auth/routes.ts, config.ts, validate.ts, consent.ts, registration-limit.ts
+- apps/every-app-gateway/src/routes/_app/admin/tokens.tsx, settings/connections.tsx; src/client/components/Sidebar.tsx, oauth/ConsentForm.tsx, admin/CreateUserTokenModal.tsx
+- packages/perimeter/src/gateway.ts; packages/cli/src/commands/dev/devAppGateway.ts, ready.ts; packages/cli/src/commands/deploy/deployApp.ts; packages/cli/src/lib/app/skill.ts
+- starter/src/tools.ts, entry.worker.ts, server/todos.ts, README.md; docs/runbooks/mcp-oauth.md; landing-page/content/agent/mcp.md; landing-page/content/docs/connect-ai.mdx