MCP tools

The tools every instance's MCP server exposes, and what each one takes.

Tool inputs are JSON Schema. Each tool returns plain text plus structured output. Calls act as the signed-in user (or the token’s owner), and an artifact you can’t access is reported as not found.

Publishing

publish_artifact creates an artifact, or publishes a new version when you pass id. Pass exactly one of content or files.

Field	Notes
`id`	The artifact to publish a new version of. Leave it out to create one, or pass an id reserved by `create_upload`.
`title`	Required when creating (no `id`). Up to 200 characters.
`description`	Optional. Up to 2,000 characters.
`format`	`html`, `markdown`, `code`, or `pdf`. With `content`, pass `format` or `entry`; when it’s left out, it’s taken from the entry file’s extension (`.html`, `.md`, and `.pdf`; anything else is `code`).
`content`	A single file as a string. Needs `format` or `entry`.
`files`	Instead of `content`: a map of path to file, for an HTML page with its CSS, JS, and images. Each file is a string, `{ "base64": "…" }` for binary, or `{ "uploadId": "…" }` from `create_upload`.
`entry`	The file to open first. With `files`, it defaults to `index.html`, then `README.md`, then the first file.
`language`	Optional, for `code`. Taken from the entry file’s extension when it’s left out.
`message`	Optional change note for this version. Up to 500 characters.
`visibility`	`private`, `team`, or `public`. A new artifact without it gets the instance’s default visibility, which is `private` unless an admin changed it.
`capabilities`	The runtime API features the page may use: `{ "db": true, "viewer": true, "storage": true }`. Each defaults to `false`.
`allowAnonymousWrites`	Let anonymous viewers of a public artifact write shared data. Defaults to `false`.

Only the artifact’s creator can change visibility, capabilities, or allowAnonymousWrites when publishing a new version; editors can publish the rest.

It returns the artifact’s id, the new version, and its view URL.

Large files

Inline content and files are capped at 256 KB in total. Send anything larger as an upload, one file at a time. A file can be up to 25 MB, and one publish up to 100 MB.

Reserve the upload: call create_upload with the file’s path in the artifact, its exact size in bytes, and optionally its contentType (by default, it’s taken from the extension). Pass artifactId to add to an existing artifact you can edit; leave it out to reserve a new artifact id. It returns uploadId, artifactId, a signed url, and expiresAt, 1 hour from now.
Send the bytes: a raw PUT of the file to url, with no auth header (the URL is signed) and a Content-Length equal to the declared size. Each upload takes one PUT; it answers 204 when it’s done.
```
curl -fsS -T report.pdf "$UPLOAD_URL"
```
Publish: call publish_artifact with id set to the returned artifactId, and the file in files under the same path as { "uploadId": "…" }. A new artifact also needs a title. Uploaded and inline files can be mixed in one publish.
```
{
  "id": "<artifactId>",
  "title": "Q3 report",
  "files": { "report.pdf": { "uploadId": "<uploadId>" } }
}
```

An upload is used once. One that’s never published is deleted by the daily cleanup once it’s older than 24 hours.

Search freshness

Search indexes each publish asynchronously, so a new version becomes searchable with search_artifacts within about 10 seconds of being published. Until then, search matches the previous version’s text. Only the first 64 KB of an artifact’s entry file is indexed; text past that isn’t searchable. To find something you just published, use get_artifact or list_artifacts.

Reading

get_artifact: metadata plus the content of a version, the latest by default.
list_artifacts: filter by owner, format, visibility, agent, or updated-since. Paginated.
search_artifacts: full-text search over title, description, and extracted text. A PDF is searchable by its text once it has been viewed in the dashboard; before that, only by title and description.

Versions

list_versions: the history, with the agent and change note for each version.
restore_version: restores an earlier version by publishing it as a new one.

share_artifact: gives an email address viewer or editor access. The person doesn’t need to have signed in yet.
unshare_artifact: removes that access.
set_visibility: private, team, or public.

Only an artifact’s creator can share it, change its visibility, or delete it.

Deleting

delete_artifact moves an artifact to the trash. It can be recovered for 30 days, then it’s purged.

Live-page data

artifact_data_get, artifact_data_list, artifact_data_query, artifact_data_set, artifact_data_update, and artifact_data_delete read and write an artifact’s live-page data. It’s the same store the runtime API uses, so an agent can seed a tracker or read a poll’s results.

REST API

/api/v1/ mirrors these operations for the dashboard and for scripts, with the same tokens.

View as Markdown