Connect

What is Handoff?

Handoff turns scattered knowledge, information, memories, conversations, sources, and otherwise lost AI context into a real‑time, machine‑readable graph hosted independently of the current new agentic environment so you and your agents dont have to worry about migrating between them everytime a new one is launched.

The Problem

Valuable knowledge often disappears when you leave a chat or gets locked in ad‑hoc “memory” layers-opaque black boxes that are difficult to inspect, share, parse, and use. Teams bounce between chat and docs, copying and pasting, trying to keep context in sync. You end up in markdown agent/context‑file hell.

The Solution

Handoff gives you durable, shared context through four simple actions:

• Capture - Save knowledge, notes, and sources as structured items
• Organize - Connect items into graphs that reflect how ideas relate
• Track - Version history keeps everything auditable and reversible
• Share - Expose context to agents and teammates via MCP in real-time

Agent‑First Model

Handoff is the context middleware between your sources and your AI work environments. It’s agent‑first by design, so your structure remains stable as models and hosts evolve.

Core Concepts

• Spaces group related work; each has a root item.
• Items can be Empty (structure‑only) or Text (markdown). Either way, they can carry structured fields (stored in props.fields) and children.
• Edges connect items to form sub‑graphs you can reuse.

See Context Retrieval for how to get this context into your AI.

Note: today only contains edges are supported; additional edge types - including custom - are planned in a future update.

What it's not (primarily)

While Handoff can serve as a docs or wiki, it's primarily an interface for AI and human systems to collaborate in real time-a stable, resilient control envelope that lets agents consume and manage knowledge quickly (sometimes autonomously) while keeping teams in the driver's seat through a dynamic, real‑time UI.

How it works

Handoff sits between your sources and your agents as the context layer, memory playground, and control plane. It works with your own agents using the Model Context Protocol (MCP) as the backplane-a deliberate choice so Handoff provides real value with your existing tools. Anything you do in the app you can also do via your own MCP client.

Use Cases

Below are concrete use cases Handoff supports. See Context Retrieval for the three ways to get this context into your AI.

• Memory for agents: assemble items and links to dynamically share context during agentic runs; capture and reuse results.
• Structured docs & note taking: organize living notes, outlines, and pages as Items (Empty/Text); link with contains edges.
• Collections & lists: track tasks, references, bookmarks, or datasets as Items; group with contains edges.
• Research graphing: capture notes and papers as Items; relate authors, topics, findings; make it available for agents.
• Task & workflow management: structure tasks with status, priority, assignees, dependencies as Items; enable agents to generate briefs, flag overdue, and suggest next actions.
• Meeting capture: convert notes into structured Items (decisions, tasks, owners); drive automated follow‑ups.
• Requirements & specs: organize PRDs, constraints, examples as a linked sub‑graph; give coding agents just what they need.
• Content & knowledge ops: track sources, outlines, drafts; produce consistent, on‑brand output.
• Customer success / support memory: link accounts, issues, resolutions; help agents respond with correct, current context.
• Sales enablement: map accounts, contacts, collateral; provide relevant, permissioned info only.
• Project management & roadmaps: organize initiatives, milestones, dependencies as connected Items; align on status and priorities.
• Team wikis & onboarding: structure policies, processes, tribal knowledge as a searchable graph; give new hires and agents role‑specific context.

Experimental

• Agent buildroom (multi‑agent orchestration): coordinate multiple agents over long runs, sharing evolving context via Handoff; capture and link results for reuse.
• Interactive runbooks: encode steps as Items with ordered edges; let the agent read/track progress.
• Design system memory: track tokens/components as Items; generate consistent UI code/content.
• Dynamic code documentation: index source trees and architectures as Items; generate and maintain docs that agents consult and update.

Context Retrieval

There are three ways to retrieve context from Handoff into an AI chat or agent: the copy button in Handoff Studio UI, MCP tools, and MCP resources.

1. Copy Button (Handoff Studio)

The quickest way to get context into any AI chat. Select an item in Handoff Studio and use the Copy button to copy markdown to your clipboard.

1. Select an item to open the inspector header.
2. Click the copy icon dropdown and choose:
   • Tree - copies the item and all its children as markdown
   • Parent - copies only the selected item
