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

# Setup

> Add the Asteroid MCP server to Claude Code or Cursor

Connect your AI coding assistant to Asteroid in under a minute. The same MCP server works with any editor that supports the Model Context Protocol over HTTP.

## Prerequisites

* An **Asteroid account** you can sign into at [platform.asteroid.ai](https://platform.asteroid.ai)
* **Claude Code** or **Cursor** (or another MCP client that supports streamable HTTP and OAuth discovery)

REST integrations use [API keys](https://platform.asteroid.ai/keys) with the HTTP API. The hosted MCP server uses **OAuth** instead — your editor runs the sign-in flow and stores the session; you do not paste an API key into the MCP `Authorization` header.

## Claude Code

<Steps>
  <Step title="Add the MCP server">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http asteroid https://mcp.asteroid.ai/mcp
    ```

    This registers the Asteroid MCP server with Claude Code.
  </Step>

  <Step title="Authenticate">
    The first time Claude Code uses an Asteroid tool, complete the **browser sign-in** when prompted. The client exchanges the OAuth code for a token and sends it on subsequent requests.
  </Step>

  <Step title="Verify the connection">
    Ask Claude Code to list your agents:

    ```
    "List all my Asteroid agents"
    ```

    If the connection is working, you'll see your agents listed in the response.
  </Step>
</Steps>

## Cursor

<Steps>
  <Step title="Add the MCP server config">
    Add the following to your `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "asteroid": {
          "url": "https://mcp.asteroid.ai/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Authenticate">
    On first use, accept the OAuth flow so Cursor can obtain a token for your Asteroid user.
  </Step>

  <Step title="Verify the connection">
    In Cursor's AI chat, ask:

    ```
    "List all my Asteroid agents"
    ```
  </Step>
</Steps>

<Info>
  The server speaks **streamable HTTP** (`/mcp`) and exposes OAuth metadata at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server` for clients that auto-discover authentication.
</Info>

## Usage Examples

Once connected, you can interact with Asteroid using natural language. Tool names your client sees match the [overview](/mcp/overview) (for example `agentList`, `executionGet`, `workflowPublish`).

### Inspecting executions

```
"What happened in execution abc123-def4-..."
"Show me the last 10 executions for my scraping agent"
"Why did execution abc123 fail?"
"List all failed executions from today"
```

### Managing workflows

```
"Fetch the current workflow for agent abc123-..."
"Add a new input called 'language' to the agent workflow"
"Update the output schema to include a 'confidence' field"
"Publish the new workflow version"
```

### Starting executions

```
"Run agent abc123 with url=https://example.com and name=Test"
```

### Debugging

```
"Show me the activity log for execution abc123"
"What tool calls did the agent make in execution abc123?"
"What was the agent's reasoning for the outcome?"
```

## Troubleshooting

| Problem                      | Solution                                                                                                                                                 |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Tool not found" errors      | Verify the MCP server is registered — run `claude mcp list` (Claude Code) or check `.cursor/mcp.json` (Cursor)                                           |
| Authentication or 401 errors | Complete OAuth again: remove the server from the client, re-add it, and sign in when prompted. Ensure your Asteroid user has access to the organization. |
| Timeout errors               | The MCP server calls the Asteroid API — ensure you have internet access and no firewall blocking `mcp.asteroid.ai`                                       |

<Note>
  Need help? Visit our [Support](/support-security/support) page or reach out on GitHub.
</Note>