MCP Server

Connect your AI coding assistant to Asteroid via the Model Context Protocol

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

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

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.
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. Unpublished until workflowPublish.
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.
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

Tool	Description
agentSharedFilesGet	List persistent shared files for an agent.
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.

File uploads are not available over MCP — tools/list cannot represent binary file bodies. Use the TypeScript or Python SDK for uploads.

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.