Agents

Connect Claude Code, Codex or any MCP client to Agora, install the Agora skill, launch subagents and keep token usage low.

Agents talk to Agora through agora mcp, a stdio MCP server that wraps the HTTP API. It reads two environment variables:

With a cursor token the server knows who the agent is and which workspace it works in, so tools do not ask for a workspace argument.

Get a cursor token

Create a workspace and a cursor for your agent (see the quickstart):

WS=$(agora api POST /v1/workspaces '{"name":"main"}' | jq -r .id)
agora api POST /v1/cursors "{\"name\":\"claude\",\"workspace\":\"$WS\"}" | jq -r .token

Claude Code

claude mcp add agora -e AGORA_TOKEN=<cursor token> -- agora mcp

Codex

codex mcp add agora --env AGORA_TOKEN=<cursor token> -- agora mcp

Any MCP client

{
  "mcpServers": {
    "agora": {
      "command": "agora",
      "args": ["mcp"],
      "env": { "AGORA_TOKEN": "<cursor token>" }
    }
  }
}

If the client runs on another machine, run agora mcp there too and point AGORA_URL at an authenticated tunnel to the daemon.

The Agora skill

The skill teaches agents how to work with Agora: snapshot first, act by ref, use the observation that comes back, spawn and wait for subagents, and ask for a human on CAPTCHAs.

bunx skills add olimpiacloud/agora-skills

Launching subagents

An agent with the spawn permission can create children with cursor_spawn. With launch, Agora starts the agent process with its own scoped token and the MCP server already configured:

{
  "name": "pricing-check",
  "goal": "Open https://example.com/pricing and return the plans as JSON",
  "permissions": ["browser"],
  "launch": { "adapter": "claude", "model": "claude-haiku-5-5", "effort": "low" }
}

Then wait for the results instead of polling:

{ "ids": ["cur_..."], "timeout_ms": 600000 }

cursor_wait returns each child with its status, result and, for Claude Code, its usage (tokens, turns, cost and duration). Children can run in parallel in the same workspace: each opens its own window and gets its own input seat.

launch options:

Token efficiency

Agora is designed so agents spend tokens on the task, not on the plumbing. In our benchmark of three browser tasks, the lean launcher brought the cost of six runs from $2.01 to $0.23 with the same 6/6 correct answers, and each subagent’s initial context from 66,700 to 7,500 tokens. See benchmarks.

What helps:

• Act, then read the observation. browser_open, browser_navigate, browser_click, browser_fill, browser_press, browser_select and browser_scroll return what is visible afterwards, and only what changed since the last view of that tab. Do not call browser_snapshot after them unless you need offscreen content.
• Refs over coordinates, snapshots over screenshots. A snapshot takes about 1 ms and a few hundred tokens. Use browser_screenshot only when appearance matters; it defaults to 1024 px JPEG at quality 60.
• One audit instead of many screenshots. browser_audit checks overflow, contrast, tap targets, labels, headings, SEO tags, Core Web Vitals, animations and broken links in one call.
• Wait for events. events_wait and cursor_wait block until something happens; never poll in a loop.
• Lean subagents. The default lean profile runs Claude Code with --strict-mcp-config, no slash commands, no built-in tools, no settings files and a short system prompt, and exposes only the tool groups the cursor needs (AGORA_TOOLS) with one-line descriptions (AGORA_LEAN=1). Tool definitions shrink from about 5.7k to 2.9k tokens.
• Small models for small jobs. Reading a page or filling a form rarely needs the largest model; pass model and effort: "low".
• Coordinate through the board. Parallel subagents board_read before starting and board_post a claim, so two of them never do the same work.
• Batch independent calls in the same turn.

You can apply the same filters to your own MCP setup:

claude mcp add agora -e AGORA_TOKEN=<cursor token> -e AGORA_TOOLS=browser,spawn -e AGORA_LEAN=1 -- agora mcp