3. Paste directly into any AI chat (Claude, ChatGPT, etc.).
4. Or use the download menu to save as AGENTS.md or CLAUDE.md for project-level context files.

2. MCP Tools

For agents connected via MCP, Handoff exposes tools to query and retrieve context programmatically.

• spaces - List all available workspaces (op="list")
• spaces - Get details about a specific workspace (op="get")
• items - List items in a workspace (optionally filtered by parent) using op="list"
• items - Get a specific item with its properties and content using op="get"
• search - Search across all workspaces by keyword

Agents can combine these tools to navigate your context graph, retrieve specific items, or search for relevant information.

3. MCP Resources

Each workspace is automatically exposed as an MCP resource. This allows MCP clients that support resources to inject entire workspaces as context when starting a new chat.

• Resources use the URI format space://workspace-name
• Reading a resource returns the entire workspace as a hierarchical markdown pack (rooted at the workspace root item)
• In Claude Desktop or other MCP clients, you can attach a workspace resource to provide full context at the start of a conversation

When to Use Each

• Copy button - Quick one-off context injection into any chat
• MCP tools - When agents need to query or navigate context dynamically during a session
• MCP resources - When you want to load a full workspace as starting context for a new conversation

Sessions

A session is a saved work context that you can hand off between models or return to later. Under the hood, each session is just a normal item in a space; the MCP server keeps a per‑user "session pointer" that remembers which item (and space) is currently active so tools don't need extra IDs. Each call to handoff appends a new session note and moves the pointer to the latest one.

Basic pattern

• At the start of work, call handin to load the active session's context, if any.
• When you're done or want to park progress, call handoff with a short markdown handoff context: what you did, key decisions, important items you touched, and how another agent should resume. The first line should be a short plain‑text label (no markdown heading); Handoff will turn it into a title like Session: 2025-12-11 - 2026 roadmap planning.
• If no session exists yet, handoff creates a new session note (usually under the space's root) and remembers it for the next handin.

Missing or deleted sessions

If the previously active session item or its space has been deleted or is no longer accessible, handin or handoff will clear the pointer and instruct the model to call handoff with a fresh summary to start a new session.

Advanced controls

• session with op="current" - return the currently active session pointer (no content load).
• session with op="start" - check whether a session is active and get guidance when none is set.
• session with op="select" - set or switch the active session pointer to an existing session item.
• session with op="clear" - clear the active session so the next handin behaves like a fresh workspace.

Next Steps

A quick path to put Handoff to work with your agents.

1) Get connected

• Copy the MCP URL from the header and add it in your host (ChatGPT, Claude, or Cursor).
• Open the host’s tools/resources view to confirm Handoff appears.

2) Build your first space

• Create a space and add a few Items (mix of Empty and Text).
• Add a few simple fields such as status, priority, owner and set values.

3) Retrieve context

There are three ways to get Handoff context into your AI: the copy button in Handoff Studio, MCP tools, and MCP resources. See Context Retrieval for details on each method.

4) Link and find

• Use contains edges (parent → child) to organize items into collections. Additional edge types - including custom - are planned.
• Use search to gather items by title/tags and embed results into a page.

5) Grow safely

• Iterate on your fields and structure as you learn; items keep working as structure evolves.
• Keep humans in the loop with agent presence and preview (soon); add review workflows when needed.

ChatGPT Setup

Add Handoff as a Custom Connector (MCP), then enable it in a chat.

Requirements

• Plus/Pro: enable Developer mode in Settings.
• Business/Enterprise/Edu: admins may need to allow custom connectors.

Add the connector

• ChatGPT → Settings → Apps & Connectors → Add custom connector.
• Paste the MCP URL: https://mcp.handoff.computer/mcp and save.

Use in chat

• Open a chat → Tools → Use connectors or Deep research.
• Select Handoff and ask your question.

Troubleshooting

• “This MCP server doesn't implement our specification” → ensure the URL is correct.
• “Admin approval required” → ask your admin to enable custom connectors.

Reference: Connectors in ChatGPT

Use with Codex (CLI/IDE)

Configure Codex to use Handoff via a remote HTTP MCP server.

1. Edit ~/.codex/config.toml and add:

   rmcp_client = true
   
   [mcp_servers.handoff]
   url = "https://mcp.handoff.computer/mcp"

