appilot-mcp 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -2,7 +2,13 @@
 /**
  * Appilot MCP server entry point.
  *
- * Two transports, one tool surface (see server.ts):
+ * Two servers ship from this package. Appilot Studio (`server.ts`) writes an
+ * app's configuration, and is the default. Appilot (`userServer.ts`, started
+ * with `--runtime`) operates an already-configured app for the person using it.
+ * One MCP process serves one of them; the remote service serves both at once,
+ * on two paths.
+ *
+ * Two transports (see server.ts):
  *
  *   stdio (default)  The operator runs the process on their own machine or
  *                    inside their network, and it carries their credentials in

package/dist/index.js

@@ -2,7 +2,13 @@
 /**
  * Appilot MCP server entry point.
  *
- * Two transports, one tool surface (see server.ts):
+ * Two servers ship from this package. Appilot Studio (`server.ts`) writes an
+ * app's configuration, and is the default. Appilot (`userServer.ts`, started
+ * with `--runtime`) operates an already-configured app for the person using it.
+ * One MCP process serves one of them; the remote service serves both at once,
+ * on two paths.
+ *
+ * Two transports (see server.ts):
  *
  *   stdio (default)  The operator runs the process on their own machine or
  *                    inside their network, and it carries their credentials in
@@ -18,20 +24,32 @@
  * Server:   docs/architecture/appilot-mcp.md.
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { loadConnection, loadRemoteConfig, resolveTransport, RemoteConfigError } from './config.js';
+import { loadConnection, loadRemoteConfig, resolveServerSurface, resolveTransport, RemoteConfigError } from './config.js';
 import { createAppilotServer } from './server.js';
+import { createAppilotRuntimeServer } from './userServer.js';
+import { runCommand } from './cli.js';
 async function runStdio() {
     const conn = loadConnection();
-    const server = createAppilotServer(conn);
+    const runtime = resolveServerSurface() === 'runtime';
+    const server = runtime ? createAppilotRuntimeServer(conn) : createAppilotServer(conn);
     await server.connect(new StdioServerTransport());
     // stderr is safe for logs; stdout is the MCP transport.
-    process.stderr.write(`[appilot-mcp] connected · base=${conn.baseUrl ?? 'not-configured'} · token=${conn.token ? 'set' : 'none'}\n`);
+    const credential = runtime
+        ? `session=${conn.sessionToken ? 'set' : 'none'}`
+        : `token=${conn.token ? 'set' : 'none'}`;
+    process.stderr.write(`[appilot-mcp] connected · server=${runtime ? 'appilot (runtime)' : 'studio (config)'} · base=${conn.baseUrl ?? 'not-configured'} · ${credential}\n`);
 }
 async function runHttp() {
     const { startRemote } = await import('./remote/httpServer.js');
     await startRemote(loadRemoteConfig());
 }
 async function main() {
+    // A subcommand answers and exits. Without this, `appilot-mcp --help` started
+    // the stdio server and waited on stdin, which reads as a hang.
+    const handled = await runCommand(process.argv.slice(2));
+    if (handled !== null) {
+        process.exit(handled);
+    }
     if (resolveTransport() === 'http') {
         await runHttp();
         return;

package/dist/manifest.d.ts

@@ -81,12 +81,24 @@ export declare function planManifest(client: AppilotClient, manifest: AppManifes
  * the token is unobtainable without the plan call and changes with the
  * manifest.
  */
