Skip to content

Drive agents from Claude Code or Cursor#

The console is also an MCP server, at https://console.astralyx.cloud/mcp. From Claude Code, Cursor or any MCP client you can list your agents, start runs, wait for their answers and read what they reached — as yourself, with your role in each workspace, exactly as in the console.

Before you begin#

  • A personal API token: Account & tokens, shown once (see API tokens and automation).
  • Starting runs needs the editor or admin role in the workspace.

Add the server#

$ claude mcp add --transport http astralyx https://console.astralyx.cloud/mcp \
    --header "Authorization: Bearer ast_pat_…"

In ~/.cursor/mcp.json, or a project's .cursor/mcp.json:

mcp.json
{
  "mcpServers": {
    "astralyx": {
      "url": "https://console.astralyx.cloud/mcp",
      "headers": { "Authorization": "Bearer ast_pat_…" }
    }
  }
}

GET $ASTRA_URL/api/v1/mcp (signed in) describes the server: its URL, protocol version, how to authenticate, its rate limit and its tools.

Then ask your assistant, for instance: "Run the researcher agent in acme/research on 'What changed in Rust 1.90?' and show me its answer."

The tools#

Tool Arguments What it does
list_workspaces — Your workspaces (<org>/<workspace>), your role, their clusters.
list_agents workspace The agents there, with their current and newest version.
run_agent workspace, agent, input, version? Starts a run; answers with its name at once. Editors and admins.
get_run workspace, agent, run, wait_seconds? (≤ 60), output_bytes? (≤ 16 384, default 8 192) State and reason, the end of its output, and its trace in numbers: model calls, tokens, tool calls, refused calls. Waits for the run to end when asked.
list_runs workspace, agent, limit? (≤ 100, default 10) The latest runs.
get_run_activity workspace, run, limit? (≤ 200, default 50), decision?, source? What the run reached outside its sandbox — each URL, connection, lookup, tool and model call, allowed or denied — with a summary.

When a workspace is on several clusters, the tools also take cluster. decision is allowed, denied, removed or requires_approval; source is sandbox, firewall, dns, gateway, model or provider.

Limits and security#

  • Each token may make 30 requests a minute (bursts of 30).
  • Only Authorization: Bearer with a personal API token or a CLI session is accepted — never a browser's cookie, so a page elsewhere cannot use your session.
  • Every call goes through the same path as the console: the cluster checks it again, in the workspace, as you. Revoking the token ends its access at once.
  • Results are bounded (24 KiB of text) to spare the assistant's context.