> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/mcp/setup) 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](/mcp/setup) for detailed installation instructions.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io/) (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

<CardGroup cols={2}>
  <Card title="Inspect Executions" icon="magnifying-glass" horizontal>
    View execution status, results, and activity logs without leaving your editor.
  </Card>

  <Card title="Manage Workflows" icon="diagram-project" horizontal>
    Fetch, modify, and publish agent workflow versions through natural language commands.
  </Card>

  <Card title="Start Executions" icon="play" horizontal>
    Kick off agent runs with custom inputs directly from your terminal.
  </Card>

  <Card title="Debug Failures" icon="bug" horizontal>
    Investigate failed executions by examining outcomes, reasoning, and activity traces.
  </Card>
</CardGroup>

## 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. |
| `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. |

<Info>
  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](/api-reference/overview) tab — that is separate from MCP auth.
</Info>