Surfaces with MCP

Create, update, preview, and release surfaces from your coding agent through Traces MCP.

Traces MCP lets your coding agent do everything the web app can do with a surface: create it, upload new versions, share a preview, make a version current, change who can use it, and archive it. This is the easiest way to iterate on a surface, because the agent writing the HTML can also publish it.

Before you start

Connect Traces MCP and approve the surfaces:write access it requests.
Pick the namespace during authorization. Each MCP connection is bound to one namespace, and every surface tool works inside it. To manage surfaces in a different namespace, reconnect and choose that namespace.
Make sure your agent can run shell commands. Surface HTML is never passed through an MCP tool argument; the agent uploads the file with curl instead.

MCP uses the same permissions as the web app: the surface's creator and namespace admins and owners can update it, and only admins and owners can make it public. See who can do what.

Surface tools

Surface operations aren't listed as top-level tools. The agent finds them with traces_search_tools (for example, a search for surface) and runs them with traces_execute_tool.

Tool	Purpose
`surface_build_instructions`	Top-level tool. Returns the full surface-building guide.
`traces_surfaces_search`	List the namespace's surfaces, including private, archived, and unapproved ones. Use it to find a surface's key.
`traces_surfaces_get`	Get a surface's full record: details, current version, visibility, and version history.
`traces_surfaces_create`	Create a new private surface with no versions.
`traces_surfaces_prepare_upload`	Step 1 of an upload. Reserves a new version and returns a single-use upload URL. Creates the surface too if the key is new and a `name` is given.
`traces_surfaces_complete_upload`	Step 2 of an upload. Finalizes the uploaded file as an immutable version and returns a `previewUrl`. Pass `release: true` to make it current in the same step.
`traces_surfaces_release_version`	Make an uploaded version current, and optionally set `visibility` to `private` or `public`.
`traces_surfaces_update`	Change the surface's name, description, or icon.
`traces_surfaces_archive` / `traces_surfaces_restore`	Archive a surface, or bring an archived one back.

Publish a new surface

Ask your agent to build one, for example:

Read https://traces.com/surfaces.md and build a surface that lists every failed shell command in a trace. Publish it to Traces as failed-commands.

The agent then:

Writes the HTML file locally.
Calls traces_surfaces_prepare_upload with the key, a name, the version (for example 1.0.0), and the file's exact byteSize. Because the key is new, this creates the surface.
Uploads the raw file to the returned URL:
```
curl -fsS -X POST -H 'Content-Type: text/html' --data-binary @surface.html "<upload-url>"
```
The response contains an artifactId. The upload URL expires quickly and works only once.
Calls traces_surfaces_complete_upload with the version and artifactId, and shares the returned previewUrl with you.
Once you're happy with the preview, calls traces_surfaces_release_version to make it current.

New surfaces are private. To list it in the marketplace, ask the agent to release it with visibility: "public", or switch it to Everyone from the surface's page.

Update an existing surface

To change a surface's HTML, ask your agent to publish a new version:

Update the failed-commands surface so it groups failures by command. Upload it as a new version and send me the preview link.

The agent looks up the surface with traces_surfaces_get (or traces_surfaces_search if it doesn't know the key), then repeats the upload steps with a new version label, such as 1.1.0. Version labels must be new: every version is immutable and can't be overwritten.

Uploading a version doesn't change what anyone sees. traces_surfaces_complete_upload leaves the current version in place unless the agent passes release: true.

Preview before releasing

traces_surfaces_complete_upload returns a previewUrl that opens the new version on the latest trace in the namespace:

https://traces.com/s/<trace-id>?surface=<key>&version=<version>

Only members of the namespace can open a version that isn't current. If the namespace has no traces yet, share one with the Traces CLI first so there's real data to try it on.

Release or roll back

Ask the agent to make a version current:

Release version 1.1.0 of failed-commands.

The agent calls traces_surfaces_release_version. Leaving out visibility keeps the surface's current visibility; it never makes a surface public on its own. To roll back, release an earlier version the same way.

Change details or visibility

Name, description, or icon: traces_surfaces_update. The key can't be changed.
Public or private: traces_surfaces_release_version with visibility, passing the current version to keep it.

Rename failed-commands to "Failed Commands" and update its description to "Every non-zero exit, grouped by command."

Archive or restore a surface

Archive the failed-commands surface.

traces_surfaces_archive removes the surface from menus and the marketplace while keeping all of its versions. traces_surfaces_restore brings it back without changing its current version or visibility.

Surfaces with MCP

On this page