Skip to main content
Your coding agent can build Asteroid workflows, run them, and read the results. Two paths lead there: the Asteroid MCP server, or the TypeScript and Python SDK.
Give your coding agent https://docs.asteroid.ai/skill.md and it can do most of the integration on its own. To install the docs as a skill in tooling that supports it:

Which path

Connect the MCP server

The MCP server signs you in through the browser. It does not take an API key.
1

Add the server

Run this in your terminal:
2

Sign in

Complete the browser sign-in the first time Claude Code calls an Asteroid tool. The client stores the token and sends it on later requests.
3

Check it works

Ask Claude Code:
Your workflows come back in the reply.
The server speaks streamable HTTP at /mcp. It publishes OAuth metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, so clients that discover authentication find it on their own.

When it does not connect

What the MCP server can do

Context and docs

Workflows and profiles

Executions

Executions and statuses lists the statuses these tools return. Debug your workflows covers how to read a failure.

Versions

Files and validation

Workflow files belong to a version, not to the workflow, so different versions can carry different files. Every write below produces a new version and returns its id as workflowId. Publish or run that version to use the change. See Workflow filesystem for where the files land at run time.

Build a workflow over MCP

The loop is agentCreate, then agentExecutePost, then poll executionGet, then executionActivitiesGet when something goes wrong. agentCreate publishes the first graph as version 1, so the first execution needs no publish step. Publishing starts to matter once you make later versions with workflowCreate.

A minimal workflow

Four nodes make a runnable workflow: a start node, one agent node, and two output nodes for the two endings. Generate a fresh UUID for every node and every transition. An agent node carries "type": "iris" in the payload, and so does a transition the workflow chooses at run time.

Rules the API enforces

  • The start node has one outgoing transition. Its type is outcome_success, and it points at a node that is not an output node.
  • An agent node routes with iris or selector transitions, never with outcome_success.
  • Every agent node needs a path to an output node for the failure case.
  • The shape of the final result goes in the output node’s schema. A schema on a transition is a different thing: it defines the data handed to the next node. See Inputs and outputs.
These rules tie a transition to the node it leaves, so no JSON schema can express them. Validation is the only place they surface.

Validate before you create

Check the output schema with schemaValidate, and the graph with workflowSpecValidate. Pass workflowSpecValidate the same workflow you are about to send. It runs the check agentCreate runs, and returns every issue at once instead of one per round trip. Each issue carries a severity and a path to the field at fault. An error blocks creation. A warning is advice. For a workflow that already exists, workflowValidate is the same check.

Run it and read the result

Start the run with agentExecutePost. Pass the agentId and any inputs the instructions reference. Then poll executionGet every 5 to 10 seconds until the status is completed, failed, or cancelled. A single-node execution usually finishes in 30 to 60 seconds. A larger graph takes minutes. When an execution ends badly, read executionActivitiesGet for the step-by-step timeline.
Poll until the status is terminal. Do not loop while the status equals running — that exits the moment the workflow pauses to ask you something. Handle paused_by_agent and awaiting_confirmation yourself. See Executions and statuses.

Point your coding agent at the docs

Two URLs teach a coding agent how Asteroid works. Hand your coding agent skill.md and it can do most of the work on its own. Add llms.txt when it needs to find a page it has not seen.

Build with the SDK instead

The SDK holds an API key and runs anywhere — your laptop, your server, your CI job. Get a key from platform.asteroid.ai/keys, and set up the client with SDK setup. The loop is create, validate, publish, execute. agentCreate publishes its first version, so a fresh workflow runs immediately. Later versions start unpublished. Publish one, or run it directly with agentWorkflowsExecute to test it first.
Two details save you a debugging session:
  • agentExecutePost names its variables inputs. agentWorkflowsExecute names them inputVariables.
  • JSON and the TypeScript SDK use camelCase. The Python SDK exposes the same fields as snake_case attributes, so executionResult reads as execution.execution_result.

Next

Write good instructions

The craft inside each node

Test, iterate, publish

Get a draft ready, then make it live

Call a workflow from your code

Execute, poll, and read the result

TypeScript SDK

Client setup and the common functions