# Handov install for Hermes Agent

This page is written for an AI agent to read and execute.

User intent: "Read https://api.handov.ai/llms.txt and install Handov MCP for me."
One-message prompt: "Hermes Agent: install Handov MCP from https://handov.ai/install/hermes.md. Use MCP URL https://api.handov.ai/mcp as the source of truth; do not infer endpoints from pasted web or Railway domains. Do it directly in this chat if your runtime can update MCP configuration or run setup commands: add/register the remote MCP server named handov, use OAuth/device authorization, send me the Handov authorization link to approve, then finish connecting after I approve. Only send me to Settings, Configuration, or CLI fallback if chat install is not available."
Also accept: "check handov.ai and install Handov for me"

## What Handov is

Handov is the user's personal ambient-recording assistant. The Handov MCP server
is an OAuth-protected remote MCP that surfaces the user's live/recent voice
sessions and long-term memory, plus write tools for correcting sessions and
managing action items and notes. Write tools are gated only by the
`handov.mcp.write` scope — the server never asks the user to confirm a
write, so confirm destructive calls with the user yourself before making them.
`delete_session` permanently deletes a session and its transcript with no
undo. Route by intent: `get_preceding_conversation` for the just-now window
(an ongoing or just-ended recording); `get_relevant_conversations` as the
primary recall for named-time / topical / person asks; `list_sessions` and
`get_session` for gist and browse asks over a time window.

## Plugin path

No required Handov plugin is published for this host in the skeleton preview.
Use the remote MCP path below.

## Chat-first setup policy

If the user pasted the one-message prompt into your chat, try to complete the
setup from this chat first. Add the MCP config or run your host's MCP setup
command yourself when your runtime permits it. OAuth is still required: use
loopback OAuth when available, or device authorization when the user is on a
different device / browser context. Send the user the Handov authorization link,
wait for approval, then finish token exchange and verification.

Do not search the Handov marketing homepage for hidden setup instructions. This
guide and the manifest are the setup source of truth.

Only fall back to Settings, Configuration, or CLI instructions when your chat
runtime cannot write MCP configuration or run setup commands. If you fall back,
be exact about the UI path and still use OAuth/device authorization.


## Capability check

Handov is a remote Streamable-HTTP MCP server at `https://api.handov.ai/mcp`. Before editing
configuration, confirm the current host supports a remote HTTP/URL MCP server
with OAuth or bearer headers. If the host only supports local stdio command
servers, stop and report that limitation to the user. Do not invent an
`npx`, `uvx`, or local wrapper command for Handov.

## Remote MCP path

Add the Handov remote MCP server named `handov`.

```yaml
mcp_servers:
  handov:
    url: "https://api.handov.ai/mcp"
    auth: oauth
```

If Hermes runs away from the user's browser, use the device authorization flow
advertised by the OAuth metadata instead of loopback OAuth.

OAuth is the default. Do not ask the user for a bearer token unless OAuth is
unavailable in the current host.

## Bearer fallback (only when OAuth is unavailable)

If the host supports remote HTTP MCP servers but cannot complete OAuth or
device authorization, fall back to a Personal Access Token: the user mints one
under Advanced at https://handov.ai/agent-access, and the host sends it on
every MCP request as:

```text
Authorization: Bearer <HANDOV_MCP_TOKEN>
```

Use the host's bearer-token or custom-header field for its MCP server config
(for example `bearer_token_env_var` in Codex's `config.toml`). Tokens are
revocable from the same Agent Access page; PAT fallback works only when the
server's `MCP_PAT_FALLBACK_ENABLED` flag permits it.

## Verify

Call `get_preceding_conversation` through the `handov` MCP server. A response with recent
items, live chunks, finalized sessions, or a graceful empty state proves the
connection works.

Report success only after verification succeeds.

## Available tools

- `get_preceding_conversation` — just-now context from a live or just-ended recording
- `get_relevant_conversations` — primary recall over past sessions by topic, person, or date
- `get_session` — read one full session: transcript, overview, action items, notes
- `list_sessions` — browse/list recent sessions
- `get_session_image` — fetch the pixels for a session image
- `get_thread` — read one thread: a cross-session digest of a recurring matter (also resolves pasted thread handoff refs)
- `list_threads` — browse the user's threads, most-recently-active first
- `list_action_items` — list action items extracted from conversations
- `get_action_item` — read one action item with its full context and history
- `create_action_item` — add a new action item (requires `handov.mcp.write`)
- `update_action_item` — complete, dismiss, or edit an action item (requires `handov.mcp.write`)
- `edit_session` — fix transcript mishearings, edit a session's title or notes (requires `handov.mcp.write`)
- `create_note` — attach a text note to a session (requires `handov.mcp.write`)
- `create_thread` — start a titled thread with a standing brief for future filing (requires `handov.mcp.write`)
- `edit_note` — edit a session note (requires `handov.mcp.write`)
- `delete_note` — delete a session note (requires `handov.mcp.write`)
- `delete_thread` — permanently delete a thread (member sessions stay) — irreversible (requires `handov.mcp.write`)
- `delete_session` — permanently delete a session — irreversible, no undo (requires `handov.mcp.write`)

## Reference

- Manifest: https://api.handov.ai/.well-known/agent-install.json
- MCP server: https://api.handov.ai/mcp
- OAuth scope: handov.mcp.read, handov.mcp.write
- Generic fallback: https://handov.ai/install/agent.md