Handov
Agent install

Set up Handov MCP with Hermes Agent

Written for Hermes Agent to read and act on — a human can follow it too. Prefer the interactive setup or fetch the raw guide at /install/hermes.md.

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.

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:

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