-export declare function applyManifest(client: AppilotClient, manifest: AppManifest, options: {
+export interface ApplyManifestOptions {
     planToken: string;
     mode?: 'merge' | 'replace';
     expectedCurrentHash?: string;
     allowUnhealthy?: boolean;
-}): Promise<{
+    /**
+     * The refusal to raise when the caller may not provision, or null/undefined
+     * when it may.
+     *
+     * Set by the tool layer from the connection's grant. The apply then proceeds
+     * whenever the provisioning half changes nothing, which is the ordinary case
+     * in CI: the app, its domains and its keys were created once by a person and
+     * every run after that only syncs configuration. Demanding provision:write
+     * for that run contradicted the reason the two scopes are separate.
+     */
+    provisionRefusal?: string | null;
+}
+export declare function applyManifest(client: AppilotClient, manifest: AppManifest, options: ApplyManifestOptions): Promise<{
     provisioning: ProvisionAppResponse;
     config?: unknown;
     notes: string[];

package/dist/manifest.js

@@ -106,21 +106,43 @@ export async function planManifest(client, manifest, resolveAppId) {
     }
     return { planToken: manifestDigest(manifest), provisioning, config, notes };
 }
-/**
- * Apply a previously planned manifest.
- *
- * `planToken` must match the manifest being applied. This is the structural
- * version of "always dry-run first": the guidance cannot be skipped, because
- * the token is unobtainable without the plan call and changes with the
- * manifest.
- */
+/** What the provisioning half of this manifest would change, in plain words. */
+function provisioningChanges(preview) {
+    const changes = [];
+    if (preview.app.action !== 'reused')
+        changes.push(`the app "${preview.app.name}" (${preview.app.action})`);
+    for (const domain of preview.domains) {
+        if (domain.action !== 'reused')
+            changes.push(`the domain ${domain.domain} (${domain.action})`);
+    }
+    if (preview.widgetKey && preview.widgetKey.action !== 'reused') {
+        changes.push(`a widget key (${preview.widgetKey.action})`);
+    }
+    return changes;
+}
 export async function applyManifest(client, manifest, options) {
     const expected = manifestDigest(manifest);
     if (options.planToken !== expected) {
         throw new Error('planToken does not match this manifest. Run plan_manifest on the exact manifest you intend to apply, then pass the planToken it returns. A mismatch means the manifest changed after it was previewed.');
     }
     const notes = [];
-    const provisioning = await client.provisionApp(provisionRequest(manifest, false));
+    // Ask what provisioning would do before deciding whether it may. The dry run
+    // is the same call with `dryRun: true`, so this costs one request and turns
+    // "this manifest needs provision:write" from a property of the tool into a
+    // property of the manifest in front of it.
+    const preview = await client.provisionApp(provisionRequest(manifest, true));
+    const changes = provisioningChanges(preview);
+    if (changes.length > 0 && options.provisionRefusal) {
+        throw new Error(`${options.provisionRefusal}\nThis manifest would change ${changes.join(', ')}, so the apply cannot proceed without it. A manifest whose app, domains and keys already exist applies with config:write alone.`);
+    }
+    let provisioning;
+    if (changes.length === 0) {
+        provisioning = preview;
+        notes.push('Provisioning wrote nothing: the app, its domains and its keys already matched the manifest, so this apply needed only config:write. The provisioning block below is the preview, which is why it reports dryRun true.');
+    }
+    else {
+        provisioning = await client.provisionApp(provisionRequest(manifest, false));
+    }
     let config;
     if (manifest.config) {
         const appId = provisioning.app.id;

package/dist/public-marketplace/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+	"name": "appilot",
+	"owner": {
+		"name": "Appilot",
+		"url": "https://appilot.space"
+	},
+	"metadata": {
+		"description": "Appilot agent tooling: skills and MCP servers that configure and operate Appilot apps.",
+		"version": "0.3.0"
+	},
+	"plugins": [
+		{
+			"name": "app-configurator",
+			"source": "./plugins/app-configurator",
+			"description": "Set up, configure, audit, repair, back up, restore and verify an Appilot app: provision the app, its domains and its widget key, scaffold the host integration, and keep the content model correct against the config health contract. Bundles the app-configurator skill and the Appilot MCP server (cloud or on-premise).",
+			"version": "0.3.0",
+			"strict": false
+		}
+	]
+}

package/dist/public-marketplace/README.md

@@ -0,0 +1,23 @@
+# Appilot plugins
+
+The Claude Code marketplace for the Appilot **app-configurator** plugin: the
+`app-configurator` skill plus the Appilot MCP server, which reads, validates,
+fixes and provisions an Appilot app.
+
+```
+/plugin marketplace add appilot/appilot-plugins
+/plugin install app-configurator@appilot
+```
+
+The plugin asks for your instance URL and a scoped service token from the
+Backoffice, under Service tokens.
+
+Other ways in, for clients that are not Claude Code: `npx -y appilot-mcp` plus
+`appilot-mcp install-skill --codex` (or `--cursor`, `--gemini`), the hosted
+endpoint at https://mcp.appilot.space/mcp for ChatGPT and claude.ai, and the
+Claude Desktop bundle at https://downloads.appilot.space/claude-desktop.
+
+Docs: https://docs.appilot.space/docs/developers/configure-with-ai/overview
+
+Built from appilot-mcp 0.3.0. Do not edit here; this tree is generated by
+`pnpm -C packages/tools/appilot-mcp build:marketplace` in the Appilot monorepo.

package/dist/public-marketplace/plugins/app-configurator/.claude-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "app-configurator",
+  "version": "0.3.0",
+  "description": "Set up, configure, audit, repair, back up, restore, and verify an Appilot app: provision the app, its domains and widget key, scaffold the host integration, and keep the content model correct. Uses the Appilot MCP server and the app-configurator skill.",
+  "author": {
+    "name": "Appilot",
+    "url": "https://appilot.space"
+  },
+  "homepage": "https://docs.appilot.space/docs/developers/configure-with-ai/overview",
+  "skills": "./skills/",
+  "mcpServers": {
+    "appilot": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/index.bundle.js"
+      ],
+      "env": {
+        "APPILOT_BASE_URL": "${user_config.base_url}",
+        "APPILOT_PAT": "${user_config.pat}",
+        "APPILOT_APP_ID": "${user_config.app_id}"
+      }
+    }
+  },
+  "userConfig": {
+    "base_url": {
+      "type": "string",
+      "title": "Appilot backend URL",
+      "description": "Cloud or on-premise Appilot backend URL.",
+      "required": true
+    },
+    "pat": {
+      "type": "string",
+      "title": "Appilot service token",
+      "description": "Scoped appilot_pat service token. config:read for audits, config:write for changes, provision:write to create apps, domains, and widget keys.",
+      "sensitive": true
+    },
+    "app_id": {
+      "type": "string",
+      "title": "Default Appilot app ID",
+      "description": "Optional default app ID used when a tool call does not provide one."
+    }
+  }
+}

