Which path
Connect the MCP server
The MCP server signs you in through the browser. It does not take an API key.- Claude Code
- Cursor
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 asworkflowId. 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 isagentCreate, 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
irisorselectortransitions, never withoutcome_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. Aschemaon a transition is a different thing: it defines the data handed to the next node. See Inputs and outputs.
Validate before you create
Check the output schema withschemaValidate, 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 withagentExecutePost. 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.
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.
agentExecutePostnames its variablesinputs.agentWorkflowsExecutenames theminputVariables.- JSON and the TypeScript SDK use camelCase. The Python SDK exposes the same fields as snake_case attributes,
so
executionResultreads asexecution.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

