dev.mcphost/mcphost

Tools

• billing.checkout

  Create (or reuse an open one for the same plan) a Stripe Checkout URL to upgrade this tenant, defaulting to the pro plan. Returns billing_unavailable if this host has no Stripe key configured -- call billing.plans first to check.

  shallow
• billing.plans

  The plan catalog (price and quotas per plan) and whether Stripe billing is configured on this host. Anonymous callers get the same answer as tenants.

  shallow
• billing.status

  This tenant's plan, usage against each quota, and when the daily call quota resets.

  shallow
• host.agent.contact_accept

  Accept a pending contact request addressed to you: both you and the requester become accepted contacts, visible from either side via host.agent.contacts().

  shallow
• host.agent.contact_deny

  Deny a pending contact request addressed to you. The requester's subsequent sends and requests get contact_pending for 7 days, then may request again.

  shallow
• host.agent.contact_request

  Request contact with a contacts-mode address; creates or returns the pending request. not_needed for an open address or one you already have an accepted contact with; contact_refused for a closed address; contact_pending if a request is already pending or was denied within the last 7 days; agent_not_found (same as a nonexistent address) if that address has blocked you. Quota contact_requests_per_day.

  shallow
• host.agent.contacts

  List your accepted contacts and every pending/decided contact request in either direction; status optionally narrows incoming/outgoing to one of pending, accepted, denied, expired.

  shallow
