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
• Claude Code or Cursor (or another MCP client that supports streamable HTTP and OAuth discovery)

REST integrations use API 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

1. Add the MCP server

   Run this command in your terminal:

   claude mcp add --transport http asteroid https://mcp.asteroid.ai/mcp
   

   This registers the Asteroid MCP server with Claude Code.

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

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

Cursor

1. Add the MCP server config

   Add the following to your .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

   {
     "mcpServers": {
       "asteroid": {
         "url": "https://mcp.asteroid.ai/mcp"
       }
     }
   }
   
2. Authenticate

   On first use, accept the OAuth flow so Cursor can obtain a token for your Asteroid user.

3. Verify the connection

   In Cursor’s AI chat, ask:

   "List all my Asteroid agents"
   

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.

Usage Examples

Once connected, you can interact with Asteroid using natural language. Tool names your client sees match the 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

Need help? Visit our Support page or reach out on GitHub.