CRT/storebound
1
0
Fork 0
Code Issues Pull requests Releases 1 Packages 1 Activity Actions

docs: mcp --http (shared server, project argument, token and introspection auth)

Browse source
This commit is contained in:
CRTkafa 2026-10-29 16:21:50 +07:00
parent 5f73fcbcf4
commit 8068993917
2 changed files with 30 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/mcp.md
View file

@ -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