MCP Server - Asteroid Agents

The Asteroid MCP server lets you manage agents, inspect executions, and update workflows directly from AI-powered coding tools like Claude Code and Cursor. Instead of switching between your editor and the Asteroid platform UI, you can ask your assistant to do it in natural language.

Quick Start

Set up the MCP server in Claude Code or Cursor.
Complete sign-in when your client prompts you (first tool use).
Ask your assistant to call getContext, then agentList for your organization.
Use workflowGet on a version ID from workflowsList to read the graph; workflowCreate and workflowPublish to ship changes.
Run agentExecutePost to test, and executionGet / executionActivitiesGet to debug.

To create an agent from scratch instead of editing an existing one, see Build an agent over MCP. See the Setup guide for detailed installation instructions.

What is MCP?

The Model Context Protocol (MCP) is an open standard that connects AI assistants to external tools and data sources. When you add the Asteroid MCP server to your editor, your assistant gains access to Asteroid’s API — it can start executions, read results, update workflows, and more.

What You Can Do

Inspect Executions

View execution status, results, and activity logs without leaving your editor.

Manage Workflows

Fetch, modify, and publish agent workflow versions through natural language commands.

Start Executions

Kick off agent runs with custom inputs directly from your terminal.

Debug Failures

Investigate failed executions by examining outcomes, reasoning, and activity traces.

Available Tools

Tool names below are the identifiers MCP clients expose to the model when connected to https://mcp.asteroid.ai/mcp.

Context and docs

Tool	Description
`getContext`	Your user context, including organization IDs and names. Call this first when you need an organization UUID.
`availableToolsList`	Tool metadata catalog for integrations and execution activity names. Agent node permissions are configured with `properties.capabilities`.
`searchDocs`	Search Asteroid documentation for guides, node types, and best practices.

Agents and profiles

Tool	Description
`agentList`	List agents for an organization (use `organizationId` from `getContext`).
`agentCreate`	Create an agent with an initial workflow graph. The first version is published immediately — see Build an agent over MCP.
`agentRename`	Rename an agent. The name must be 1-100 characters.
`agentDelete`	Permanently delete an agent and its workflows. Only allowed when all executions are terminal.
`agentProfilesList`	List browser profiles (proxy, captcha, credentials, persistence) for an org.
`agentProfilesCreate`	Create a profile.
`agentProfileGet`	Fetch one profile by ID.
`agentProfileUpdate`	Update profile settings.
`agentProfileDelete`	Delete a profile.
`agentProfileClearBrowserCache`	Clear persisted browser state for a profile.

Executions

Tool	Description
`agentExecutePost`	Start an execution for an agent (uses the published workflow by default).
`executionsList`	List executions with filters and pagination.
`executionGet`	Full detail for one execution.
`executionView`	Show an execution in an interactive in-chat viewer (status, activity, result) on clients that support MCP Apps.
`executionActivitiesGet`	Activity log (tool calls, messages, events).
`executionAgentFilesGet`	All files for an execution, grouped by directory.
`executionContextFilesGet`	Files attached to an execution context.
`executionStatusUpdate`	Pause, resume, or cancel an execution.
`executionUserMessagesAdd`	Send a user message into an execution.

Workflows (agent versions)

Tool	Description
`workflowsList`	List workflow versions for an agent.
`workflowGet`	Load a full version (graph, rules, settings).
`workflowCreate`	Create a new version; set `parentId` for lineage. Unpublished until `workflowPublish`.
`workflowPublish`	Publish a version so it becomes the default for new runs.
`workflowExecute`	Run a specific version (including unpublished), useful for testing.

Files and validation

Agent files belong to a workflow version rather than to the agent as a whole, so different versions can carry different files. Every write below derives a new version and returns its id as workflowId — publish or execute that version for the change to take effect.

Tool	Description
`workflowAgentFilesList`	List the agent files attached to a workflow version.
`workflowAgentFilesUpload`	Add a file, passing its content as `contentText` or `contentBase64`.
`workflowAgentFilesReplace`	Replace the contents of one file.
`workflowAgentFilesRename`	Rename or move a file to a new node-relative path.
`workflowAgentFileSignedUrl`	Short-lived signed URL for reading a file’s contents.
`workflowAgentFilesDelete`	Remove one file.
`workflowAgentFilesDeleteMany`	Remove several files in a single new version.
`schemaValidate`	Validate JSON schema for structured output requirements.
`workflowSpecValidate`	Check the `workflow` you are about to pass to `agentCreate`, without creating anything. Returns every issue with a severity and a field path.
`workflowValidate`	The same check against an existing agent, for use before `workflowCreate`.

Execution context files and staged temp files take multipart bodies that tools/list cannot represent, so those uploads are not available over MCP — use the TypeScript or Python SDK instead.

Build an agent over MCP

The full loop is: agentCreate → agentExecutePost → poll executionGet → executionActivitiesGet to debug. agentCreate publishes the initial workflow as version 1, so no workflowPublish call is needed before the first execution — publishing only comes in when you create later versions with workflowCreate.