2. In a terminal, run codex mcp login handoff to log in to the Handoff MCP server.
3. Restart Codex (CLI or IDE extension) and verify with codex mcp list.

Claude Setup

Add Handoff as a custom connector using a remote MCP URL, then enable tools in chat.

Plans

• Available on Pro, Max, Team, and Enterprise (beta).

Add the connector

• Claude (web or Desktop) → Settings → Connectors → Add custom connector.
• Name: Handoff
• URL: https://mcp.handoff.computer/mcp

Enable and use

• In chat, open Search and tools, connect, and enable relevant tools.
• Disable write‑capable tools when not needed.

Reference: Claude custom connectors (remote MCP)

Use with Claude Code (IDE)

Add Handoff as a remote HTTP MCP server for Claude Code.

1. Run: claude mcp add --transport http handoff https://mcp.handoff.computer/mcp
2. In Claude Code, use /mcp to view and manage servers; enable Handoff tools for your project.

Cursor Setup

Add Handoff to your mcp.json config file, then restart Cursor.

1. Copy the config

{
  "mcpServers": {
    "handoff": {
      "url": "https://mcp.handoff.computer/mcp"
    }
  }
}

2. Add to mcp.json

• Global: ~/.cursor/mcp.json
• Project: .cursor/mcp.json in your project root
• If the file exists, merge the mcpServers object with your existing config.

3. Restart & verify

• Restart Cursor after saving the config.
• Open the Composer and check Available Tools for Handoff.
• Toggle tools as needed; optionally enable auto‑run.

Reference: Cursor MCP docs

Gemini CLI Setup

Add Handoff as a remote HTTP MCP server using the Gemini CLI.

Add the server

Run this command to add Handoff:

gemini mcp add --transport http handoff https://mcp.handoff.computer/mcp

Verify installation

List your configured servers to verify Handoff is connected:

gemini mcp list

Or use the interactive MCP UI within Gemini:

/mcp

Remove the server

To remove Handoff from your configuration:

gemini mcp remove handoff

Configuration options

• Add --trust to bypass tool confirmation prompts
• Add -s user to save to user config instead of project
• Configuration is stored in .gemini/settings.json (project) or ~/.gemini/settings.json (user)

Other Hosts

Most MCP‑capable hosts support adding a remote MCP server. Look for settings like “Add custom connector”, “Remote MCP URL”, or mcp.json configuration.

• Server URL: https://mcp.handoff.computer/mcp
• After adding, enable tools/resources for your session.

Tools

Current Handoff MCP tools available in supported hosts.

Identity

• whoami - return your current user identity (userId).

Spaces

• spaces - list, get, create, update, or delete spaces using op="list" | "get" | "create" | "update" | "delete".

Items

• items - list, get, create, update, move, reorder, or delete items using op="list" | "get" | "create" | "update" | "move" | "reorder" | "delete".

Icon hint: tools may set props.ui.icon to a single string value using a lucide-react icon name in kebab-case (for example file-text, layers). The UI resolves this name to a Lucide icon when rendering items.

Edges

• edges - list, get, update, or delete edges using op="list" | "get" | "update" | "delete".

Note: today only contains edges are supported; additional edge types - including custom - are planned.

Search

• search - find items by title (and more), optionally scoped to a space.

History

• history - list commits, fetch a commit with revisions, or revert using op="list" | "get" | "revert".

Sessions

• handin - load the active session's context, if any; returns instructions when no session is active.
• handoff - append a markdown handoff note and move the active session pointer to it; if no session exists, creates the first session note (usually under the space root).
• session - inspect or control the active session using op="current" | "start" | "clear" | "select".

Agent Presence

Presence lets your UI follow along with actions your own agents take - selecting items and switching spaces automatically when appropriate.

How it works

• When agents create/update items or spaces, the API emits lightweight presence hints (e.g., “select item”, “select space”).
• The web app listens for these hints and, when enabled, auto-selects the targeted item or navigates to the space.
• Presence events only apply to actions from your own user/agents - never other users.

Enable/disable

• Open Settings → Account → Presence and toggle “Enable agent presence”.
• Default is enabled; you can turn it off anytime.

Notes

• Hints are scoped - the UI only reacts when the event targets your current organization and space.
• Designed to be non-disruptive: it warms caches and updates selection without page reloads.