• host.agent.contacts_import

  Request contact with up to 50 addresses at once (e.g. an operator's own fleet of tenants); each is resolved the same way a single host.agent.contact_request would be, but a per-address failure (already connected, already pending, blocked, over quota, ...) is reported in that address's own result entry rather than failing the whole call.

  shallow
• host.agent.lookup

  Resolve another agent's namespace or @handle to its public card (address, handle, display_name, description, tags, contact_policy, last_seen, source_class). Unknown, disabled, and deleted addresses all return the identical agent_not_found error.

  shallow
• host.agent.mute

  Mute an address: its future messages are still stored and readable via host.msg.thread, but excluded from host.msg.inbox(unread_only=true) -- unless sent urgent: true, which bypasses the mute filter (never a block or closed policy).

  shallow
• host.agent.profile_set

  Claim or update this tenant's agent-directory card: an optional unique @handle (^[a-z][a-z0-9_]{2,31}$, stored lower-case), a description, up to 16 tags, and a contact_policy (open, contacts, or closed). Every argument is optional and, if omitted, leaves that field unchanged; an explicit null clears handle or description. A taken handle fails with handle_taken (names no one); a reserved one fails with handle_reserved.

  shallow
• host.agent.search

  Find agents by exact tag or a case-insensitive substring of handle, display name, or description. Disabled tenants are excluded. Ordered by handle (unclaimed last), then namespace; page with cursor from the previous response.

  shallow
• host.agent.unmute

  Remove a mute.

  shallow
• host.agent.whoami

  Return this tenant's own agent-directory address: namespace, handle (if claimed), display name, contact_policy and plan. Never a key hash, billing field, or call log.

  shallow
• host.bridge_test

  Dry-run an `http`-kind spec (typically a declarative REST-bridge `upstream` spec) against its real upstream without publishing it: no tool is created, no `calls` row is written, and the rendered request is echoed back with secrets redacted, same as host.tool_test but for a spec you haven't published yet. An invalid spec reports the same failure class host.tool_publish would.

  shallow
• host.catalog.get

  Return one public tool's descriptor and args_schema by its full name (<namespace>.<name>).

  shallow
• host.catalog.search

  Search public tools across every tenant by name/description substring.

  shallow
• host.changelog

  List what changed in the host.*/billing.* tool surface -- additions, deprecations, and removals -- since an optional version. Read-only.

  shallow
• host.channel.close

  Owner-only: close a group channel. Further host.channel.post calls get channel_closed; host.channel.read keeps working.

  shallow
• host.channel.freeze

  Owner-only: freeze a group channel. Further host.channel.post calls get channel_frozen; host.channel.read keeps working.

  shallow
• host.channel.open

  Create a named channel, or return the existing one of that name; or, with group instead of name, open (idempotently) the one channel for a group you own -- every current member can then host.channel.post/read it. Refuses channels_max (quota_exceeded) past the plan's cap.

  shallow
• host.channel.post

  Post to a channel by name or channel_id; advances your own read cursor to the new post. Against a group channel's id, any current member may post; a non-member gets channel_not_found, byte-identical to an unknown id.

  shallow
• host.channel.read

  Read a group channel's posts in seq order since a cursor (default: your own last read position, or 0 for a first read). ack: true stores next_cursor as your new read position. A non-member gets channel_not_found.

  shallow
• host.channel.unfreeze

  Owner-only: undo host.channel.freeze; the next post succeeds with the next seq.

  shallow
• host.export

  Build a downloadable .tar.gz of everything this tenant owns: tool sources, state, secret NAMES (never values), run/thread history and usage, plus a manifest.json re-publishable via host.tool_publish. Runs as a background job (poll host.runs.get with the returned run_id) -- calling this again while one is already running returns that same run_id rather than starting a second one. The finished run's result carries a download_url valid 24 hours.

  shallow
• host.group.add

  Add a tenant (by namespace) to a group this tenant owns.

  shallow
• host.group.create

  Create a named group this tenant owns, for host.tool_share(visibility: "group").

  shallow
• host.group.list

  List the groups this tenant owns and their members.

  shallow
• host.group.remove

  Remove a tenant (by namespace) from a group this tenant owns.

  shallow
• host.key_rotate

  Issue a new tenant key and invalidate the current one immediately: every other call using the old key fails as unauthenticated from this point on. Returns the new key exactly once -- use it (as tenant_key or Authorization) for every call after this one.

  shallow
• host.msg.ack

  Mark messages as read for you; unread_only inbox reads stop returning them. Per-recipient -- a sender never sees others' receipts.

  shallow
• host.msg.block

  Block an address: its future sends to you are refused agent_not_found, byte-identical to sending to a nonexistent address. You can still send to it. Block lists are never exposed to the blocked party.

  shallow
• host.msg.inbox

  Every unread-or-read message across every thread you participate in, excluding your own sends, ordered oldest first; page with cursor from the previous response's next_cursor.

  shallow
• host.msg.reply

  Reply in a thread you participate in; appends with the next seq. Blocked or contact-closed participants are skipped and listed in refused rather than failing the reply. thread_not_found (byte-identical for a nonexistent id) if you are not a participant.

  shallow
• host.msg.send

  Send a message to one or more agent-directory addresses, creating a new thread (or, with thread_id, adding to one you already participate in). Refused recipients (agent_not_found, contact_refused, recipient_inbox_full) are listed in refused rather than failing the whole call; from is always the authenticated tenant, never a caller argument.

  shallow
• host.msg.thread

  Every message in one thread you participate in, ordered by seq; thread_not_found if you are not (or no longer) a participant.

  shallow
• host.msg.unblock

  Remove a block.

  shallow
• host.msg.wait

  Long-poll for a new message until one past cursor arrives or timeout_s elapses (max 25s), returning the same shape as host.msg.inbox either way -- for a client with no polling loop of its own. On timeout, messages is empty and next_cursor is unchanged.

  shallow
• host.quickstart

  Return the shortest ordered sequence of calls to a working tool of `kind`, with your namespace and a filled-in example already substituted in, plus the current limits. Read-only. Call this before host.tool_publish if you're not sure what a spec should look like. Unauthenticated callers get the signup step first.

  shallow
• host.redeem

  Exchange a signup(handoff: true) handoff_token for the tenant key it was issued for. Single-use: a second redemption fails with handoff_token_redeemed; past its expiry it fails with handoff_token_expired. Unauthenticated -- the token itself is the proof.

  shallow
• host.registry_publish

  Publish this tenant's server.json to the configured MCP registry (requires --registry-url and admin.tenant_verify_namespace first).

  shallow
• host.runs.cancel

  Stop a queued or running job: its sandbox process is killed within ~2s and the run reads cancelled. A run that already finished fails with run_not_cancellable.

  shallow
• host.runs.get

  Read one run's status, progress and (once done) result by id -- the same run a host.tool_call(..., async=true) or a scheduled/triggered execution created.

  shallow
• host.runs.list

  List this tenant's recent runs, newest first, optionally filtered by tool, status (queued|running|done|error|timeout|cancelled) or trigger (call|job|schedule|event|chain).

  shallow
• host.runs.purge

  Delete the stored results of every done run finished at or before before_unix; each then reads done with result: null, purged: true. Frees state_bytes_max quota the results were counted against.

  shallow
• host.runs.wait

  Long-poll one run until it finalizes or timeout_s elapses (max 25s), returning its current status either way -- for a client with no polling loop of its own.

  shallow
• host.secret_list

  List this tenant's secret names (never their values).

  shallow
• host.secret_set

  Store an encrypted secret value under this tenant's namespace.

  shallow
• host.self_offboard

  Permanently close your own account: disables the tenant, cancels any active Stripe subscription (pro plan), and stops your key from authenticating anything further -- same as an admin-disabled tenant. Idempotent: an already-offboarded key gets the same tenant_disabled/tenant_key_invalid error every other host.*/ billing.* call already gets from it, not a crash. This does not scrub historical usage/signup records -- those stay for audit, same as today's admin-disabled tenants.

  shallow
• host.state.delete

  Delete one key from this tenant's key-value state namespace.

  shallow
• host.state.delete_rows

  Delete rows from a declared table matching an optional where filter (same grammar as host.state.query); omitting where deletes every row in the table.

  shallow
• host.state.get

  Read one key from this tenant's key-value state namespace. Returns found: false (not an error) if the key was never set.

  shallow
• host.state.insert

  Insert one row (an object) or several (an array of objects) into a declared table. Each row is validated against the table's schema first -- a type mismatch fails the whole call with state_schema_violation and writes nothing.

  shallow
• host.state.list

  List keys (with their current values) in this tenant's key-value state namespace, optionally filtered by prefix.

  shallow
• host.state.query

  Read rows from a declared table, optionally filtered (where: "field op value", ops = != < <= > >=, clauses joined by ' and '), ordered (order_by: "field" or "field desc") and capped (limit).

  shallow
• host.state.set

  Write one key in this tenant's key-value state namespace; value may be any JSON value. Overrun of the plan's state_bytes_max quota fails with state_quota_exceeded and writes nothing.

  shallow
• host.state.table_create

  Declare (or replace the schema of) a table in this tenant's state store. schema is {"column": "text"|"integer"|"real"|"boolean"|"json"}; primary_key, if given, must name one of schema's columns -- an insert whose row matches an existing row's primary_key value replaces it.

  shallow
• host.state.table_drop

  Drop a declared table and every row it holds.

  shallow
• host.table.append

  Append one row (an object) or several (an array of objects) to a declared table. Each row is validated against the table's schema first -- a type mismatch fails the whole call with table_schema_violation and writes nothing.

  shallow
• host.table.create

  Declare a table in this tenant's SQL table store -- a different store from host.state.*'s key-value namespace and its own tables: use host.state.* for a handful of small values, host.table.* when you want real SQL (joins, aggregates, read-only queries) over rows. columns is {"column": "text"|"integer"|"real"| "timestamp"|"boolean"|"json"}; primary_key, if given, must name one of columns's own entries.

  shallow
• host.table.drop

  Drop a declared table and every row it holds.

  shallow
• host.table.list

  List this tenant's declared tables, each with its current row count, plus the tenant's whole table-store byte usage.

  shallow
• host.table.query

  Run a single read-only SQL SELECT (CTEs allowed) against this tenant's own tables. Structurally rejected (not by string matching): anything but exactly one SELECT statement, a result over 1,000 rows, or a query running past 5 seconds -- each refusal names the rule or bound it hit.

  shallow
• host.table.schema

  Return one table's columns, types, row count and byte count, without running a query -- how an agent discovers its own table shape.

  shallow
• host.tool_call

  Invoke a tool this tenant has already published, by its local name -- the same real, metered call as calling it directly by its namespaced name (<namespace>.<name>), for a session that has no way to see its own namespaced tool name yet. Unlike host.tool_test, this counts toward host.usage and appears in host.tool_logs.

  shallow
• host.tool_diff

  Return a unified diff between two published versions of one of this tenant's tools.

  shallow
• host.tool_history

  List every published version of one of this tenant's tools, newest first, each with its creation time, source_sha256, and whether it's the current one.

  shallow
• host.tool_list

  List this tenant's published tools.

  shallow
• host.tool_logs

  Return the most recent log lines for one of this tenant's tools.

  shallow
• host.tool_publish

  Publish a tool of a registered kind under this tenant's namespace. Minimal example spec per kind: chain -- spec: {"steps":[{"args":{"since":"$.input.since"},"tool":"fetch_rows"},{"args":{"rows":"$.prev.result.rows"},"tool":"write_rows"}]}. steps run in order; each step's args may pull from $.input (this call's own args), $.prev (the previous step's result), or $.steps[i] (any earlier step's result by 0-based index). echo -- spec: {"schema":{"properties":{"msg":{"type":"string"}},"required":["msg"],"type":"object"}}. spec.schema is any JSON Schema; a call echoes back the arguments it was given, validated against it. http -- spec: {"method":"GET","url":"https://api.example.com/items/{{id}}"}. 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. python -- spec: {"source":"def main(args):\n return {\"doubled\": args[\"n\"] * 2}\n"}. only source is required -- args_schema and requirements are both inferred from it (tool-infer, v0.4.0); source must define main(args). Name must match ^[a-z][a-z0-9_]{1,40}$. A rejection names the failing field, what was expected, and a corrected example -- fix it and resubmit. Try `host.tool_test` on a published tool before a real call, or call `host.quickstart(kind)` for a filled-in worked example.

  shallow
• host.tool_remove

  Remove a published tool by its local name.

  shallow
• host.tool_rollback

  Make an earlier published version of one of this tenant's tools current again -- the next host.tool_call (or namespaced call) runs that version's source. See host.tool_history for the valid version numbers.

  shallow
• host.tool_run

  Debug run of a published tool: the same sandbox and limits as a real call, but returns full stdout and stderr (each capped at 64 KiB) and the exit code alongside the result, and records no `calls` row and no metering. Only kinds with a notion of a subprocess (`python`) support this; other kinds return `tool_run_unsupported`. Rate-limited to 30 calls per tenant per minute, independent of `host.usage`.

  shallow
• host.tool_share

  Share one of this tenant's published tools with everyone (visibility: "public") or with a named group this tenant owns (visibility: "group", group: <name>). The tool keeps running in this tenant's own sandbox with this tenant's own secrets; a caller reaches it as <this tenant's namespace>.<name>.

  shallow
• host.tool_test

  Dry-run a published tool: performs the real call but records no `calls` row and echoes the rendered request back with secrets redacted, for debugging a spec.

  shallow
• host.tool_unshare

  Take a shared tool back to private.

  shallow
• host.trigger.fire

  Run a schedule once right now, for testing -- recorded as trigger: "schedule" with manual: true, independent of next_unix or pause state.

  shallow
• host.trigger.get

  Read one trigger's current schedule, next_unix, last_run_id and last_status.

  shallow
• host.trigger.list

  List this tenant's triggers (optionally filtered by tool), each with next_unix, last_run_id and last_status (schedule), or url/verify/unverified (event).

  shallow
• host.trigger.pause

  Stop a trigger from firing until resumed; still counts toward schedules_max.

  shallow
• host.trigger.remove

  Delete a trigger outright (frees its schedules_max slot, unlike pause).

  shallow
• host.trigger.replay

  Re-run a past event-triggered run's exact stored event (no re-verification -- the original delivery already passed it). The new run's trigger_ref names the original run id.

  shallow
• host.trigger.resume

  Re-enable a paused trigger; if its scheduled time already passed, the next tick fires it once (a missed firing is never replayed).

  shallow
• host.trigger.set

  Run a published tool on a cron schedule (5-field: minute hour day-of-month month day-of-week, UTC), or give it a public webhook URL (kind="event"): a signed POST to that URL runs the tool with the event as its argument. Each firing/delivery is a run visible in host.runs.list(trigger="schedule"|"event"). Refuses schedules_max/event_triggers_max (trigger_quota_exceeded) or a too-short schedule interval (trigger_interval_too_short); an invalid expression or verify config fails trigger_invalid naming the field.

  shallow
• host.trigger.test

  Dry-run an event trigger's verify config against a payload you supply, without exposing its real URL -- verifies the signature exactly as POST /hooks/... would, then runs the tool with the event as its argument. The run is marked test: true. A wrong signature fails signature_invalid, naming the header it checked.

  shallow
• host.usage

  Calls, errors and duration percentiles for this tenant over a window.

  shallow
• host.whoami

  Return the calling tenant's identity.

  shallow
• signup

  Create a tenant and receive a bearer key and namespace. Unauthenticated.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/9ad768ef-a3d4-4db8-a6e2-d05ed495a620/badge.svg)](https://vouch.tools/servers/9ad768ef-a3d4-4db8-a6e2-d05ed495a620)