# Handov

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

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

## Install brief

Handov is a remote OAuth Streamable-HTTP MCP server for ambient conversation memory. Install the server named handov at https://api.handov.ai/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.handov.ai/llms.txt and install Handov MCP for me.", do this:

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

## Not yet validated

These hosts are listed for discovery but do not have a validated Handov 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 Handov homepage or inventing a local stdio command:

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

## MCP

MCP server: https://api.handov.ai/mcp
Auth: OAuth
Scope: handov.mcp.read, handov.mcp.write

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

## Handoff refs

A pasted Handov handoff ref — canonical `<title> (Handov Kind ID: <id>)`, with
legacy `<title> (Ambi Kind ID: <id>)` / `<title> (Kind ID: <id>)` and
`…/h/{kind}/{id}` forms still accepted —
is a reference to a session, action item, thread, or live conversation. The
user picked that exact thing in Handov and
handed it to their agent — skip discovery and resolve it directly. The
paste starts with one line — `<title-snapshot> (Handov 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.handov.ai/mcp):

- `/h/action/{id}` → `get_action_item` with the pasted ref text (canonical or
  legacy label, or 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 (canonical or
  legacy label, or 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 (canonical or legacy label, or 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 (canonical or
  legacy label, or 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: Handov PAT or OAuth token; resolve needs scope
`handov.mcp.read`, close needs `handov.mcp.task_write` or `handov.mcp.write`):

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

No token yet? Ask the user to mint a PAT (`ambp_…`) in the Handov web app at
`https://handov.ai/agent-access` (Agent Access), or drive OAuth (`amba_…`) from the
RFC 9728 protected-resource metadata at
`https://api.handov.ai/.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.