Connect your first agent

Autonomy isn’t an agent — it’s an MCP server an agent connects to. The default path connects Claude Code, using a thin plugin Autonomy ships for exactly this purpose. This page wires that connection and confirms the agent can actually see Autonomy’s tools before you rely on it for anything. If you’d rather bring a different MCP client, the mechanism is the same; see Bring your own agent.

By the time you’re here, Install has put autonomy (a7y).app at /Applications, Grant permissions has authorized Accessibility and Screen Recording, and Run the doctor is green. This step doesn’t build anything new — it just points Claude Code at what’s already running.

Why Claude Code specifically, and why MCP

Autonomy used to spawn its own agent subprocess inside the app (nightgram). That’s retired — see MCP-native architecture for why. Today, Claude Code (or Codex, or any MCP client) connects to the Autonomy daemon as a regular MCP client and drives the conversation itself, with full access to Autonomy’s tools. Claude Code is simply the one Autonomy ships a ready-made plugin for.

What the plugin actually wires up

The Claude Code plugin at plugins/autonomy/.claude-plugin/ shares one .mcp.json with the Codex plugin. Its MCP server entry is:


{
  "mcpServers": {
    "autonomy": {
      "command": "/Applications/autonomy (a7y).app/Contents/Resources/bin/a7y-cli",
      "args": ["daemon", "proxy"]
    }
  }
}

a7y-cli daemon proxy is a stdio JSON-RPC bridge — it doesn’t start a second relay. It attaches to the single relay the app already owns (the one you started, without necessarily noticing, back when you opened the app in Install):


 Claude Code  --stdio JSON-RPC-->  a7y-cli daemon proxy  --attaches to-->  the app's one running relay
                                                                                    |
                                                                                    v
                                                                  a7y-ax / browser / speech backends

One runtime, one relay, no matter how many MCP clients attach to it — that’s a deliberate design point, not an implementation detail you need to manage.

Connect it

Add this repo as a Claude Code plugin marketplace

Since the repo isn’t public yet, add it from your local checkout rather than a GitHub shorthand:


/plugin marketplace add /path/to/your/autonomy/checkout
/plugin install autonomy@autonomy

Let Claude Code auto-discover the plugin

Claude Code auto-discovers the plugin’s .mcp.json and its skills/ directory — no further config to write by hand.

Confirm the connection


claude mcp list

Look for autonomy in the list. If it’s there, ask Claude directly to check Autonomy’s readiness — a connected agent can call tools like accessibility_state and doctor_check_permissions to get its own permission and readiness signals (a separate implementation from a7y-cli doctor, not a wrapper around it) and tell you, in its own words, whether it’s ready.

Once connected, the agent has on the order of 170 Autonomy tools available — screen reading and control, browser automation, the VoiceOver speech transport, consent and the action ledger, and more. That’s deliberately more than any single conversation should have loaded into context at once; see “Discovery instead of a firehose” for how Autonomy scopes that down per task, and the full MCP tool catalog for what’s actually in there.

Pitfalls

The plugin’s own install docs mention build-app.sh, not install-app.sh. build-app.sh alone builds the app in place under plugins/autonomy/ — it doesn’t install anything to /Applications. Since the shared .mcp.json above hardcodes /Applications/autonomy (a7y).app, make sure you’ve actually run install-app.sh (see Install) rather than build-app.sh alone, or Claude Code will have a plugin installed with nothing at the path its MCP config points to.
Don’t add a second, manual autonomy MCP server registration if the plugin-provided one is already active — you’d end up with two clients fighting over the same daemon identity for no benefit.
A tool being visible isn’t the same as an action being heard or seen. That distinction matters starting with the very next page.

If autonomy doesn’t show up in claude mcp list, see MCP tools not visible. Otherwise, continue to Your first screen-off task.