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 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/<namespace>/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

mcphost migrate applies pending SQL migrations and exits. mcphost version prints the version and exits. mcphost serve --registry-url <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 <registry-url>/v0/publish, and the same document becomes servable, unauthenticated, at GET /.well-known/mcp/<namespace>/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:

{
  "schema": {
    "properties": {
      "msg": {
        "type": "string"
      }
    },
    "required": [
      "msg"
    ],
    "type": "object"
  }
}

Example call arguments:

{
  "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:

{
  "method": "GET",
  "url": "https://api.example.com/items/{{id}}"
}

Example call arguments:

{
  "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:

{
  "source": "def main(args):\n    return {\"doubled\": args[\"n\"] * 2}\n"
}

Example call arguments:

{
  "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:<run_id>) from signup onward, set by the harness sending x-mcphost-synthetic: <label> on its signup call -- no behavior change, metadata only. /healthz's tenants_real / tenants_synthetic split, and admin.tenants' synthetic filter (true/false/all, default all), read this column so synthorg candidates --measure can exclude panel traffic from "real tenant" evidence.

Backfilling the existing census (every tenant predates this column, so all load with synthetic: null until tagged): use admin.tenants_set_synthetic, previewed with dry_run: true before the dry_run: false that applies it. The recipe this host's own census used: