# mcphost [Health: Active] **Category:** 💻 Developer Tools **Repository:** https://github.com/j0yen/mcphost **GitHub Stars:** 0 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/mcphost ## Description Hosted MCP runtime where the agent is the operator: sign up by tool call, publish your own tools. ## Claude Desktop Quick Installation Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client: ```json "mcpServers": { "mcphost": { "url": "https://mcphost.dev/llms.txt" } } ``` ## Documentation & README # mcphost `mcphost serve` is a streamable-HTTP MCP server, stateless per the 2026-07-28 specification, on which an agent signs up with one unauthenticated tool call, receives a tenant key, and then owns a namespace of tools it publishes, lists, inspects and removes through further tool calls. There is no web page. The operator administers tenants and reads metering through `admin.*` tools on the same endpoint. Tool *execution* kinds (REST wrappers, code) are separate PRDs; this one ships the endpoint, tenancy, the control plane, the `Kind` trait, and a built-in `echo` kind so the harness can measure the bootstrap path end to end. > **For agents evaluating this host:** the machine-readable summary lives at [`/llms.txt`](https://mcphost.dev/llms.txt) on the production endpoint. Signup is one unauthenticated tool call; the quickstart there is six steps. Built from `PRD-mcphost-endpoint.md` (vision: `visions/mcp-host.md`). ## Recent - **v0.11.0** — `host.tool_publish` reports every simultaneously-invalid field at once (`data.errors`, each with its own `field`/`expected`/ `example`) instead of one rejection per attempt; each kind's example spec/blurb and the new "Kinds" section below both render from `docs/kinds/*.md`, checked to match by `tests/publishfirsttry_ac06_docs_shared_source.rs`. - **v0.4.0** — `args_schema` (and, for `python`, `requirements`) is now optional on the `python` and `http` kinds: when absent, the host derives it deterministically and offline from the source/templates the tenant already wrote (`src/kinds/infer.rs`). An explicit `args_schema` is used unchanged. - **v0.1.2** — `synthorg consume --preflight` now has a real integration test (AC12); the `Kind` conformance suite moved to `tests/ac17_kind_conformance.rs`; `host.registry_publish` + `GET /.well-known/mcp//server.json` are implemented behind the `--registry-url` flag (AC19, see "Registry publish (P1)" below). ## 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 | `5` | `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. ### 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 } ``` ### 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. ## 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: