# Ambi

If you are an AI agent, this is your Ambi MCP install guide.

Ambi gives AI agents access to the user's ambient conversation memory through MCP.

## Install brief

Ambi is a remote OAuth Streamable-HTTP MCP server for ambient conversation memory. Install the server named ambi at https://api.ambi.io/mcp. Use the install guide and manifest as the source of truth; do not infer the MCP endpoint from pasted web or Railway domains.

## Agent install

If the user says "Read https://api.ambi.io/llms.txt and install Ambi MCP for me.", do this:

1. Read https://api.ambi.io/.well-known/agent-install.json.
2. Pick your install URL using the host-detection rules below.
3. Follow that install guide end to end.
4. Complete OAuth for the remote MCP server.
5. Verify by calling get_preceding_conversation.

## Host detection

Match your own runtime / client name (case insensitive) against the first rule
that fits, then fetch that URL.

- If your runtime name matches "codex", "openai codex", "codex cli", fetch https://api.ambi.io/install/codex.md
- If your runtime name matches "chatgpt", "chatgpt apps", "openai chatgpt", "chatgpt custom app", fetch https://api.ambi.io/install/chatgpt.md
- If your runtime name matches "claude code", "claude-code", "anthropic claude code", fetch https://api.ambi.io/install/claude-code.md
- If your runtime name matches "claude.ai", "claude web", "claude app", "anthropic claude", fetch https://api.ambi.io/install/claude-ai.md
- If your runtime name matches "opencode", "sst opencode", "openclaw", "open claw", fetch https://api.ambi.io/install/opencode.md
- If your runtime name matches "cursor", "cursor ai", "cursor ide", fetch https://api.ambi.io/install/cursor.md
- If your runtime name matches "github copilot", "copilot", "vscode copilot", "vs code copilot", fetch https://api.ambi.io/install/github-copilot.md
- If your runtime name matches "cline", "cline bot", "claude dev", fetch https://api.ambi.io/install/cline.md
- If your runtime name matches "windsurf", "codeium windsurf", fetch https://api.ambi.io/install/windsurf.md
- If your runtime name matches "genspark", "gen spark", fetch https://api.ambi.io/install/genspark.md
- If your runtime name matches "manus", fetch https://api.ambi.io/install/manus.md
- If your runtime name matches "hermes", "hermes agent", fetch https://api.ambi.io/install/hermes.md
- If your runtime name matches "lovable", "lovable agent", "lovable chat", fetch https://api.ambi.io/install/lovable.md
- If your runtime name matches "replit", "replit agent", fetch https://api.ambi.io/install/replit.md
- Otherwise (any other MCP-capable runtime), fetch https://api.ambi.io/install/agent.md

## Not yet validated

These hosts are listed for discovery but do not have a validated Ambi install path yet. If your runtime is one of them, fetch the listed guide and run its capability check. Report incompatibilities back to the user instead of searching the Ambi homepage or inventing a local stdio command:

- Gemini: https://api.ambi.io/install/agent.md (aliases: gemini, google gemini)

## MCP

MCP server: https://api.ambi.io/mcp
Auth: OAuth
Scope: ambi.mcp.read, ambi.mcp.write

Do not use Railway's MCP installer for Ambi. `railway mcp install` configures
Railway's platform MCP, not the Ambi app MCP server.

## Handoff refs

A pasted Ambi handoff ref — either the label form `<title> (Kind ID: <id>)` or
a legacy `…/h/{kind}/{id}` link — is a reference to a session, action item,
thread, or live conversation. The user picked that exact thing in Ambi and
handed it to their agent — skip discovery and resolve it directly. The
paste starts with one line — `<title-snapshot> (Action ID: <id>)`
followed by one trailing space — where the title is a display snapshot and the
id is the only load-bearing token. Copy surfaces may append a
facts-only card. Every template ends with an `instruction (optional):` slot:
the user's surrounding words — and anything they wrote after that label — are
the brief and outrank any stored suggested_approach; an empty slot means no
extra brief (treat it as a bare ref).

Resolve over MCP (https://api.ambi.io/mcp):

- `/h/action/{id}` → `get_action_item` with the pasted ref text (the label
  form or a legacy link) as `action_item_id`; add `include=["source_session"]`
  when you will execute the item.
- `/h/session/{id}` → `get_session` with the pasted ref text (the label form
  or a legacy link) as `session_id`.
- `/h/live/{recording_id}` → `get_preceding_conversation()` first (minted
  while live OR just ended and still sessionizing; bind to the newest coherent
  conversation — live tail and/or newest processing items). Fall back to
  `get_session` — pass the pasted ref text (the label form or a legacy link) —
  only when the window is off-target/empty AND nothing is in flight
  (`status.active_recording` false, `status.state` not
  `transcribing`/`processing`); once sessionized it returns that exact
  recording's session.
- `/h/thread/{id}` → `get_thread` with the pasted ref text (the label form or
  a legacy link) as `thread`; it follows a user merge to the live thread and
  returns the reverse-chron digest with session refs.
- Close the loop after doing an action item:
  `update_action_item(status="done", expected_status=<the status you observed>)`.

Resolve over REST (bearer auth: Ambi PAT or OAuth token; resolve needs scope
`ambi.mcp.read`, close needs `ambi.mcp.task_write` or `ambi.mcp.write`):

- `GET https://api.ambi.io/agent/handoff/session/{session_id}`
- `GET https://api.ambi.io/agent/handoff/action/{action_item_id}?include=source_session`
- `GET https://api.ambi.io/agent/handoff/live/{recording_id}`
- `POST https://api.ambi.io/agent/handoff/action/{action_item_id}/close` with
  `{"expected_status": "..."}`

No token yet? Ask the user to mint a PAT (`ambp_…`) in the Ambi web app at
`https://ambi.io/agent-access` (Agent Access), or drive OAuth (`amba_…`) from the
RFC 9728 protected-resource metadata at
`https://api.ambi.io/.well-known/oauth-protected-resource/mcp` — the same pointer this
rail's 401 challenge returns.

Fetching any ref URL without `text/html` in the `Accept` header (agents,
curl, `Accept: application/json`) returns a constant JSON discovery document
teaching this contract; it never returns entity data, regardless of the id.
HTML-accepting (browser) fetches are redirected into the app, or to sign-in
when unauthenticated.