mcphost

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.

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.

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

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

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.

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.

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.

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.

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.

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).

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.

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.

Remove a mute.

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.

Dry-run an unpublished http spec against its real upstream; for the other cases see host.quickstart.

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

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

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

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

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

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.

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.

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.

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

Soft-delete a document by id or name; still visible via host.docs.list {since} with deleted: true.

Read a document by id or name -- version defaults to the current one; text: true also returns the extracted plain text this document's mime produced at put time.

Configure this tenant's search index provider. provider: "none" (lexical only, the default) or "openai-compatible" (endpoint, model, and secret -- a tenant secret name used as the embeddings request's bearer -- all required). Changing config re-indexes every document from scratch in the background.

List documents in this tenant's document store. Without since, returns the current live snapshot; with since (a watermark from host.docs.status, 0 for everything), returns every document changed since, including deleted ones (deleted: true).

Drop stored versions of a document older than older_than_versions versions back from its current one -- get {version: <a dropped version>} then reads not found.

Write (or, for an already-used name, create a new version of) a document in this tenant's document store. mime is detected from name and content when omitted; allowed mimes are text/plain, text/markdown, application/json, text/csv. content (or content_base64 for arbitrary bytes) must be at most MCPHOST_DOC_MAX_BYTES (default 2 MiB). Identical content to the current version is a no-op that repeats the current version.

Force this tenant's search index to re-chunk (and re-embed, if a provider is configured) one document (document_id) or, without document_id, every document, on the indexer's next tick.

Ranked passage search over this tenant's document store. Lexical (BM25) by default; embeddings mode (set via host.docs.index_config) ranks by cosine and falls back to lexical (index.mode: "lexical-fallback") if the provider call fails. Returns [{document_id, name, version, chunk_no, offset, text, score}] plus an index block naming the mode and how stale the index is.

This tenant's document store counters: documents, bytes, text_bytes, the current change watermark, this plan's document/byte quotas, and an index block (mode, indexed_watermark, lag_seconds, pending_documents, chunks, rebuilding, quota_chunks_reached) describing the search index's own freshness.

Generate and store a new per-tenant secret for signing end_user_assertion (HS256 compact JWS, claims sub/iat/exp with exp <= iat + 3600). Returns the secret once; it is never shown again and never appears in host.secret_list. Assertions signed with any prior secret stop verifying immediately -- no overlap window.

One end user's calls (tool, outcome, run_id, impersonated) merged with its revoke/unrevoke/purge control-plane events, newest first, paged by cursor.

Export one end user's state rows and call history as a bundle at /exports/<run_id>, the same envelope host.export returns (download_url, size_bytes, expires_unix).

One end user's roster row (subject, issuer, first_seen, last_seen, calls_total, revoked_at, revoked_by, purged_at) plus its live state_rows, vault_connections, and runs_30d counts.

List this tenant's end users with last-seen and call counts, newest last-seen first. Optional since (unix seconds, filters last_seen), revoked (bool), limit (default 50, max 1000), and cursor (from a previous page's cursor field).

Delete a revoked end user's scoped state and vault-token rows, de-identify its calls rows (kept, never deleted), and set purged_at. Requires the end user to be revoked first (revoke_required otherwise). Returns {state_rows, vault_tokens} counts.

Revoke an end user: its next identified call is refused with end_user_revoked, no tool runs, and its vault-token connections are disconnected.

Reverse a prior host.enduser.revoke; the end user's calls succeed again.

The end user (if any) this call itself carries: {subject, issuer, method, verified_at} from the OAuth bearer's sub/iss or a verified end_user_assertion; null when the call carries no verified end-user identity.

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.

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

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

List the groups this tenant owns and their members.

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

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.

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

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.