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

<Note>
  File uploads are not available over MCP — `tools/list` cannot represent binary file bodies. Use the [TypeScript](/sdks/typescript) or [Python](/sdks/python) SDK for uploads.
</Note>

<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>