diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d65fcd..c0fea25 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,8 @@
 
 ## Unreleased
 
+- `storebound mcp --http`: one Streamable HTTP MCP server that every agent session of a machine shares (no process per session). Each tool gets a `project` argument (absolute path inside `--roots`); auth is a local bearer token (`~/.storebound/mcp-token`, made on first start) or, for a server behind TLS, OAuth bearer tokens checked by introspection (RFC 7662) with protected resource metadata (RFC 9728). docs/mcp.md.
+
 ## 0.8.57 · 2026-10-27
 
 - `apple upload` finds the IPA of a build made with `--out`: `apple build` notes its IPA and out folder in `.storebound/last-apple-build.json`, and upload searches `--out` (new flag), then that last build's out, then `apple.build.out` / `build/ios`. When nothing is found, the error names every folder it searched and the last build's IPA.
diff --git a/docs/mcp.md b/docs/mcp.md
index 0e8b66c..efe9cb4 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -24,6 +24,34 @@ per-request `_meta`, `resultType`, cacheable `tools/list`) and, on the same proc
 Manual config for a tool that `install` does not know: command `bunx` with args `["storebound", "mcp"]` (or the
 absolute path of `bin/storebound` plus `mcp`).
 
+## One shared server over HTTP
+
+`storebound mcp --http` serves the same tools over Streamable HTTP (MCP 2025-06-18 and later) at `/mcp`, so every
+agent session of a machine shares one process instead of starting its own. POST carries one JSON-RPC message and gets
+one JSON answer; there is no server-initiated stream and no session state. A browser Origin other than localhost is
+refused unless `--allow-origin` names it.
+
+- Every tool gets a `project` argument: the absolute path of the app folder to run in. It must be inside `--roots`
+  (comma-separated, default the home folder). `--project <dir>` sets a default for calls without one.
+- `--auth token` (default): the server makes `~/.storebound/mcp-token` (mode 600) on first start and requires it as a
+  bearer token. Only localhost hosts are allowed with it.
+
+  ```bash
+  storebound mcp --http --port 7787
+  claude mcp add --transport http storebound http://127.0.0.1:7787/mcp --header "Authorization: Bearer $(cat ~/.storebound/mcp-token)"
+  ```
+- `--auth introspect`: for a server shared over the network behind TLS. Bearer tokens are OAuth 2.0 access tokens from
+  your authorization server, checked through its introspection endpoint (RFC 7662; this server authenticates with the
+  key in `--introspect-key-file`). A token must be active, carry the `mcp` scope and list `--resource` in `aud`
+  (RFC 8707). Without one the answer is 401 with `WWW-Authenticate: Bearer resource_metadata=...`, and
+  `/.well-known/oauth-protected-resource/mcp` names `--issuer` (RFC 9728).
+
+  ```bash
+  storebound mcp --http --host 0.0.0.0 --auth introspect --introspect-url https://auth.example.com/introspect \
+    --introspect-key-file ~/.storebound/introspect.key --resource https://mcp.example.com/mcp --issuer https://auth.example.com
+  ```
+- `/health` answers `{ ok, version }` without auth.
+
 ## Desktop machine interface
 
 `storebound serve --stdio` is what the desktop app (`apps/desktop`, in progress) runs as its sidecar: newline-delimited