mcphost

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.

Drop a declared table and every row it holds.

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.

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.

Return the generated semantic model for a declared table: per column its inferred type, null share, distinct count, min/max or top values, and role (key|category|measure|date|id|text); per table its row count, candidate primary key, detected foreign keys, and suggested measures/dimensions. Refreshes after append/create within 30s; a call right after a write returns the previous model with stale: true rather than blocking.

Drop a declared table and every row it holds.

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

Annotate a declared table or one of its columns -- the next describe merges this back in (an annotation's role wins over the inferred one; unit/description are added; hidden marks a column to omit from a summary). key must be one of role, unit, description, hidden.

List every declared table that has a computed semantic model, each with its version, staleness, row count and when it was last computed.

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.

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

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. Pass async: true for a tool that needs more than the call deadline: returns {run_id, status: "queued"} immediately instead of running inline -- see host.runs.get/wait. Pass version to pin the call to one of host.tool_history's versions instead of whichever is current.

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

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.

List this tenant's published tools.

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

Publish a tool of a registered kind (chain, echo, http, python, wasm) under this tenant's namespace. Call host.quickstart(kind) first for a filled-in example spec and the full publish-to-call sequence. Name must match ^[a-z][a-z0-9_]{1,40}$; a rejection names the failing field and a corrected example. Try host.tool_test before a real call.

Remove a published tool by its local name.

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.

Debug-run a published python tool: result.payload plus duration_ms and exit_code; for the other cases see host.quickstart.

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

Read a shared tool's kind and redacted spec -- only works when the owner shared it with expose_spec: true. The spec never carries env values or secret references (see host.tool_share's expose_spec).

Dry-run an already-published tool by name, no calls row written; for the other cases see host.quickstart.

Take a shared tool back to private.

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

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

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

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

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

Re-run a past event- or message-triggered run's exact stored event/envelope (no re-verification -- the original delivery already passed it). The new run's trigger_ref names the original run id. For a webhook trigger, pass id (the trigger) and row_id (an inbox_<name> row id, e.g. from POST /hook/...'s own response or host.state.query) instead of run_id -- a paused delivery has no run to replay from.

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

Run a published tool on a cron schedule (5-field: minute hour day-of-month month day-of-week, UTC), give it a public webhook URL (kind="event"): a signed POST to that URL runs the tool with the event as its argument, fire it whenever this tenant receives a message (kind="message"): the tool runs with the message envelope as its argument, or give it an inbound-inbox URL (kind="webhook"): a verified POST lands as a row in state table inbox_<name> and fires the tool with that row as its argument -- the response carries {url, secret} once (host.trigger.get afterwards never returns the secret again). Each firing/delivery is a run visible in host.runs.list(trigger="schedule"|"event"|"message"|"webhook"). Refuses schedules_max (trigger_quota_exceeded, shared by schedule and webhook triggers), event_triggers_max (shared by event and message triggers) or a too-short schedule interval (trigger_interval_too_short); an invalid expression or verify config fails trigger_invalid naming the field.

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. On a message trigger, runs the tool with a synthetic envelope (test: true, no messages row created). On a webhook trigger, builds and self-signs a synthetic body exactly like a real sender would, then stores and fires it through the same path POST /hook/... uses (one inbox row, one run). The run is marked test: true. A wrong signature fails signature_invalid, naming the header it checked.

Calls, errors and duration percentiles for this tenant over a window. Pass `by` ("tool", "caller", or "end_user") for a breakdown instead of the plain per-tenant summary: "caller" (only valid for a tool this tenant has shared) shows which tenant called in and how much; "end_user" shows which identified end user called, with the caller tenant folded into the key when the call crossed tenants. Breakdown rows cap at 1000 per page; pass the returned `cursor` back to page further.

Return the calling tenant's identity, including key_age_s and key_rotated_at for auditing credential hygiene.

Create a tenant and receive a bearer key and namespace. Unauthenticated. Recommended: pass handoff: true to receive a short-lived, single-use handoff_token instead of the raw key -- redeem it once with host.redeem to get the key, so a transcript of this call and the redeem call, if it leaks, carries a dead credential. The raw-key path (handoff omitted) stays fully supported.