Worked example: `agentCreate`

A minimal runnable agent is four nodes: a start node, one iris (agent) node, and two output nodes for the success and failure ends. Generate a fresh UUID for every node and transition.

{
  "organizationId": "<organization UUID from getContext>",
  "name": "Product Price Checker",
  "workflow": {
    "rules": "",
    "settings": {
      "viewport_width": 1440,
      "viewport_height": 900,
      "max_timeout_mins": 15,
      "new_agent_loop": true
    },
    "graph": {
      "nodes": [
        {
          "id": "0b8e4b1e-0000-4000-8000-000000000001",
          "name": "Start",
          "type": "start",
          "properties": { "type": "start" }
        },
        {
          "id": "0b8e4b1e-0000-4000-8000-000000000002",
          "name": "Check Price",
          "type": "iris",
          "properties": {
            "type": "iris",
            "instructions": "Go to {{.product_url}}. Find the current price and whether the product is in stock.",
            "model": "asteroid-balanced",
            "capabilities": {
              "browser_use": true,
              "computer_use": false,
              "ask_user_question": false
            }
          }
        },
        {
          "id": "0b8e4b1e-0000-4000-8000-000000000003",
          "name": "Success",
          "type": "output",
          "properties": {
            "type": "output",
            "outcomes": ["success"],
            "schema": {
              "type": "object",
              "properties": {
                "price": { "type": "number", "description": "Current price" },
                "in_stock": { "type": "boolean", "description": "Availability" }
              },
              "additionalProperties": false,
              "required": ["price", "in_stock"]
            }
          }
        },
        {
          "id": "0b8e4b1e-0000-4000-8000-000000000004",
          "name": "Failure",
          "type": "output",
          "properties": { "type": "output", "outcomes": ["failure"] }
        }
      ],
      "transitions": [
        {
          "id": "0b8e4b1e-0000-4000-8000-00000000000a",
          "from": "0b8e4b1e-0000-4000-8000-000000000001",
          "to": "0b8e4b1e-0000-4000-8000-000000000002",
          "type": "outcome_success",
          "require_confirmation": false,
          "properties": { "type": "outcome_success" }
        },
        {
          "id": "0b8e4b1e-0000-4000-8000-00000000000b",
          "from": "0b8e4b1e-0000-4000-8000-000000000002",
          "to": "0b8e4b1e-0000-4000-8000-000000000003",
          "type": "iris",
          "require_confirmation": false,
          "description": "Price and stock status were found.",
          "properties": { "type": "iris" }
        },
        {
          "id": "0b8e4b1e-0000-4000-8000-00000000000c",
          "from": "0b8e4b1e-0000-4000-8000-000000000002",
          "to": "0b8e4b1e-0000-4000-8000-000000000004",
          "type": "iris",
          "require_confirmation": false,
          "description": "The page failed to load or the product was not found.",
          "properties": { "type": "iris" }
        }
      ],
      "sticky_notes": []
    }
  }
}

Structural rules the API enforces:

The start node’s single outgoing transition must be type outcome_success, and must point at a non-output node.
Agent (iris) nodes route with iris or selector transitions — never outcome_success — and every agent node needs a failure path to an output node.
The final result shape goes in the output node’s schema; a schema on a transition instead defines the data handed to the next node. See Output Node.

These rules correlate a transition with the node it leaves, so no JSON schema can express them and the generated types will not catch them — validation is the only place they surface. Before creating the agent, check any output schema with schemaValidate and the spec itself with workflowSpecValidate. Pass it the same workflow you are about to send: it runs the validator agentCreate runs, so what passes there is accepted here, and it returns every issue at once rather than one per round trip. Each issue carries a severity (error blocks creation, warning is advisory) and a path to the offending field. For a new version of an agent that already exists, workflowValidate is the same check against that agent.

Execute and poll

Start a run with agentExecutePost (pass agentId and any inputs your instructions reference), then poll executionGet until status is terminal (completed, failed, cancelled). Simple single-node executions typically finish in about 30-60 seconds; multi-node workflows take several minutes. Poll every 5-10 seconds — see Execution Statuses. On failure, read executionActivitiesGet for the step-by-step activity log.

The MCP server authenticates with OAuth (browser sign-in to your Asteroid account). Your client receives a bearer token valid for the API; permissions match the platform and REST API for your user. For HTTP access to Asteroid without MCP, use an API key and the API tab — that is separate from MCP auth.

​Quick Start

​What is MCP?

​What You Can Do

Inspect Executions

Manage Workflows

Start Executions

Debug Failures

​Available Tools

​Context and docs

​Agents and profiles

​Executions

​Workflows (agent versions)

​Files and validation

​Build an agent over MCP

​Worked example: agentCreate

​Execute and poll

Quick Start

What is MCP?

What You Can Do

Available Tools

Context and docs

Agents and profiles

Executions

Workflows (agent versions)

Files and validation

Build an agent over MCP

Worked example: `agentCreate`

Execute and poll