Ara MCP | Ara Documentation

Ara MCP is how a coding agent operates your Ara workspace: connecting repositories, managing environments and secrets, starting sessions, and reading them back. It is a remote Model Context Protocol connection, so the agent talks to Ara directly rather than shelling out to a CLI.

The direct Streamable HTTP endpoint is:

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

Connect a client

The quickest path is through Ara CLI, which configures every supported client it detects and starts each one’s 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.

What the connection can reach

Each grant is bound to one workspace and covers that workspace’s complete public Ara API. It does not include operator authority, private web-app routes, another workspace, or runtime-only device tools. The CLI and every client keep separate, individually revocable grants.

Typed tools cover the common operations:

Tool	Covers
`ara_repository_manage`	Connect, index, and configure repositories
`ara_environment_manage`	Environments and repo runbooks
`ara_secret_manage`	Write-only secrets, scoped `repo` or `user`
`ara_mcp_server_manage`	Third-party MCP servers, including a `test` action
`ara_skill_manage`	Skills
`ara_automation_manage`	Automations and their triggers
`ara_session_create` · `ara_sessions` · `ara_session_interact`	Start, list, and drive coding sessions
`ara_session_events` · `ara_session_search`	Read sessions back
`ara_memory_manage` · `ara_team_manage`	Memory and teammates
`ara_plugin_list` · `ara_plugin_tools`	Installed plugins and remote HTTP tool discovery
`ara_plugin_call`	Run-only execution of one connected remote HTTP plugin tool

Use ara_api_request when an approved public /v3 operation has no typed tool.

How secrets behave

Secret values are write-only. Reading a server back returns a placeholder and secret_names, never the value you supplied. For bearer or API-key MCP servers, put credentials in the write-only secrets map and reference them from headers or env as $SECRET_NAME.

Connecting an OAuth-backed third-party MCP server creates its Ara configuration, but the provider’s browser authorization must still be completed before an agent can use it.

For a fixed curated HTTP server, ara_mcp_server_manage with action: "test" resolves the write-only credentials and returns only a health verdict, the discovered tool count, and latency. Custom URLs, per-customer endpoints, SSE, and stdio servers are tested inside a fresh acceptance session rather than from Ara’s API servers.

Inside an Ara cloud run

For workspaces explicitly enabled during the staged rollout, Ara’s managed execution environment uses a small ara.* JavaScript client inside its persistent command environment. The friendly skill calls are:

1 await ara.skills.list()
2 await ara.skills.get(id)
3 await ara.plugins.list()
4 await ara.plugins.tools("context7", "resolve")
5 // Copy every required field from the discovered inputSchema exactly.
6 await ara.plugins.call("context7", "resolve-library-id", {
7   libraryName: "hono",
8   query: "Find the official Hono documentation.",
9 })
10 await ara.tools.list("skill")
11 await ara.tools.call("ara_skill_manage", { action: "get", skill_id: id })

Skills and plugins are logical capability namespaces within /mcp/ara, not separate transport routes such as /mcp/ara/skills or /mcp/ara/plugins.

Inside that enabled cloud run, the matching ara skills, ara plugins, ara tools, and ara call commands provide a fallback through the run’s Bash tool. These are run-local commands, not additions to the public Ara CLI installed on your computer. Both interfaces use the same client and call this page’s /mcp/ara endpoint; they do not add hundreds of individual MCP tool names to the runtime tool list.

The base cloud-run grant covers managed-skill reads plus the coding tools already allowed for that run. A separately allowlisted canary adds connected, Ara-curated Streamable HTTP plugin discovery and execution. It does not run custom endpoints, stdio processes, or legacy SSE transports in the API service. Read-only runs may discover plugin tools but cannot call them. Writable calls use a distinct short-lived plugins:execute authority and a durable invocation key derived from the plugin, tool, and stable arguments. Identical implicit calls in one run therefore share an identity. If Ara has already completed the call, or cannot prove its outcome after a transport failure, recovery refuses to dispatch that identity again. Once an effectful tools/call is sent, Ara never replays it automatically after a transport or HTTP-status failure; the outcome is treated as ambiguous. A caller must supply a deliberate new key to request a genuinely new provider operation.

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. External MCP clients continue to connect directly to /mcp/ara with their own public grant, but ara_plugin_call remains run-only during this canary.

Native sandbox MCP injections still apply to future runs. In an enabled unified-plugin canary, Ara resolves the connected curated HTTP server and fresh OAuth credential at call time, while preserving the agent’s configured plugin allowlist.