{
  "markdown": "# Handover MCP\n\nMove active work between Claude Code, Codex, Cursor, Gemini CLI, people, and\nservice agents without losing decisions, files, history, or authorship.\n\n[![npm CLI](https://img.shields.io/npm/v/handover-sh?label=handover-sh&logo=npm)](https://www.npmjs.com/package/handover-sh)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-verified-2684ff)](https://registry.modelcontextprotocol.io/v0.1/servers?search=sh.handover%2Fhandover)\n[![Agent Skills](https://img.shields.io/badge/Agent_Skills-8-84cc16)](https://skills.handover.sh/?utm_source=github&utm_medium=referral&utm_campaign=agent_skills_launch)\n[![skills.sh](https://skills.sh/b/44-pixels/handover-mcp)](https://www.skills.sh/44-pixels/handover-mcp)\n[![MIT License](https://img.shields.io/badge/license-MIT-111111)](LICENSE)\n\n[Handover](https://handover.sh/?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch)\nprovides shared, versioned context for humans and AI agents through a hosted\nModel Context Protocol server, a dependency-free CLI, and eight open Agent\nSkills. This repository is the public source, discovery, installation, and\nconnection record for those interfaces.\n\n![Handover product interface](https://handover.sh/og.png)\n\n## Research and evidence\n\nThe [Handover research and evidence\nindex](https://handover.sh/research?utm_source=github&utm_medium=referral&utm_campaign=research_evidence)\ncollects the open continuity benchmark, Reporter migration field report,\nHandoff Continuity Record, and runnable continuation demo. Findings stay beside\ntheir methods, source artifacts, first-party relationship, and material\nlimitations.\n\nThe versioned [`research/v1/`](research/v1/) package gives agents and\nresearchers a stable JSON index, JSON Schema, citation metadata, and a bounded\nMarkdown summary. The package is a first-party publication by Handover and\n44pixels; it is designed for inspection and reuse, not presented as independent\nvalidation.\n\n- [Human research index](https://handover.sh/research?utm_source=github&utm_medium=referral&utm_campaign=research_evidence)\n- [Agent-readable production index](https://handover.sh/research.json)\n- [Versioned repository index](research/v1/index.json)\n- [Citation metadata](research/v1/CITATION.cff)\n- [Run and submit an independent benchmark result](benchmark/v1/independent-results/)\n\n## See a complete handoff\n\nThe [public continuation\ndemo](https://handover.sh/demo?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch_demo)\nshows the same workflow from both sides: an interactive human view and an\nagent-readable record. It includes Markdown, SQL, JSON, a visual artifact,\nthree attributable revisions, a human review note, and the next agent's\nresolution. No account is required.\n\n- [Interactive demo](https://handover.sh/demo?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch_demo)\n- [Continue the demo in your workspace](https://handover.sh/app?start=demo&utm_source=github&utm_medium=referral&utm_campaign=public_continuation_demo)\n- [Demo workflow and verification notes](DEMO.md)\n- [Agent-readable manifest](https://handover.sh/demo.json)\n- [Raw Markdown](https://handover.sh/demo/context.md)\n- [Raw SQL](https://handover.sh/demo/inventory.sql)\n- [Evidence JSON](https://handover.sh/demo/evidence.json)\n\n## Build a private handoff prompt\n\nThe [AI handoff prompt\ngenerator](https://handover.sh/tools/ai-handoff-prompt-generator?utm_source=github&utm_medium=referral&utm_campaign=ai_handoff_prompt)\nturns unfinished work into separate capture and receiver prompts without\nrequiring an account. Draft fields stay inside the browser tab and are not sent\nto analytics or stored as a server-side draft.\n\nThe receiver prompt requires the next actor to inspect the evidence, separate\nverified and unverified state, identify blockers, and state one bounded next\naction before continuing. Copy or download the Markdown record, or carry the\nsame private draft into a prefilled first handover.\n\n- [Open the private prompt generator](https://handover.sh/tools/ai-handoff-prompt-generator?utm_source=github&utm_medium=referral&utm_campaign=ai_handoff_prompt)\n- [Inspect the raw Markdown example](https://handover.sh/examples/ai-handoff-prompt.md)\n- [Decide when `HANDOFF.md` is enough](https://handover.sh/guides/handover-vs-handoff-md?utm_source=github&utm_medium=referral&utm_campaign=ai_handoff_prompt)\n\n## Move from Claude Code to Codex\n\nCodex's built-in import is the right first choice for a one-time move of\nsupported Claude Code setup, projects, memories, and recent chats. Use\nHandover when Claude Code and Codex will alternate on unfinished work and need\nshared artifacts, separate identities, review, and revision history.\n\nThe [Claude Code to Codex transfer\nrecipe](examples/claude-code-to-codex-context-transfer.md) contains the exact\nsender checkpoint, two-host service-credential setup, receiver verification,\noptimistic-concurrency continuation, revocation test, and pass criteria. The\n[rendered\nguide](https://handover.sh/guides/transfer-context-from-claude-code-to-codex?utm_source=github&utm_medium=referral&utm_campaign=claude_code_to_codex)\nexplains when to use native import and when to use a durable handoff.\n\n## Run the reviewed MCP handoff\n\nThe demo shows the finished record. The\n[end-to-end MCP handoff procedure](examples/end-to-end-mcp-handoff-workflow.md)\ntests the workflow itself across separate authenticated identities:\n\n1. verify the publisher;\n2. publish Markdown, SQL, and JSON;\n3. read every artifact back;\n4. review exact evidence from another identity;\n5. publish a correction with optimistic concurrency;\n6. resolve the finding against the correcting revision; and\n7. prove a fresh successor can continue without the original chat.\n\nIt also exercises denied, read-only, stale-revision, and revoked-credential\npaths. Use the [rendered\nguide](https://handover.sh/guides/end-to-end-mcp-agent-handoff?utm_source=github&utm_medium=referral&utm_campaign=mcp_handoff_e2e)\nfor the rationale, or connect an agent through the\n[install flow](https://handover.sh/install?utm_source=github&utm_medium=referral&utm_campaign=mcp_handoff_e2e)\nbefore running the repository procedure.\n\n## Use the AI agent handoff checklist\n\nFor a smaller local handoff, start with the\n[Markdown checklist](templates/agent-handoff.md). It captures the objective,\ncurrent state, decisions, evidence, constraints, next action, and ownership,\nthen requires the receiving actor to read the current revision, open the\nevidence, reproduce one meaningful result, and mark the handoff as passed or\nblocked.\n\nThe [rendered checklist and\nFAQ](https://handover.sh/templates/agent-handoff?utm_source=github&utm_medium=referral&utm_campaign=agent_handoff_checklist)\nexplains each verification step. The raw template works without Handover; use\nthe hosted service when multiple actors need authenticated access, immutable\nrevisions, search, annotations, or auditable ownership.\n\n## Test company AI context readiness\n\nBefore connecting company knowledge to several people and agents, use the\n[company AI context readiness checklist](templates/company-ai-context-readiness.md).\nIt separates approved source knowledge from changing continuation records,\ninventories human and service identities, declares company and workspace\nboundaries, and finishes with a two-person, two-agent pilot.\n\nThe pilot is intentionally stricter than an import count: it verifies\nauthorized retrieval, attributable revisions, human review, denied searches,\nagent revocation, and fresh-session continuation. The\n[source-linked architecture\nguide](https://handover.sh/guides/shared-workspace-for-humans-and-ai-agents?utm_source=github&utm_medium=referral&utm_campaign=company_ai_knowledge)\nexplains why a search index, private model memory, and canonical company\nrecords have different responsibilities.\n\n## Use the open handoff format\n\nThe [Handoff Continuity\nRecord](https://handover.sh/protocol?utm_source=github&utm_medium=referral&utm_campaign=handoff_continuity_record)\nis a platform-neutral JSON format for the state another human or AI agent needs\nto verify and continue work. It records the objective, verified and unverified\nstate, decisions, evidence, constraints, next action, ownership, and open\nreview without prescribing transport, routing, authentication, or storage.\n\nThe [`protocol/v1/`](protocol/v1/) directory contains:\n\n- a JSON Schema Draft 2020-12 contract;\n- a valid inventory-reporting example;\n- a dependency-free Node.js conformance checker; and\n- producer, receiver, scope, and security requirements.\n\n```bash\nnode protocol/v1/validate.mjs protocol/v1/example.json\n```\n\nMCP can expose the tools used to read and write the record. A2A or an\norchestration framework can route it. Git or Handover can store it.\n\n## Connect\n\nThe canonical Streamable HTTP endpoint is:\n\n```text\nhttps://handover.sh/api/mcp?profile=core\n```\n\nThe recommended core profile exposes 17 tools for everyday identity, search,\nretrieval, review, continuation, publishing, and portability workflows. Use\n`https://handover.sh/api/mcp?profile=native` for all 27 first-party Handover\noperations. The unparameterized `https://handover.sh/api/mcp` endpoint retains\nall 55 tools and Reporter aliases for existing integrations.\n\nThe endpoint exposes its MCP handshake and tool schemas without an account so\nclients and directories can verify compatibility before connecting. Tool calls\nremain protected and return Handover's OAuth resource challenge when no valid\nhuman or service credential is present.\n\nInteractive MCP hosts use Handover's first-party OAuth flow: standard discovery,\ndynamic client registration, PKCE, short-lived access tokens, and rotating\nrefresh tokens. The host opens Handover in a browser; sign in as yourself,\nreview the requested permissions, and approve the connection. Handover records\nyour human identity on every attributable action.\n\nUnattended runners and hosts without OAuth support use a separately named,\nscoped service credential created under **Workspace or Company -> Agents**.\nHuman and service identities remain independently attributable and revocable.\n\nFor the complete setup, identity check, two-agent continuity test, and\ntroubleshooting flow, see [CONNECTING.md](CONNECTING.md).\n\n### Codex\n\n```bash\ncodex mcp add handover --url https://handover.sh/api/mcp?profile=core\ncodex mcp login handover\n```\n\n### Claude Code\n\n```bash\nclaude mcp add --transport http --scope user \\\n  handover https://handover.sh/api/mcp?profile=core\n```\n\n### Gemini CLI\n\n```bash\ngemini mcp add --transport http --scope user \\\n  handover https://handover.sh/api/mcp?profile=core\n```\n\n### Cursor\n\nAdd this to `.cursor/mcp.json`. Cursor discovers Handover's authorization\nserver and prompts for browser sign-in when the connection starts:\n\n```json\n{\n  \"mcpServers\": {\n    \"handover\": {\n      \"url\": \"https://handover.sh/api/mcp?profile=core\"\n    }\n  }\n}\n```\n\n### Cline\n\nOpen Cline's MCP wizard:\n\n```bash\ncline mcp install handover --transport http https://handover.sh/api/mcp?profile=core\n```\n\nChoose **Remote (HTTP)** and **Static headers**, then enter the scoped service\nagent credential in Cline's private header prompt. The agent-readable\n[`llms-install.md`](llms-install.md) includes the exact configuration, identity\ncheck, safe first write, two-agent continuation test, and revocation procedure.\nUse the [first-party Cline setup\npage](https://handover.sh/install?utm_source=cline&utm_medium=marketplace&utm_campaign=cline_marketplace)\nfor the complete Handover flow. Do not paste a real credential into chat or\ncommit Cline's private MCP settings.\n\n## Command-line client\n\nThe dependency-free Handover CLI supports the same durable workflow from a\nterminal:\n\n```bash\nnpm install --global handover-sh\nhandover login\nhandover doctor\nhandover search \"billing migration\"\nhandover pull <slug-or-url> --out ./continued-work\nhandover publish ./report --title \"Weekly report\"\n```\n\nThe published package source and metadata live in [`cli/`](cli/). The audited\ndirect installer remains available when npm is not appropriate:\n\n```bash\ncurl -fsSL https://handover.sh/install.sh | sh\n```\n\nPackage releases are built from this public repository. The bootstrap and\ntrusted-publishing process is documented in [RELEASING.md](RELEASING.md).\n\n`handover doctor` is a read-only connection check. It verifies the configured\nendpoint, server-resolved identity, workspace, role, scopes, and one protected\ncontext request without printing the credential or changing a handover. Use\nthe [complete verification checklist](https://handover.sh/guides/test-mcp-server-connection-cli?utm_source=github&utm_medium=referral&utm_campaign=cli_doctor)\nbefore an agent's first write.\n\n## Agent Skills\n\nInstall reusable Handover workflows into a compatible coding agent with the\nopen Agent Skills format:\n\n[![skills.sh](https://skills.sh/b/44-pixels/handover-mcp)](https://skills.sh/44-pixels/handover-mcp)\n\n```bash\nnpx skills add 44-pixels/handover-mcp --list\nnpx skills add 44-pixels/handover-mcp --skill handoff\nnpx skills add 44-pixels/handover-mcp --skill handover-record\nnpx skills add 44-pixels/handover-mcp --skill handover-publish\nnpx skills add 44-pixels/handover-mcp --skill handover-test-continuity\n```\n\nThe public collection includes a local-first session handoff, skills for\ncreating and validating machine-readable records, verifying connections,\npublishing context, resuming work,\nreviewing revision-anchored feedback, testing complete multi-identity\ncontinuity, and governing agent access. Browse the\ncatalog at [skills.handover.sh](https://skills.handover.sh/) or inspect the\nsource in [`skills/`](skills/). The collection is also indexed in the\n[Skills.sh directory](https://www.skills.sh/44-pixels/handover-mcp).\nThe catalog organizes skills by handoff phase, includes a plain-language\nstarting request for each workflow, and exposes the exact MCP tools and CLI\ncommands through its [machine-readable\nindex](https://skills.handover.sh/index.json).\n\nThe runtime is independently listed as\n[`sh.handover/handover` in the official MCP\nRegistry](https://registry.modelcontextprotocol.io/v0.1/servers?search=sh.handover%2Fhandover).\n\nThe [Agent Skills and MCP\nguide](https://handover.sh/guides/agent-skills-and-mcp?utm_source=github&utm_medium=referral&utm_campaign=agent_skills_mcp)\nexplains the boundary between portable workflow instructions and authenticated\nruntime capabilities. Its [raw end-to-end\nworkflow](https://handover.sh/examples/agent-skill-mcp-workflow.md?utm_source=github&utm_medium=referral&utm_campaign=agent_skills_mcp)\nis designed for direct agent retrieval.\n\nFor host-specific installation, use the tested [Claude Code, Codex, Cursor,\nand Gemini CLI\nguide](https://handover.sh/guides/install-agent-skills-claude-code-codex-cursor-gemini?utm_source=github&utm_medium=referral&utm_campaign=cross_host_skills).\nIts [raw verification\nchecklist](https://handover.sh/examples/cross-host-agent-skill-install.md?utm_source=github&utm_medium=referral&utm_campaign=cross_host_skills)\nseparates file installation from host discovery, skill activation,\nauthenticated MCP identity, read-back, denied access, and cross-host\ncontinuation.\n\nTo publish a workflow that uses Handover, start with the\n[Agent Skill developer\nkit](https://skills.handover.sh/publish?utm_source=github&utm_medium=referral&utm_campaign=agent_skill_mcp_builder),\nthe [contributor contract](CONTRIBUTING.md), and the\n[starter skill](templates/handover-skill/SKILL.template.md). Copy the starter\ninto a new `skills/<name>/SKILL.md`; the template deliberately does not use the\nreserved filename so registries cannot mistake it for an installable skill.\nCommunity submissions keep\ntheir publisher and source attribution; catalog inclusion does not widen\nHandover access or replace source review.\n\nValidate the local contract before testing the authenticated workflow:\n\n```bash\nnode templates/handover-skill/validate.mjs skills/<name>/SKILL.md\n```\n\nPassing this validator proves the file contract, not host discovery, MCP\nauthentication, permissions, read-back, or denied behavior. The developer kit\nkeeps those runtime checks explicit.\n\n## Open continuity benchmark\n\nThe [AI Handoff Continuity\nBenchmark](https://handover.sh/benchmark?utm_source=github&utm_medium=referral&utm_campaign=continuity_benchmark_results)\ntests whether a successor model can recover the objective, current state,\ndecisions, evidence, constraints, next action, owner, and open questions from\na transcript, compressed memory, or structured handoff.\n\nThe first two-system pilot scored structured handoffs at 79.45, conversation\ntranscripts at 76.67, and compressed memory at 45.00. It is a small authored\npilot rather than a model leaderboard. The public [`benchmark/`](benchmark/)\ndirectory contains the dataset, answer key, dependency-free scorer, strict\nsubmissions, deterministic results, limitations, and all 18 raw response\nbodies. Reuse the published\n[`CITATION.cff`](benchmark/v1/CITATION.cff),\n[`citation.bib`](benchmark/v1/citation.bib), or flat\n[`summary.csv`](benchmark/v1/results/2026-08-04/summary.csv) instead of\ntranscribing values from the page.\n\n```bash\ncd benchmark/v1\nnode run.mjs --validate-scorer\nnode run.mjs --prompts ./prompts\n```\n\n## What agents can do\n\nConnected agents can:\n\n- verify the active identity, organization, workspace, and scopes with\n  `handover.whoami`;\n- search company or personal context;\n- inspect an exact immutable revision;\n- read attached Markdown, HTML, SQL, JSON, code, images, and other files;\n- retrieve discussions and revision-anchored annotations;\n- create a new handover or continue an existing one;\n- add, edit, resolve, and respond to review comments;\n- preserve the authenticated human or service identity in the audit history.\n\nThe server never asks an agent to provide an author identity in tool input.\nAuthorship comes from the authenticated credential.\n\n## Verify the connection\n\nAsk the connected host to perform these calls before real work:\n\n1. Call `handover.whoami` with no arguments and confirm the returned person or\n   named service agent, organization, workspace, role, and scopes.\n2. Call `handover.search` with `{ \"query\": \"\" }` and confirm it returns only\n   context that identity should be able to access.\n3. Read one known handover and artifact before creating or continuing work.\n\nA working connection lists Handover's tools without a JSON or sign-in error,\npreserves the intended identity as author, and immediately stops working after\nthe OAuth grant or service credential is revoked.\n\n## Service agents\n\nWorkspace owners create service agents in Handover and grant only the scopes\nthat actor needs. Store the credential in `HANDOVER_TOKEN`; do not put it in a\nrepository or MCP configuration committed to source control.\n\n```bash\nexport HANDOVER_TOKEN='hnd_tok_...'\ncodex mcp add handover \\\n  --url https://handover.sh/api/mcp?profile=core \\\n  --bearer-token-env-var HANDOVER_TOKEN\n```\n\n## Discovery and documentation\n\n- [No-login continuation demo](https://handover.sh/demo?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch_demo)\n- [AI agent handoff checklist](templates/agent-handoff.md)\n- [Company AI context readiness checklist](templates/company-ai-context-readiness.md)\n- [Shared knowledge base architecture guide](https://handover.sh/guides/shared-workspace-for-humans-and-ai-agents?utm_source=github&utm_medium=referral&utm_campaign=company_ai_knowledge)\n- [End-to-end reviewed MCP handoff](examples/end-to-end-mcp-handoff-workflow.md)\n- [Rendered MCP handoff guide](https://handover.sh/guides/end-to-end-mcp-agent-handoff?utm_source=github&utm_medium=referral&utm_campaign=mcp_handoff_e2e)\n- [Install and host-specific setup](https://handover.sh/install?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch)\n- [MCP memory setup for Claude Code, Cursor, and Codex](https://handover.sh/guides/mcp-memory-server-for-claude-code-cursor-codex?utm_source=github&utm_medium=referral&utm_campaign=mcp_memory_setup)\n- [Raw cross-host setup and continuity test](https://handover.sh/examples/mcp-memory-server-setup.md?utm_source=github&utm_medium=referral&utm_campaign=mcp_memory_setup)\n- [Claude Code to Codex context transfer](examples/claude-code-to-codex-context-transfer.md)\n- [Rendered Claude Code to Codex guide](https://handover.sh/guides/transfer-context-from-claude-code-to-codex?utm_source=github&utm_medium=referral&utm_campaign=claude_code_to_codex)\n- [Connection and verification runbook](CONNECTING.md)\n- [MCP workflow guide](https://handover.sh/guides/mcp-workflow-for-multi-agent-collaboration?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch)\n- [MCP OAuth vs service accounts](https://handover.sh/guides/mcp-oauth-vs-service-accounts?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch)\n- [Preserve context across AI coding agents](https://handover.sh/guides/preserve-context-across-ai-coding-agents?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch)\n- [Migrate static report folders](https://handover.sh/guides/migrate-static-report-folders-to-shared-ai-context?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch)\n- [Glama hosted connector](https://glama.ai/mcp/connectors/sh.handover/handover)\n- [Machine-readable host recipes](https://handover.sh/recipes/mcp-hosts.json)\n- [MCP server manifest](https://handover.sh/.well-known/mcp.json)\n- [Agent tool manifest](https://handover.sh/agent-tools.json)\n- [OpenAPI document](https://handover.sh/openapi.json)\n- [Agent-readable knowledge corpus](https://handover.sh/llms-full.txt)\n- [Security model](https://handover.sh/security?utm_source=github&utm_medium=referral&utm_campaign=mcp_launch)\n\n## Source and support\n\nThe hosted Handover application source is maintained in a private repository.\nThis public repository contains the MCP connection record, setup documentation,\nand the source of the dependency-free CLI, not the hosted service\nimplementation.\n\nReport connection or documentation problems through\n[GitHub Issues](https://github.com/44-pixels/handover-mcp/issues). Report\nsecurity concerns using the process in [SECURITY.md](SECURITY.md).\n",
  "bytes": 22138,
  "sha": "3e0caf4d3805886a6fa947f72b5e71bbe18661c3962f08d60ef174180704ae60",
  "repo_slug": "44-pixels/handover-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_sh_handover_handover_324b1541/readme"
}