Hosted MCP — the 24 tools your agent gets

Fetch the active model catalog (families, models, parameter schemas). Returns the data needed to choose model_id and build a valid parameters object for create_prompt / create_version. Cache for the session — the catalog is stable per deploy.

List the user's prompts (cursor-paginated). Pass cursor from a prior response's nextCursor to page; bogus cursors return invalid_cursor rather than silently falling back to the first page. Returns each prompt's id, name, currentVersionId, updatedAtUtc. Grant-restricted keys see only granted prompts.

Fetch a prompt by promptId, including its current version's promptText and modelSettingsJson. Response also includes currentVersionStatus = 'ok' | 'missing' so agents can detect when a prompt's currentVersionId points to a deleted version (call list_versions + switch_current_version to repair, or create_version with setAsCurrent: true).

Create a new prompt with an initial version. Top-level fields: name, promptText, modelSettings (object: {model_id, parameters}). Returns {promptId, currentVersionId}. Call get_catalog for valid model_id values + parameter shapes.

Patch a prompt's metadata (name, abbreviation). RFC 7396 merge-patch semantics: pass null to clear, omit to leave unchanged. Note: capability descriptions are now per-version — use update_version to edit them.

Soft-delete a prompt. Cascades hide records/versions/attachments under it; sweep job hard-deletes later. Requires per-prompt grant if the API key is restricted.

List all versions of a prompt (cursor-paginated). Response includes currentVersionId at the top level (so you don't have to round-trip get_prompt to know which version is active) plus each version's id, versionNumber, and updatedAtUtc.

Fetch a single prompt version by id. Returns full promptText and modelSettingsJson.

Append a new version to an existing prompt. The new version's versionNumber auto-increments server-side. Pass setAsCurrent: true to also activate it (atomic create + switch in one transaction).

Patch a version's metadata (versionDescription, description, descriptionMode). RFC 7396 merge-patch. Does NOT change promptText or modelSettings — those define the version's identity; create a new version for behavioral changes. Server-owned description: in Auto mode (the default), the server regenerates the capability description from promptText via gpt-5.4-nano on every promptText change. To take ownership and write the field yourself, send { description: "…", descriptionMode: 1 } in the same request — flipping to Manual atomically with the write. Otherwise description writes are silently ignored in Auto.

Set the prompt's currentVersionId. Used by an agent that just created a new version and wants to make it default.

Soft-delete a non-current version. Server returns 409 version_is_current if it's the prompt's current version — call switch_current_version first if needed.

Run a prompt as a new conversation. Required: promptId. Optional: userInput (the user's text for this turn), versionId (defaults to current), autoFinalize (default true). Streams output server-side and returns the final text in the tool's content[0].text. Image-modality runs return generated image bytes inline as MCP image content blocks (one per image, base64 PNG) so MCP-aware clients render them directly — no follow-up fetch needed. When autoFinalize: true the run also chains a finalize, returning a saved recordId via the SSE record_finalized event.

NOT a chat append. Re-renders the prompt's output with a revision instruction — the model receives a synthetic wrapper (Original input: … + Previous output: … + Revision instruction: …) and produces a fresh full output that supersedes the prior one. For multi-turn dialog, start a NEW run instead. Required: userInput AND exactly one of runId XOR recordId. Optional: intermediateOutput (overrides the model's prior-turn output), fromTurn (rewind primitive — drops session turns > N before applying). Same image-content-block delivery as run_prompt.

Promote an active run to a saved record. Idempotent (returns the same record) if the run already auto-finalized. Required: runId. Optional: finalText (Copy-with-edits — producing a value that differs from the model output creates an EDIT delta), tag (label for that EDIT delta — requires finalText to be present and to differ from the model output; use notes for record-level labels), notes (free-form record-level label), fromTurn. Calling on an already-Finalized session with new content reopens + re-finalizes. Validation errors (bad tag/fromTurn/finalText) reject without state mutation — no zombie sessions.

Drop an active run without finalizing. Required: runId. Idempotent. Returns 409 run_already_terminal if the run already completed.

Fetch an image from an active (non-finalized) run by 0-based index. Required: runId, n. Returns a single MCP image content block (base64 PNG). Most agents won't need this — run_prompt already returns images inline as content blocks. Use when revisiting an active run after losing the original tool result, or to re-fetch a specific image. For finalized records, use GET /api/v2/records/{recordId}/image?index={n} instead.

List finalized records (cursor-paginated). Filter by promptId. Returns slim DTOs with model output, cost (costMicroCents), image counts, and timestamps. Most-recent-first. Image records: outputText is null (the model output is the image, not text); imageStoredPaths is a typed array of opaque blob keys — fetch bytes via GET /api/v2/public/records/{id}/image?index=N.

Update notes and/or tag on a record the caller created. Same-source-same-principal: ApiKey callers must match the creating key; OAuth callers (chat MCP) can manage their own records. Tag attaches to the record's edit delta — server returns 409 record_no_edit_delta if no edit delta exists. Pass null to clear a field; omit to leave unchanged.

Soft-delete a record the caller created (same ownership rules as patch_record). Sweep job hard-deletes later. Records are execute-axis, not write.

Upload a file as a prompt attachment (text or image). Bytes via inline base64 or local file path. Server caps: per-file 10MB image / 5MB text; per-prompt 50MB total; per-user storage quota. Idempotent on (promptId, filename, content) — retries don't double-bill storage. TRUST: localPath is read by the MCP server with the user's permissions — only use paths the agent is authorized to read.

List a prompt's attachments. Returns slim DTOs (id, filename, type, size, createdAt). Use get_attachment to fetch the bytes.

Fetch an attachment's content. Reply has explicit kind: 'image' (returns imageMediaRef), 'text' (returns inline utf-8 string for text/json/xml/yaml), or 'binary' (returns mediaRef for any other content type — PDF/audio/video/octet-stream — instead of a corrupt UTF-8 decode). Inline ≤16MB raw, else a local tmpfile path.

Soft-delete an attachment + refund its bytes against the per-user storage quota. Server returns 409 attachment_referenced_by_active_run if any non-terminal run still uses this blob (retry after the run finalizes/expires).

Synthesized at tools/list emit time when the prompt has ExposeAsMcpTool=true. Input schema is a single optional userInput string. Dispatch resolves the prompt by exact-match (UserId, McpToolName), then runs the same pipeline as run_prompt. If the user toggles exposure off (or deletes the prompt) the tool name returns unknown_tool with a hint to re-list. Tool name is stable across prompt renames — an agent with a hardcoded name keeps working when the user tweaks the prompt's display name. If the user wants the tool name re-derived from the new prompt name, they click "Update tool name" in the settings panel (which calls POST /api/v2/prompts/{id}/mcp-rename).

Discovery: these only appear when the user has toggled them on (Settings panel on the prompt). MCP hosts cache tools/list aggressively — after a toggle, the user may need to start a new conversation or reconnect the connector for the new tool to appear.