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, thenagentListfor your organization. - Use
workflowGeton a version ID fromworkflowsListto read the graph;workflowCreateandworkflowPublishto ship changes. - Run
agentExecutePostto test, andexecutionGet/executionActivitiesGetto debug.
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 tohttps://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. |
listAvailableTools | Capabilities that can be assigned to AI Task nodes in workflows. |
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). |
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. |
executionActivitiesGet | Activity log (tool calls, messages, events). |
executionContextFilesGet | Files attached to an execution context. |
executionContextFilesUpload | Upload files to a running execution. |
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. |
workflowSyncExecution | Point a running execution at a specific workflow version. |
Files and validation
| Tool | Description |
|---|---|
tempFilesStage | Stage a file before starting an execution. |
agentSharedFilesGet | List persistent shared files for an agent. |
agentSharedFilesUpload | Add shared files (available across executions). |
agentSharedFilesUpdate | Replace contents of one shared file. |
agentSharedFilesDelete | Remove one shared file. |
agentSharedFilesDeleteAll | Remove all shared files for an agent. |
agentSharedFilesFreeze | Freeze or unfreeze a shared file. |
schemaValidate | Validate JSON schema for structured output requirements. |
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.