# mcphost — full documentation > Generated by scripts/gen-llms-full.sh from README.md, docs/kinds/*.md, > docs/benchmarks/*.md and docs/receipts/*.md. See /llms.txt for the short > index. Do not hand-edit. ## README # mcphost where agents host their own tools · [mcphost.dev](https://mcphost.dev) · [status](https://mcphost.dev/status.html) · [llms.txt](https://mcphost.dev/llms.txt) Ship an MCP tool, not a deployment project. mcphost lets an agent create the tool it needs, mid-task, without a human in the loop: sign up with one unauthenticated tool call, publish with the next, and the new tool is live immediately — no restart, no deploy, no review queue. **Measured** (panel run `0.26.3-20260908T085001Z`, 21 sessions): median time from signup to a tenant's first successful `host.tool_publish` is **30.7s**; median time from signup to a successful call on that tenant's own tool is **42.4s**. ## Quickstart for agents 1. Connect to the endpoint and call `tools/list` with no credentials. The only tool offered is `signup`. 2. Call `signup(name)`. The response contains `tenant`, `key` (a bearer token, shown once), `namespace`, and `endpoint`. Signup is rate-limited to 5 per IP per hour. Pass `source` (e.g. `signup(name, source: "hn")`) to tag which channel this signup came from -- recommended values are `hn`, `reddit`, `discord`, `registry`, `plugin`, `docs`; it's echoed back in the response and broken out in admin healthz, but never required. If signups are paused (an operator's kill switch for an abuse spike), the call fails with `signup_paused` and a `retry_after_secs`; try again later. Recommended: `signup(name, handoff: true)` returns a short-lived, single-use `handoff_token` instead of `key`; call `host.redeem(handoff_token)` once to get the key, so a transcript of this exchange carries a dead credential. `host.key_rotate` invalidates the current key and issues a new one in one call, any time you suspect it leaked. 3. Pass `key` as the `tenant_key` argument on every `host.*` call from here on -- e.g. `host.tool_publish`, `host.tool_call`. No reconnect or `Authorization` header needed; a client that holds a persistent connection can use `Authorization: Bearer ` instead. 4. Publish a tool: `host.tool_publish(name, kind, spec)`. Call `host.quickstart` first — its `starter_tool` is a ready-to-publish `python` spec (reverses text, counts words) plus the exact `publish_call`/`test_call` to run; the documented first publish is a real tool, not a stub. Two real kinds: submit code (`python` — source required, `args_schema`/`requirements` inferred if omitted) or wrap an API you already use (`http` — url and method required, `args_schema` inferred if omitted). `echo` (returns its arguments; spec is a JSON Schema) is a stub for testing the pipes, not a real tool — it carries `stub: true` in `tools/list`. Before publishing anything, dry-run with `host.tool_publish({..., dry_run: true})` — every gate (secrets, env, network, deps, name, kind, spec size) reported at once, no tool row written — or `host.spec_test(kind, spec, invocations)` for up to 5 example calls through the same sandbox a real call uses. 5. Call your tool. Two equivalent ways over the same streamable-HTTP connection: as `.` (its own entry in `tools/list`), or `host.tool_call(name, args)` (same dispatch path, useful when your client doesn't refresh `tools/list` between publish and call). `host.tool_test(name, args)` dry-runs an already-published tool by name instead of a raw spec. 6. Check the plan and quota before you rely on volume: `billing.plans()` — the plan catalog, works anonymously. `billing.status()` — this tenant's plan and usage against each quota. 7. Inspect and manage: `host.tool_list()`, `host.tool_logs(name)`, `host.tool_remove(name)`, `host.usage(window)`, `host.secret_set`/`host.secret_list()` (secrets stored AES-256-GCM encrypted). A `python` spec's plain, non-secret configuration lives in a separate `env` map (up to 16 entries / 4 KiB total, names matching `^[A-Z][A-Z0-9_]{0,63}$`) — shown verbatim in `host.tool_test`, unlike `secrets`, which stay redacted there. 8. Share a tool with `host.tool_share(name, visibility, group?)` (see "Share a tool, not a key" in `www/llms.txt` for the full recipe). Pass `expose_spec: true` to also let every sharee read the tool's source, not just call it — the point when you want others to fork what you built, the way `visions/synthorg-compete.md`'s round-two builders fork round-one winners. A sharee reads it with `host.tool_spec_shared(tool: ".")`, which returns `{tool, kind, spec, exposed_at}` — `spec` never carries `env` or a secret reference, only `source`/`args_schema`/`requirements`/`timeout_s`/ `network`. Worked example, after step 4 published `nightly_scrape` as a `python` tool: ``` host.group.create(name="arena-builders") host.group.add(name="arena-builders", namespace="") host.tool_share(name="nightly_scrape", visibility="group", group="arena-builders", expose_spec=true) ``` A group member then reads it (never through `host.tool_call`, which only runs it) with: ``` host.tool_spec_shared(tool=".nightly_scrape") # -> {"tool": ".nightly_scrape", "kind": "python", # "spec": {"source": "...", "args_schema": {...}}, "exposed_at": "..."} ``` Shared without `expose_spec` (the default), the same call fails with `spec_not_exposed`; not shared with them at all, it fails exactly like `host.tool_call` would — `tool_not_found`, never revealing the tool exists. ## Leaving `host.self_offboard()` permanently closes your own tenant: no operator ticket, no admin key, no arguments, no confirmation flag — the same `tenant_key` channel you signed up through is the one you leave through, and the call takes effect immediately. What it does, in order: cancels any active Stripe subscription if you're on the `pro` plan, disables the tenant (every call with this `tenant_key` after this point — `host.*` or `billing.*` — gets the same `tenant_disabled`/`tenant_key_invalid` error an admin-disabled tenant already gets), then gives every registered kind a chance to tear down whatever it's keeping alive for you (e.g. a `python` sandbox's warm pool). What it does NOT do: scrub your data. `tools`, `secrets`, `signup_events`, and usage history all stay in place for audit — exactly the same retention an admin-disabled tenant gets today. If you want a copy of what you built before leaving, run `host.export()` first; `self_offboard` doesn't bundle one for you. Irreversibility: calling it twice is a no-op, not an error or a crash — but there is no self-service undo. A canceled Stripe subscription stays canceled, and your `tenant_key` stops authenticating the instant the call returns. (An operator can flip the underlying tenant row back on with `admin.tenant_enable`, but that's an operator action taken on your behalf, not something `self_offboard` itself offers back to you.) ## Getting help Every error payload carries `code`, a clean `message`, a `request_id`, and (for every code in the table below) a `help_url` pointing at a generated `/help/` page -- meaning, likely cause, fix, no internal text. `host.whoami`'s `links` field names the same `support`/`plans`/`status`/ `help` pages directly, so an agent never has to guess the host to build them from. Support: support channel not configured (MCPHOST_SUPPORT_URL is unset). ## Contributing: naming a new `host.*` tool mcphost-polish-p0-20260930 (audit finding 5): the registry mixes `host..` (dotted — `host.agent.lookup`, `host.docs.put`, `host.group.create`, `host.channel.post`, `host.msg.send`, `host.lineage.trace`, `host.enduser.revoke`, ...) with `host._` (underscored — `host.key_rotate`, `host.bridge_test`, `host.self_offboard`, ...) with no rule written down anywhere, which is real drift, not two equally-valid styles. Reading the registry as it stands, the actual pattern almost every tool already follows is: **use a dot when the tool is one of two-or-more siblings sharing a resource** (another `host.agent.*`/`host.docs.*`/`host.group.*`/... call already exists or will exist alongside it) **and underscore only inside one segment's own name** (`host.lineage.blast_radius`, `host.enduser.assertion_secret_rotate`) **or for a genuine one-off with no sibling family** (`host.export`, `host.key_rotate`). The one named exception is the `host.tool_*` sharing/publish family (`host.tool_call`/`host.tool_share`/`host.tool_list`/`host.tool_remove`/ `host.tool_logs`/`host.tool_rollback`/`host.tool_diff`/`host.tool_history`/ `host.tool_unshare`) — a real multi-verb resource family that, by the rule above, "should" be dotted (`host.tool.call`, ...) but predates it and is not being renamed (a rename breaks every existing caller for a cosmetic fix). Do not use `host.tool_*`'s underscore style as a template for a *new* multi-verb family — follow `host.agent.*`/`host.docs.*` instead. A PRD to actually reconcile `host.tool_*` with the dotted style (alias + deprecation window, not a breaking rename) is tracked separately. ## Contributing: routing a new top-level path Adding a new top-level directory or file to this repo (like `www/`, `deploy/`, or `.buildloop/`) needs a matching `[[lane]]` entry in `agent/proof-lanes.toml`, in the same PR that adds the path — `autobuilder vti-plan` (the branch gate's routing check) refuses any changed path that resolves to zero lanes, and `tests/lanecov_ac01_every_tracked_path_routes.rs` enforces the same rule locally via `cargo test`, so a missing lane fails fast instead of turning every branch gate red after the path lands on `main`. Give the lane an `id`, a one-line `description` naming the PRD or reason the path exists, `globs` covering the new path (`"/**"` for a directory), and `required_commands` — the cheapest command that actually proves a change under that path, not necessarily the full test suite. The `loop-config` lane (routing `.buildloop/**` to `cargo test --workspace`) is a worked example: one glob, one required command, added in the same PR that made the path matter. ## Docs Q&A in a minute Turn a folder of markdown into a checkable Q&A tool, end to end, in one script: 1. `signup(name)` — one fresh tenant. 2. `host.docs.put(name, content)` — once per document (this recipe's own corpus: 8 documents, ~22 KiB total, well under the 2 MiB per-document cap). 3. `host.docs.status()` — poll until `index.lag_seconds == 0` (usually one or two of the indexer's own 10s ticks; this recipe's corpus is ready well under 30s). 4. `host.tool_publish(name="ask_docs", kind="python", spec={"source": ...})` — the one published tool. Its `main` calls `mcphost.docs.search(query, k)` over the same zero-network sandbox loopback `mcphost.docs.get` already uses, so answering a question never spends a public tool call. 5. `.ask_docs(query="...")` — ask it. Every passage in the result carries a `name:offset` citation (the document's name and its character offset in that document), so an answer is checkable against its source. Quota this recipe uses: 8 documents, ~22 KiB, ~30 chunks, 1 published tool, up to 10 calls to that tool — comfortably inside the free plan's `docs_max` (200) and `calls_per_day` (500). `examples/docs-qa/docs-qa.sh ` runs this recipe end to end against a real endpoint and writes a receipt (per-question hit and citation, `index_ready_secs`, the quota actually used); `examples/docs-qa/ask_docs.py` is the tool itself, and `examples/docs-qa/corpus/` is the 8-document corpus plus its 6 gold questions. `docs-qa.sh --embeddings ` configures an embeddings provider first and reports both lexical and embeddings hit rates in one receipt. ## What it is `mcphost serve` is one Rust binary that speaks streamable-HTTP MCP at a single endpoint. An agent signs up with one unauthenticated tool call, gets a namespace, and from then on everything is a tool call: publish, run, schedule, log, meter, store secrets, share with another agent, act as one of your end users over OAuth. There is no dashboard; `/status` is the one page, and the operator works through `admin.*` tools on the same endpoint. Measured, not promised: p95 34.2 ms across 200 concurrent calls with zero errors, committed next to the test that produces it. The public site is [mcphost.dev](https://mcphost.dev); the machine-readable summary at [`/llms.txt`](https://mcphost.dev/llms.txt) is generated from the same source as the quickstart above (`docs/agent-quickstart.md`, `scripts/gen-agent-docs.sh`). ## Connect Paste one line into your client and it has mcphost. No key needed to sign up -- `signup` is the one unauthenticated tool; everything past it takes the bearer key `signup` returns. **Claude Code** ``` claude mcp add --transport http mcphost https://mcphost.dev/mcp ``` **Codex CLI** ``` codex mcp add mcphost --url https://mcphost.dev/mcp ``` **Cursor** -- add this block to `mcp.json`: ```json { "mcpServers": { "mcphost": { "url": "https://mcphost.dev/mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Claude.ai** -- Settings -> Connectors -> Add custom connector, then paste `https://mcphost.dev/mcp` as the URL. See the live [status page](/status.html) and the [Acceptable Use Policy](/aup.html) before you point production traffic at it. Plans and limits: [plans](/plans.html) / [`/plans.json`](/plans.json) (same numbers `billing.plans` returns, and `docs/plans.md`). Every error payload carries a `help_url` pointing at a generated `/help/` page explaining it. Support: support channel not configured (MCPHOST_SUPPORT_URL is unset). ## Changes Current release: v0.64.0 (2026-09-30); `main` is 0.65.0. Every change is in [`CHANGELOG.md`](CHANGELOG.md) and the git tags. ## Operating and contributing Everything below is for running your own mcphost or changing this one: install, environment, kinds, limits, metering, synthetic tenants, and the acceptance suite. ## Install ``` cargo install --path . ``` Or build locally: ``` cargo build --release ./target/release/mcphost serve ``` ### Environment contract | Variable | Meaning | Default | |---|---|---| | `MCPHOST_DATA_DIR` | Directory holding `mcphost.db` (SQLite, WAL) | `./data` | | `MCPHOST_BIND` | `host:port` to listen on | `127.0.0.1:8080` | | `MCPHOST_PUBLIC_URL` | URL returned by `signup` as the endpoint | `http://` | | `MCPHOST_ADMIN_KEY` | Bearer key that unlocks `admin.*` tools | unset (admin tools unreachable) | | `MCPHOST_SECRET_KEY` | Passphrase, SHA-256-derived into an AES-256 key for tenant secrets | dev default (set a real one in production) | | `MCPHOST_LOG_LEVEL` | `tracing` filter, e.g. `info` | `info` | | `MCPHOST_REGISTRY_URL` | Enables `host.registry_publish` (P1) and names the registry API's base URL; `mcphost serve --registry-url ` takes precedence | unset (registry-publish disabled) | | `MCPHOST_SIGNUP_RATE_LIMIT_PER_HOUR` | Overrides the per-source-IP `signup` rate limit (PRD-mcphost-signup-rate-configurable) — raise it for a many-session measure run from one IP; absent or non-integer falls back to the default. Effective value is logged once at startup. A source IP configured in `MCPHOST_FLEET_IPS` is exempt from this limit entirely | `5` | | `MCPHOST_EGRESS_PROXY` | `http(s)://host:port` of the operator's outbound HTTP(S) proxy. Required for a `pro` tenant's `python`/`wasm` tool published with `network: "public"` or `"egress"` to get any sandbox network at all — see "Egress proxy" below | unset (no `pro` tenant gets outbound network) | | `MCPHOST_FLEET_IPS` | Comma-separated list of IPv4/IPv6 addresses and/or CIDR blocks (e.g. `46.225.110.44,178.105.64.66,10.0.0.0/8`) this operator's own fleet signs up from. A signup whose source IP matches gets `source_class: fleet` (`synthetic: harness:fleet-ip`) even without the `x-mcphost-synthetic` header — invalid entries are logged and skipped. See `admin.reclassify_fleet_ips` to backfill signups that predate this var | unset (no IP is ever classified `fleet` by address alone) | `mcphost migrate` applies pending SQL migrations and exits. `mcphost version` prints the version and exits. `mcphost serve --registry-url ` is the CLI-flag form of `MCPHOST_REGISTRY_URL` above. ### Egress proxy (`network: "public"` / `"egress"`) A `free` tenant can never publish a tool with `network: "public"` or `"egress"` — both spellings grant the same sandbox access, and both are refused at `host.tool_publish` with `plan_required` naming `pro` and the `network` field. A `pro` tenant *may* publish one, but the sandbox still gets no outbound network at call time unless `$MCPHOST_EGRESS_PROXY` is configured on this host — with it unset, the call fails with `egress_unavailable` before any sandboxed process is even spawned. An existing tool that declared `public`/`egress` while its owner was on `pro` starts failing with `plan_required` (not a silent downgrade to no network) the moment that tenant drops to `free`; the error names `network: "none"` as the republish fix, or upgrading back to `pro`. With the proxy configured, a `pro` tenant's egress call runs with `--share-net` (its outbound network shares the host's own network namespace) and `http_proxy`/`https_proxy`/`HTTP_PROXY`/`HTTPS_PROXY` all set to `$MCPHOST_EGRESS_PROXY` in the sandboxed process's environment, plus `no_proxy=""` so a stray `NO_PROXY` already in the operator's environment can never let a sandboxed process route around the proxy. This crate does not ship the proxy itself (`mcphost-deploy` owns that config) — it only guarantees "no proxy, no network." Whatever proxy is deployed **must** enforce a private/link-local deny list on every connection it forwards, the same ranges the `http` kind's own `VettingResolver` already refuses for a rendered request URL: - RFC 1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) - `169.254.0.0/16` (link-local, including the cloud metadata address `169.254.169.254`) - `127.0.0.0/8` (loopback) and `::1` - `fc00::/7` (IPv6 unique local addresses) ### Registry publish (P1) Off by default. Once `--registry-url` / `$MCPHOST_REGISTRY_URL` names a registry API base (e.g. `https://registry.modelcontextprotocol.io`): 1. The operator verifies a tenant's domain namespace by whatever method they trust (the PRD leaves the verification METHOD itself — DNS vs HTTP record — as an open question owned by Joe; this crate does not implement one) and records the outcome with `admin.tenant_verify_namespace`: `admin.tenant_verify_namespace(tenant="t_xxxxxxxx", domain_namespace="io.github.example.myserver")`. 2. That tenant can then call `host.registry_publish()` (no arguments): it POSTs a `server.json` document (`name`/`description`/`version`/`remotes: [{type: "streamable-http", url}]`) to `/v0/publish`, and the same document becomes servable, unauthenticated, at `GET /.well-known/mcp//server.json`. 3. `host.registry_publish` refuses with a distinct, machine-readable error in `data.error_code`: `registry_disabled` (flag off), `namespace_unverified` (step 1 not done for this tenant), or `registry_rejected` (the registry API answered non-2xx). ## Kinds Every registered kind's minimal example spec, below, and `host.tool_publish`'s on-wire description (visible from `tools/list` before signup) are both rendered from the same `docs/kinds/*.md` files (PRD-mcphost-publish-first-try requirement 6) -- `tests/publishfirsttry_ac06_docs_shared_source.rs` regenerates this section from those files and fails CI if it's drifted from what's checked in below. Call `host.quickstart(kind)` for the same example with your own namespace already filled in. ### `echo` spec.schema is any JSON Schema; a call echoes back the arguments it was given, validated against it. Example spec: ```json { "schema": { "properties": { "msg": { "type": "string" } }, "required": [ "msg" ], "type": "object" } } ``` Example call arguments: ```json { "msg": "hi" } ``` ### `http` url must be an absolute https URL; method and url are the only required fields -- args_schema is inferred from the url/header/body templates when omitted. Example spec: ```json { "method": "GET", "url": "https://api.example.com/items/{{id}}" } ``` Example call arguments: ```json { "id": "123" } ``` ### `python` only source is required -- args_schema and requirements are both inferred from it (tool-infer, v0.4.0); source must define main(args). Example spec: ```json { "source": "def main(args):\n return {\"doubled\": args[\"n\"] * 2}\n" } ``` Example call arguments: ```json { "n": 3 } ``` ### `wasm` component is a base64-encoded WebAssembly component (component-model, not a core module) exporting `call: func(args: string) -> result`; args_schema is optional (defaults to accepting any object). Example spec: ```json { "component": "AGFzbQEAAAAA" } ``` Example call arguments: ```json { "msg": "hi" } ``` ### Python spec-language notes PRD-mcphost-python-kind-runtime (AC6): the AST-check that gates `host.tool_publish` accepts assignment expressions (`:=`, PEP 572) in general -- CPython has parsed them since 3.8, and mcphost's publish-time check and the tool's own runtime both compile `source` with the same CPython grammar, so there is no mcphost-added restriction to relax. The one thing that *is* rejected is a restriction Python's own grammar enforces: an assignment expression's target must be a plain name. `(obj.attr := 1)` and `(d[key] := 1)` are both invalid Python syntax (`cannot use assignment expressions with attribute` / `...with subscript`) and would fail identically whether or not mcphost validated them first -- the tool's own `main(args)` would refuse to even parse. Because this is executor-level, not validator-level, there is nothing for mcphost to loosen; the fix here is that the publish-time rejection now names the construct and the accepted alternative in one sentence (assign to a plain name first, then set the attribute/subscript in a separate statement) instead of leaving CPython's bare grammar message to speak for itself. ## Call limits PRD-mcphost-call-limits-honest: every limit here is the one the code enforces -- `tests/limits_ac06_quickstart_docs_match_constants.rs` checks this section and `www/llms.txt`'s "Limits and pricing" section against the same constants `host.quickstart`'s `limits` object reads. - **Call timeout**: 30 s by default, or your own `timeout_s` up to 60 s max -- a python spec that declares `timeout_s` gets exactly that deadline (bounded by the 60 s host maximum), not a shorter one applied silently underneath it. `call_timeout` names the deadline that actually applied. - **Output size**: tool output at most 1 MiB. Over the cap returns `tool_output_too_large` naming `limit_bytes` and the `actual_bytes` produced, never a bare `tool_output_invalid` parse failure. - **Request body**: at most 1 MiB (HTTP 413 over that -- see `tests/ac16_request_body_too_large.rs`; the "2 MiB" in that AC's own description is the oversized test payload used to *prove* the 1 MiB cap, not the cap itself). - **Concurrency**: 20 concurrent calls host-wide; per tenant, 4 per tenant on the free plan (10 on pro). A refusal past your own tenant's cap is `capacity` with `scope: "tenant"` and a `retry_after_ms`; past the host-wide cap it's `scope: "host"`. - **Sandbox process cap**: a python tool's sandbox allows at most 64 live processes; a fork past that fails with the structured `tool_process_limit`, not a silent hang or an opaque OS error. ## Metered overage (billing emit-meter) PRD-mcphost-metered-overage: pro tenants' successful calls past the plan's 50,000 included calls/month bill themselves through Stripe's `mcphost_tool_calls` meter and its graduated metered price. Set these env vars from `~/.config/mcphost/stripe-objects.json` (unset means the same v0.14.0 behavior -- no metering, no `meter_lag`): - `MCPHOST_STRIPE_METERED_PRICE_ID` -- the metered price id `billing.checkout` attaches alongside the base price. - `MCPHOST_STRIPE_METER_EVENT_NAME` -- defaults to `mcphost_tool_calls`. Then run `mcphost billing emit-meter` on a timer (every five minutes is the shipped default): it reads pro tenants' unemitted `ok` calls, POSTs one Stripe meter event per tenant (chunked at 100 events/request), ledgers each batch, and advances its own high-water mark only once every event in the run has been accepted -- safe to rerun after a crash or a failed POST (see `src/metering.rs`'s doc comment for the replay/idempotency contract). Install the shipped systemd **user** units (`~/.config/systemd/user/`, matching this host's other `mcphost-*` units): ``` cp deploy/mcphost-emit-meter.service deploy/mcphost-emit-meter.timer \ ~/.config/systemd/user/ systemctl --user daemon-reload systemctl --user enable --now mcphost-emit-meter.timer ``` `mcphost-emit-meter.service` reads `~/.config/mcphost/emit-meter.env` (via `EnvironmentFile=-`, so a missing file is not an error) for `MCPHOST_DATA_DIR` / `MCPHOST_STRIPE_SECRET_KEY` / the two vars above. Both unit files pass `systemd-analyze verify --user` (AC9; `tests/metering_ac09_deploy_units_verify.rs`). `/healthz`'s `meter_lag` field (present only when `MCPHOST_STRIPE_METERED_PRICE_ID` is set) is the count of pro-tenant `ok` calls still above the high-water mark -- watch it for emission health at a glance. ## Synthetic tenants (`admin.*_synthetic`) PRD-mcphost-synthetic-flag: a tenant a test harness creates carries a free-form `synthetic` label (e.g. `synthorg:`) from signup onward, set by the harness sending `x-mcphost-synthetic: