> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ara MCP

> The agent-facing MCP transport and typed workspace tools.

## August 14, 2026 — PR repair handoffs keep their review context

* The existing 6:07 AM Pacific production reliability sweep now builds a
  disposable, conflicting pull request and drives three real agent turns through
  it. The first opens the fixture through `ara_pr_open`; the read turn must page
  every file and feedback section and inspect a real
  failed Actions job with annotations, logs, and artifacts; the write turn must
  update metadata, act on discussion and inline review feedback, resolve and
  reopen its review thread, repair the conflict, refresh the snapshot, and
  merge only into a temporary base branch. The workflow archives the Sessions
  and deletes every temporary branch after retaining its evidence artifact.
  Opening and repair are certified from the exact MCP calls plus the resulting
  live GitHub state, so a successful canary does not depend on the agent repeating
  a particular completion phrase.
  Manual runs are admitted only from reviewed `main` before any inherited or
  Infisical secret is exposed. The fixture also forces feedback and thread-comment
  pagination beyond offset zero and verifies a real reviewer/assignee picker
  option without notifying or assigning a human.
* The Review page's conflict-repair action and the agent runtime now share one
  instruction contract. Before editing, the agent must page the complete PR,
  inspect checks and unresolved review threads, and read detailed failed-check
  diagnostics; after repairing the branch, it refreshes the PR and replies to or
  resolves addressed feedback.
* A deterministic acceptance fixture drives that exact action through the real
  agent loop with the six advertised PR tools. It also pins the continuation
  boundary that previously allowed a child run to start without its PR number,
  branch, and URL, which made its first `ara_pr_get` return `no_pr` even though
  the source Session had a PR.
* If the Session's original PR has closed but its pushed branch now belongs to
  one newer open PR, the execution preflight retargets the continuation to that
  PR before the agent starts. Ambiguous branches still fail closed. This keeps a
  long-lived Session's conflict/check repair action attached to the live review
  instead of silently discarding all PR context.
* New tool `ara_vendor_request` relays one HTTP request to a connected vendor
  that has no MCP server of its own — Resend, for transactional email, is the
  first. The vendor's credential is attached to the request server-side and
  never enters the run.

## August 13, 2026 — Agents can work the whole pull-request review

* The live-run PR surface is now six focused tools. `ara_pr_get` returns the
  complete Review-page snapshot: PR identity and state, merge requirements,
  commits, paged file patches, checks, reviews, inline comments and resolved
  thread state, discussion, picker options, visual evidence, supported actions,
  and any stored merge operation or blocker. Every independently fetched section
  says whether it is complete, unavailable, or unsupported, so an outage can no
  longer look like “there was no feedback.”
* `ara_pr_check_get` now identifies required checks, exposes workflow artifacts,
  and reads bounded GitHub Actions logs without the request headers that caused
  some log endpoints to return HTTP 415. The signed log download now requests
  only the bounded tail from blob storage. Agents can inspect the exact
  annotation, failed step, and log excerpt that CI produced before changing code.
* `ara_pr_feedback_update` is the one new tool. It posts PR comments, replies to
  inline review comments, toggles discussion reactions, and resolves or reopens
  GitHub review threads. `ara_pr_update` now covers the rest of the Review-page
  controls: title/body, draft or ready state, close, base branch, reviewers,
  assignees, and labels, with an optional expected-head guard against racing a
  newer push.
* The older `ara_pr_feedback_get` name remains callable for cached clients but is
  no longer advertised; it resolves to `ara_pr_get`. Agents therefore discover
  six PR tools, not seven.
* Large review threads expose a bounded first comment page plus explicit totals
  and next offsets. Agents can page every remaining comment through the same
  `ara_pr_get` tool by passing the thread id, so completeness no longer requires
  an unbounded MCP response.

## August 12, 2026 — A session picks a plugin, not an endpoint

* A session could previously create or update a workspace MCP server with any
  `url` and any `headers`. Both are where Ara sends that workspace's credentials,
  because a server's headers may reference workspace secrets by name and Ara
  resolves them before it connects. A session choosing them chose the
  destination of a credential.
* A session now names a plugin from the catalog and Ara fills in the endpoint. The
  `url` and `headers` a session sends are ignored rather than validated, and a
  plugin the catalog has no endpoint for is refused with
  `mcp_server_destination_requires_human`. That covers custom servers, plugins
  that run a local command, and providers that issue one endpoint per customer.
* One-click plugin connect is unchanged: it already named the plugin and took the
  endpoint from the catalog. Adding a custom server, or one whose endpoint only
  you know, is done in workspace settings as before.
* People and API keys are unaffected. This applies only to a session acting on its
  own, which is the principal that can be steered by content it reads.

## August 12, 2026 — Granola's tools now load

* Connecting Granola failed at tool discovery: it answers `tools/list` with a
  single-message JSON-RPC batch (`[{...}]`), and the gateway accepted only a bare
  object, so discovery ended in `bad_upstream_payload` and no tools appeared.
* A one-message batch for `tools/list` is now unwrapped and handled. Larger or
  otherwise unexpected batches are still rejected, so this widens compatibility
  with one real server shape rather than loosening the protocol generally.

## August 12, 2026 — Agents now propose runbook updates as they go

* A repo run is told that `.ara/runbook.md` is the single source of truth for
  setup, development, testing, and verification commands, and that
  `ara_runbook_update` is how to change it — but nothing asked the agent to
  actually check its own work against that file, and a private per-agent
  scratchpad sat right next to it as the lower-effort option.
* Before finishing, an agent is now asked directly: did this run rely on or
  discover a setup/build/run/test/verify fact not already in the runbook (a
  required boot command, flag, port, missing dependency, or setup step)? If
  so, call `ara_runbook_update` now, even when it is unrelated to the run's
  main task, so every future session on that repository starts from what was
  just learned instead of rediscovering it.
* The private scratchpad is unchanged and still exists for run-to-run
  handoffs on the same agent; it was never a substitute for the runbook since
  it is scoped to one agent record, not the repository.

## August 12, 2026 — Recycling a stuck cloud machine works

* `ara_machine_reset` returned `cloud_machine_reset_unavailable` for every call
  since it shipped, so an agent on an unusable machine had no way to recover it.
  Its live-session guard compared a session id against a mistyped parameter and
  the query could never execute. Rotation now succeeds and reports the machine
  generation it moved from and to.
* The guard itself is unchanged in intent: a reset is still refused while another
  session is running on that machine, still applies to cloud machines only, and
  still never touches a person's own computer.

## August 12, 2026 — An agent can see and recycle its cloud machine

* `ara_machine_list` reports the cloud machines a workspace's sessions run on,
  each machine's generation, how many sessions are still live on it, and how many
  repositories share it.
* `ara_machine_reset` rotates the current session's cloud machine so the NEXT run
  provisions a fresh one. Use it when a machine is unusable (out of disk, a wedged
  process, a corrupt checkout) and ordinary retries keep failing.
* Rotation is not a wipe: the previous machine's contents are not deleted, it is
  simply no longer selected and ages out normally. The current run is not repaired
  either, so start a new session to pick up the replacement.
* Refused while another session is still running on that machine, so recycling can
  never pull a workspace out from under a teammate's live run. Cloud machines only:
  a person's own computer is never reset by an agent.

## August 11, 2026 — Retry a session on a different model

* `ara_session_create` and `ara_session_send` now accept optional `model` and
  `reasoning_effort` parameters, so an agent watching one of its own sessions
  stall or fail can retry it on another model instead of only reporting the
  failure.
* Sending a `model` override to a live session always starts a new
  continuation run rather than mutating the one in progress: a run's model is
  fixed at its first execution, the same way a composer retry works today.
* Valid `model` ids are the closed Ara catalog (`openai/gpt-5.6-sol`,
  `openai/gpt-5.6-terra`, `openai/gpt-5.6-luna`, `anthropic/claude-sonnet-4.6`)
  or a connected organization `byok:` id; `reasoning_effort` is one of `low`,
  `medium`, `high`, or `xhigh`. Omitting either preserves today's behavior.

## August 11, 2026 — A shorter Connect Ara screen

* The MCP connect screen no longer shows the requesting app and its requested
  access as two boxed panels. The app name and a one-line access summary sit in
  the prose above the workspace picker instead.
* Nothing was dropped from what you consent to: the screen still names which app
  is asking and whether it receives full or only its requested access, and still
  states that stored secrets can be written or replaced but never read back.

## August 11, 2026 — The shared agent skill names the session tools

* The Ara skill that `ara mcp` installs for every coding agent now names the
  canonical session tools (`ara_session_create`, `ara_session_events`,
  `ara_session_send`, `ara_session_get`, `ara_session_search`,
  `ara_session_cancel`), so an agent reading it can run the whole loop instead
  of only the setup steps its description already promised.
* It also records that `ara_session_interact` is a deprecated alias of
  `ara_session_send`. The alias still dispatches for existing callers, and is
  still deliberately absent from the advertised tool list.

## August 7, 2026 — Organization memory on the capability plane

* Eligible cloud sessions can use org-wide durable memory through
  `ara.memory.list`,
  `ara.memory.read`, `ara.memory.write`, and `ara.memory.search`.
* Memory is organization-scoped markdown (L1 `USER.md` / `MEMORY.md`, semantic
  directories, and `episodic/YYYY-MM-DD.md`), not repository-scoped notes.
* Settings → Memory shows the file tree, editor, history, and Dream now controls.
* Available to every workspace by default. Operators retain
  `ORG_MEMORY_ENABLED` as an emergency global switch and may use
  `ORG_MEMORY_ORGS` as a temporary bounded override.

## August 2, 2026 — One-command agent setup

* `ara mcp` now configures every detected supported agent app, installs
  the shared Ara agent skill, and starts its native OAuth flow without an extra
  Ara confirmation prompt.
* `ara device` is the short, idempotent path for installing this Mac
  as a full-access background Ara Device.
* Ara agents can test authentication for fixed, curated HTTP MCP connections
  without receiving secret values or opening custom URLs from the API server.
* Ara MCP remains the direct tool surface for coding agents; Ara Device is the
  separate native worker. The direct Streamable HTTP endpoint is
  `https://api.ara.so/mcp/ara`.

## August 10, 2026 — Minimal standard CLI

* `ara mcp` is now the only MCP setup and status capability. Its first run
  configures every detected client; later runs report organization,
  installation paths, connections, and last use without changing ready clients.
* `ara status`, `ara whoami`, `ara help`, and `ara --version` provide the
  conventional discovery surfaces agents expect.

## August 4, 2026 — Runtime conformance

* The canonical exact-main check now runs the full four-case conformance corpus,
  including on a clean diff. This keeps the production baseline and changed-case
  checks aligned.
* Its dynamic outcome markers are sentence-shaped rather than token-shaped, so
  Ara's safety redaction does not hide the evaluator's own visible result.
* Case-derived nonce components are separated before interpolation as well,
  including the long failed-recovery case name.

## August 7, 2026: Custom MCP server connections pin the verified address

* Requests to a configured org MCP server (health checks, OAuth discovery and
  token exchange, gateway calls) now connect to the exact IP address the
  private-network guard verified, instead of resolving the server's hostname a
  second time at connect time. A DNS name that answers with a public address
  during validation can no longer swap to an internal or link-local address for
  the actual connection (DNS rebinding). TLS still validates the server's
  certificate against its hostname, so legitimate public MCP servers, including
  those behind CDNs that require SNI, are unaffected.
* Follow-up: the OAuth discovery, registration, and token-exchange steps of
  this flow are now exercised in tests through an injected transport, so the
  private-network guard above is always the real one under test. Internal test
  tooling only; the flow's outbound behavior is unchanged.
* Follow-up: the guard's DNS lookups are now cancelled the moment their caller
  gives up, instead of running to the OS timeout in the background. A custom
  MCP server whose nameserver stalls on purpose can no longer pile up pending
  lookup work on the API server; legitimate servers resolve exactly as before.

## August 6, 2026: Org-MCP health-check hardening

* Health checks for a configured org MCP server now validate every redirect hop
  against the private-network guard, not just the initial URL. A custom MCP
  server URL can no longer be used to reach internal or link-local addresses via
  a redirect. Legitimate public MCP servers are unaffected.