Ara MCP | Ara Documentation

Ara MCP is the typed control plane for coding agents. External agents and Ara’s Brain use the same JSON-RPC endpoint, schemas, handlers, authorization checks, and audit trail. They differ only in authentication and the scoped view they receive.

https://api.ara.so/mcp/ara

Connect a client

The quickest path is through Ara CLI, which configures supported clients and starts their OAuth flow:

$ ara mcp setup
$ ara mcp status

Agent app	What it receives
Plugin-capable app	The Ara plugin: remote MCP connection plus the shared Ara operating skill
MCP-capable app	The remote MCP connection; complete OAuth from that app’s MCP settings

Setup also installs the shared skill at ~/.agents/skills/ara/SKILL.md.

If Ara was connected before full public workspace grants shipped, run ara mcp setup --clients <client> --reauthorize once. Restart the client if it does not discover the newly installed plugin in the current chat.

One server, scoped views

External agents authenticate with a scoped ara_ API key or MCP OAuth grant. Ara’s Brain authenticates with a short-lived token bound to its run, model, worker lease, and execution generation. Every principal is bound to one workspace and sees only tools its scopes permit.

Both principal classes execute a control tool the same way:

POST /mcp/ara
tools/call -> canonical ara_* handler -> authorization + audit

The canonical catalog is:

Family	Tools
Automations	`ara_automation_list`, `ara_automation_get`, `ara_automation_create`, `ara_automation_update`, `ara_automation_delete`
Sessions	`ara_session_search`, `ara_session_get`, `ara_session_create`, `ara_session_send`, `ara_session_events`, `ara_session_cancel`
Plugins	`ara_plugin_list`, `ara_plugin_get`, `ara_plugin_connect`, `ara_plugin_update`, `ara_plugin_disconnect`, `ara_plugin_tools`, `ara_plugin_call`
Skills	`ara_skill_list`, `ara_skill_search`, `ara_skill_get`, `ara_skill_create`, `ara_skill_update`, `ara_skill_delete`
Memory	`ara_memory_list`, `ara_memory_get`, `ara_memory_search`, `ara_memory_set`, `ara_memory_delete`
Secrets	`ara_secret_list`, `ara_secret_set`, `ara_secret_delete`
Runbooks	`ara_runbook_get`, `ara_runbook_update`
Repositories	`ara_repository_list`, `ara_repository_get`, `ara_repository_connect`, `ara_repository_disconnect`
Issues	`ara_issue_get`, `ara_issue_search`, `ara_issue_create`, `ara_issue_comment`
Pull and merge requests	`ara_pr_get`, `ara_pr_feedback_get`, `ara_pr_open`, `ara_pr_update`
Devices	`ara_device_list`, `ara_device_status`, `ara_device_connect`, `ara_device_disconnect`

Some families are external-only or live-run-only. A name appearing above does not override scope or principal restrictions.

Repository-scoped secrets

Secret operations require both repo and provider. Ara stores their identity against the stable repository connection plus the secret name. Values are write-only: listing returns names and metadata, never plaintext.

Repository runbooks

.ara/runbook.md is the source of truth for repository setup, development, testing, and verification commands. ara_runbook_get reads that exact file. ara_runbook_update creates a branch, changes that file, and opens a pull or merge request. There is no separate database runbook.

Inside an Ara cloud run

The Brain derives typed schemas locally from the same canonical registry, so it does not block the first answer on a tools/list network call. Actual executions still go through /mcp/ara. Mutations use a run-bound invocation ledger so a worker loss cannot silently execute the same action twice.

Before Hands is ready, the model receives its scoped ara_* tools plus update_plan and spawn_subagents. When an enrolled, authorized device becomes ready, exactly two physical tools are added:

bash
repl

Disconnecting the selected device removes both immediately. Files, Git, tests, processes, browser work, and scripts all run through those two physical tools. The eleven legacy local_* relay operations are internal protocol details and are never advertised to the model or external MCP clients.

The run credential stays in the Brain and never enters Hands. Device credentials also never enter model context. Repository checkout and fetch happen as part of the authorized Hands attachment.

Run grants are bound to the live worker lease and current execution generation, narrowed again against the active run on every request, and provide neither ara_api_request nor a reusable public API bearer. Provider descriptions and results are untrusted data; resolved credentials are applied only inside Ara, redacted from results, and never sent into the execution environment.

When a typed Ara control exists, the Brain uses it instead of shelling out to curl api.ara.so, gh, or ara call. bash and repl are reserved for actual workspace execution.

Legacy action-based tool names remain accepted as hidden compatibility aliases. They are not returned by tools/list, and audit events record the canonical name. Improvements to shared descriptors and handlers therefore reach external agents and Ara’s Brain together whenever their scopes permit them.