package/dist/public-marketplace/plugins/app-configurator/README.md

@@ -0,0 +1,328 @@
+# appilot-mcp
+
+MCP server that lets an AI agent **read, validate, fix, and soak** an Appilot
+app's content-model configuration (Views, Controls, Forms, Action Plans,
+Knowledge, Zones, Tools) against the **config health contract**.
+
+It is the tool surface behind the `app-configurator` skill. The skill is the
+instructions; this server is what actually touches your instance.
+
+## Why
+
+Hand-authored app config drifts silently: a plan that opens an input but never
+submits, an auto-generated selector like `#nc-vue-30`, half-translated labels, a
+knowledge article that is really a procedure. This server encodes the contract
+those failures violate and checks it locally (no round-trip, air-gapped-safe)
+and against the live instance.
+
+## Cloud or on-premise
+
+Endpoint-agnostic by design. The same binary talks to a cloud tenant or an
+on-premise / sovereign instance purely by pointing `APPILOT_BASE_URL` at it. The
+static gate runs locally from `appilot-shared`, so it works with no network.
+
+## Two transports, one tool surface
+
+The same tools serve two shapes, and which one you need is decided by the client,
+not by preference.
+
+| Transport | Who launches it | Credential | Clients |
+|-----------|-----------------|------------|---------|
+| **stdio** (default) | The client, as a local child process | `APPILOT_PAT` in the process environment | Claude Code, Codex (CLI, IDE, app), Claude Desktop, Cursor, Antigravity |
+| **HTTP** (`--http`) | You, as a deployed service | Account approval or a manually supplied service token through OAuth | ChatGPT, claude.ai, and any remote MCP client |
+
+ChatGPT and claude.ai cannot start a process on your machine, and neither offers
+a field for pasting an API key: they connect to a URL and authenticate with
+OAuth. That is what HTTP mode is for. See
+[Remote deployment](#remote-deployment).
+
+## Configuration
+
+| Env | Required | Meaning |
+|-----|----------|---------|
+| `APPILOT_BASE_URL` | yes | Backend URL, e.g. `https://api.appilot.space` or `http://localhost:6001` |
+| `APPILOT_PAT` | for writes / server echo | A scoped service token (`appilot_pat_…`), minted in the Backoffice (Service tokens). `config:read` to read/validate, `config:write` to apply. |
+| `APPILOT_APP_ID` | optional | Default app id for tools that omit one |
+| `APPILOT_SOAK_STORAGE_STATE` | optional | Path to a Playwright `storageState` JSON for an authenticated site session (soak) |
+
+HTTP mode reads a different profile. It holds no Appilot credential of its own,
+because each caller brings theirs.
+
+| Env | Required | Meaning |
+|-----|----------|---------|
+| `APPILOT_BASE_URL` | yes | The one instance this deployment fronts. Never client-supplied: a caller-chosen URL would make the service an SSRF relay. |
+| `APPILOT_MCP_PUBLIC_URL` | yes | The public origin clients reach, e.g. `https://mcp.appilot.space`. OAuth metadata and redirects are absolute. |
+| `APPILOT_MCP_OAUTH_SECRET` | yes | At least 32 characters (`openssl rand -base64 32`). Everything the authorization server issues is sealed with it, so rotating it disconnects every client. |
+| `PORT` | no | Defaults to 8080. Cloud Run supplies it. |
+| `APPILOT_MCP_ALLOWED_HOSTS` | no | Extra `Host` values to accept, comma separated, for a proxy or a platform-assigned hostname. The public origin is always accepted. |
+| `APPILOT_MCP_DOCS_URL` | no | Where the protected-resource metadata points a client for documentation. Defaults to the public docs site. |
+| `APPILOT_MCP_BACKOFFICE_URL` | no | The Backoffice origin consent screens link to, and the only origin account approval is accepted from. Must be HTTPS (localhost excepted). Defaults to `https://backoffice.appilot.space` when the instance is the Appilot cloud. |
+| `APPILOT_MCP_HANDOFF_SECRET` | no | Enables account approval instead of pasting a service token. At least 32 characters, and it must match the backend's. Separate from the OAuth secret, and it requires `APPILOT_MCP_BACKOFFICE_URL`. |
+
+## Tools
+
+Twenty-five, in the order the server registers them. `test/toolSurface.test.ts`
+holds this table, `mcpb/manifest.json` and the registered tools to one list.
+
+| Tool | Purpose |
+|------|---------|
+| `capabilities` | Version, migration level and the closed vocabularies this instance accepts (negotiate before configuring) |
+| `read_config` | Normalized snapshot of an app's content model |
+| `validate_config` | Severity-ranked findings against the health contract (local + server echo) |
+| `entity_template` | A valid skeleton per entity kind, carrying the closed enums this instance accepts |
+| `create_entity` / `update_entity` / `delete_entity` | Authoring across all eight kinds (server re-validates the trust boundary) |
+| `validate_action_plan` | Check draft plan sections before writing them |
+| `export_config` / `import_config` | Whole-app ConfigBundle round trip, dry-run first, merge or replace |
+| `whoami` | Which organization, which app and which scopes the credential reaches |
+| `create_app` | Provision the app, its domains and a widget key, with the snippets to paste in |
+| `list_apps` | What this organization has provisioned, with each domain's verification status |
+| `list_widget_keys` | The keys already minted, by label and prefix. No raw key, no secret |
+| `verify_domain` | Where a domain's DNS verification stands, and the TXT record it needs |
+| `integration_snippet` | The script tag and boot call for an app that already exists. Pure, no scope |
+| `plan_manifest` / `apply_manifest` | A whole tenant from one versioned file, plan before apply |
+| `scaffold_integration` | The host application's source: identity relay, widget boot, a client action |
+| `verify_integration` | Load the running page and report what is actually true |
+| `soak_selectors` | Headless-browser check that each control selector resolves on the live page (needs Playwright) |
+| `inspect_page` | Read a page and rank locator candidates by whether they survive the next render |
+| `scaffold_agent_first` | The artifacts one capability needs to be operable by the agent |
+| `report_feedback` / `list_feedback` | Report a gap or a defect in Appilot, and see what this organization has already raised |
+
+## The command line
+
+The package is an MCP server first, and a small CLI for the things a pipeline
+needs without an MCP client in front of them.
+
+```bash
+npx appilot-mcp --help
+npx appilot-mcp --version
+npx appilot-mcp install-skill --claude     # or --codex, --cursor, --gemini
+npx appilot-mcp plan  app.appilot.json     # preview, writes nothing
+npx appilot-mcp apply app.appilot.json     # apply the plan it just printed
+```
+
+`plan` and `apply` read the same environment the stdio server does, and `apply`
+runs the plan itself and passes its own token, so the preview cannot be skipped.
+`install-skill` copies the bundled `app-configurator` skill into the client's
+skills directory, which is what makes the skill reachable from a bare `npx`
+install: inside the npm cache no client looks for it.
+
+
+## Distribution artifacts
+
+One package carries a tool-neutral implementation plus thin discovery adapters:
+
+| Artifact | Consumers |
+|----------|-----------|
+| `skills/app-configurator/SKILL.md` | Open Agent Skills clients, including Codex, Claude Code, Cursor, and Antigravity |
+| `.mcp.json` | Codex plugin MCP declaration |
+| `.codex-plugin/plugin.json` | Codex plugin |
+| `.claude-plugin/plugin.json` | Claude Code plugin |
+| `mcpb/manifest.json` | Claude Desktop bundle manifest, packed by `pnpm build:mcpb` |
+| `Dockerfile` | The remote HTTP service |
+| `dist/index.bundle.js` | Self-contained Node.js MCP server, both transports |
+
+`pnpm pack` runs the build and includes all of these artifacts in the package.
+The server can initialize and expose its tools before connection settings are
+provided. Live tool calls return a clear configuration error until
+`APPILOT_BASE_URL` is set.
+
+## Install from this repository
+
+Build the self-contained server first:
+
+```bash
+pnpm -C packages/tools/appilot-mcp build
+```
+
+### Codex
+
+The repository is a Codex marketplace:
+
+```bash
+codex plugin marketplace add /absolute/path/to/app-pilot
+codex plugin add app-configurator@appilot
+```
+
+The plugin installs both the skill and MCP server globally. Start a new Codex
+task after installation so the new tool surface is loaded.
+
+### Claude Code
+
+Add the repository marketplace and install `app-configurator@appilot`. Claude's
+plugin settings prompt for the backend URL, service token, and optional app ID.
+The token is declared sensitive so Claude stores it in secure credential
+storage.
+
+### Claude Desktop
+
+Build the double-clickable bundle and open it:
+
+```bash
+pnpm -C packages/tools/appilot-mcp build
+pnpm -C packages/tools/appilot-mcp build:mcpb
+open packages/tools/appilot-mcp/dist/appilot-configurator.mcpb
+```
+
+Desktop asks for the backend URL and the service token, storing the token in the
+OS keychain. The bundle carries the server and its manifest and nothing else, so
+it installs on a machine with no Node toolchain and no network.
+
+### ChatGPT and claude.ai
+
+Neither can launch a local process, so both connect to a deployed HTTP endpoint.
+Once one is running (see [Remote deployment](#remote-deployment)):
+
+- **ChatGPT**: Settings, Apps, Advanced settings, turn on Developer mode, then
+  add a connector pointing at `https://<your-host>/mcp` with OAuth. The
+  authorization step opens Appilot account approval, or manual token consent on older deployments.
+- **claude.ai**: Settings, Connectors, Add custom connector, same URL.
+- **Codex** can use the remote endpoint too, if you prefer one shared deployment
+  over a local process: add the URL to `~/.codex/config.toml` and run
+  `codex mcp login appilot`.
+
+To reach a private instance from ChatGPT without exposing an endpoint at all,
+run OpenAI's Secure MCP Tunnel against the local stdio server instead. The
+tunnel client makes an outbound connection from inside your network, so the
+instance needs no public listener.
+
+### Cursor
+
+Copy `skills/app-configurator` to `~/.cursor/skills/app-configurator`, then add
+the server to `~/.cursor/mcp.json`.
+
+### Antigravity
+
+Copy `skills/app-configurator` to the applicable global skills directory:
+
+- Antigravity IDE: `~/.gemini/config/skills/app-configurator`
+- Antigravity CLI: `~/.gemini/antigravity-cli/skills/app-configurator`
+
+Register the stdio server in `~/.gemini/config/mcp_config.json`.
+
+### Any stdio MCP client
+
+Point the client at the built bundle:
+
+```json
+{
+  "mcpServers": {
+    "appilot": {
+      "command": "node",
+      "args": ["/absolute/path/to/appilot-mcp/dist/index.bundle.js"],
+      "env": {
+        "APPILOT_BASE_URL": "https://api.appilot.space",
+        "APPILOT_PAT": "appilot_pat_...",
+        "APPILOT_APP_ID": "123"
+      }
+    }
+  }
+}
+```
+
+For registry-backed distribution, replace `node` and the bundle path with
+`pnpm dlx appilot-mcp` after the package is published.
+
+Do not commit service tokens. Use the MCP client's secure secret storage or
+environment forwarding when available.
+
+## Remote deployment
+
+HTTP mode delegates identity and approval storage to the backend. It has no
+local user table, client registry or raw token store. The OAuth authorization server seals its own
+state into the artifacts it issues (see `src/remote/tokens.ts`), so a second
+instance behaves exactly like the first and a cold start loses nothing.
+
+What it serves:
+
+| Path | Purpose |
+|------|---------|
+| `POST /mcp` | The MCP endpoint, Streamable HTTP, bearer required |
+| `/.well-known/oauth-protected-resource/mcp` | Points a client at the authorization server |
+| `/.well-known/oauth-authorization-server` | Metadata, PKCE with S256, dynamic registration |
+| `/authorize`, `/token`, `/register` | The OAuth 2.1 flow |
+| `/consent` | Manual token verification and review |
+| `/connect/callback` | Redeems account approval bound to the initiating browser |
+| `/health` (also `/healthz` off Cloud Run) | Liveness |
+
+Run it:
+
+```bash
+pnpm -C packages/tools/appilot-mcp build
+docker build -t appilot-mcp packages/tools/appilot-mcp
+docker run -p 8080:8080 \
+  -e APPILOT_BASE_URL=https://api.appilot.space \
+  -e APPILOT_MCP_PUBLIC_URL=https://mcp.appilot.space \
+  -e APPILOT_MCP_OAUTH_SECRET="$(openssl rand -base64 32)" \
+  appilot-mcp
+```
+
+On Cloud Run, which is where the backend already runs, use the script rather
+than a hand-typed `gcloud` line: it creates the signing secret, grants the
+runtime service account access to it, and handles the two-pass problem where the
+service URL only exists after the first deploy while `APPILOT_MCP_PUBLIC_URL`
+has to name that exact origin.
+
+```bash
+packages/tools/appilot-mcp/scripts/deploy-cloud-run.sh
+```
+
+It deploys unauthenticated on purpose: the service does its own OAuth, and
+platform-level IAM in front of it would block the discovery endpoints a client
+has to read before it can authenticate at all. The upload carries the
+`Dockerfile` and the one bundle, which is what `.gcloudignore` is for. Mapping
+`mcp.appilot.space` onto the service is the last step, and the script prints it.
+
+### How access works
+
+The service never sees an Appilot password. Account approval asks the backend
+to create a scoped credential after the administrator reviews access. In the
+manual flow, a person pastes a previously created token and MCP checks it against the instance
+(`GET /config/whoami`) before granting anything. The granted scopes are the
+intersection of what the client asked for and what that token actually carries,
+so a `config:read` token cannot be talked into write access. The token is then
+sealed inside the OAuth tokens the client holds; the client never sees it.
+
+Revocation happens where the token was minted: revoke it in the Backoffice and
+every connection built on it stops working on the next call. Rotating
+`APPILOT_MCP_OAUTH_SECRET` invalidates every issued token at once.
+
+The soak tool is deliberately unavailable in this mode: driving a real browser
+belongs on the operator's machine over stdio, not in a shared web service.
+
+## Develop
+
+```bash
+pnpm -C packages/tools/appilot-mcp build       # tsc + the self-contained bundle
+pnpm -C packages/tools/appilot-mcp build:mcpb  # the Claude Desktop bundle
+pnpm -C packages/tools/appilot-mcp test        # vitest: contract, OAuth, HTTP end to end
+pnpm -C packages/tools/appilot-mcp typecheck
+```
+
+To exercise HTTP mode locally, point it at a dev backend and use a localhost
+public origin, which is the one case where plaintext is accepted:
+
+```bash
+APPILOT_BASE_URL=http://localhost:6001 \
+APPILOT_MCP_PUBLIC_URL=http://localhost:8080 \
+APPILOT_MCP_OAUTH_SECRET="$(openssl rand -base64 32)" \
+node packages/tools/appilot-mcp/dist/index.bundle.js --http
+```
+
+Live DOM soak needs Playwright: add it with pnpm and install Chromium.
+
+See `docs/architecture/appilot-mcp.md` (server) and
+`docs/content-model/config-health-contract.md` (the contract it enforces).
+
+### Account-based remote approval
+
+Remote deployments can reuse the Backoffice session for approval without asking
+users to create or paste a token. Configure APPILOT_MCP_HANDOFF_SECRET on backend
+and MCP, a trusted APPILOT_MCP_BACKOFFICE_URL on MCP, and the fixed
+APPILOT_MCP_PUBLIC_URL on backend. Deploy migration system/025 and the Backoffice
+approval page first. The cloud activation script is
+`scripts/enable-session-approval.sh`. Keep this secret separate from the OAuth key.
+
+Manual service-token consent remains available when session approval is not
+configured, or with `manual=1` on the authorization request. Consent and errors
+support English, Spanish and German. Administrators can filter connections,
+renew expiry and revoke access in Backoffice Service tokens.