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 related items using semantic relationships, including custom types.

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

Organize items in a parent-child hierarchy, then add semantic relationships to connect related ideas across that structure.

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. Use MCP tools to read and update spaces, items, relationships, and supported agent features.

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 four ways to retrieve context from Handoff into an AI chat or agent: the copy button in Handoff Studio UI, MCP tools, MCP resources, and the REST API.

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 in the organization selected during connection.

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

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

3. MCP Resources

Each accessible space is exposed as an MCP resource containing a navigation index. Clients that support resources can attach this map when starting a chat.

• Choose a space from your client’s resource list. Resource URIs use the format space://slug
• The index contains item names, IDs, hierarchy, and semantic relationships.
• Item bodies are loaded separately. Use items with op="get" and includeResource=true to read an item’s content.

4. REST API

For programmatic access outside of MCP, use the Handoff REST API with an organization API key. Create API keys in Settings > API Keys, then authenticate requests with a Bearer token header.

• Full CRUD access to spaces, items, and edges
• Bulk and batch operations for creating or updating multiple items
• Markdown pack export for rendering item trees as documents
• Commit history and revert operations (plan permitting)

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 a map of a space to guide context retrieval in a new conversation
• REST API - When building custom integrations, scripts, or pipelines that need direct programmatic access

Next Steps

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

1) Get connected

• Choose your client under Connect Agents: ChatGPT, Codex, Claude, Cursor, Gemini CLI, or another compatible MCP client. Follow its guide to add Handoff and start OAuth sign-in.
• Sign in to Handoff, choose your organization, and approve the requested access if prompted. Return to your client and enable Handoff.

Use Handoff to list my spaces.

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

• Organize items with parent-child hierarchy and connect related items with semantic relationships, including custom relationship types.
• 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.
• Use agent presence to see ongoing work and history to review changes.

ChatGPT Setup

Connect Handoff as a custom MCP plugin in ChatGPT on the web.

1. Add Handoff

1. In Plugins, use the plus button and choose Add custom MCP server.
2. Name it Handoff and add a description, such as “Shared context, spaces, and tasks.”
3. For the connection, enter this public MCP server URL:

https://mcp.handoff.computer/mcp

2. Sign in

1. Choose OAuth authentication. Handoff supports automatic client registration, so leave optional client ID and secret fields blank.
2. Review ChatGPT’s notice and create the plugin. When prompted, sign in to Handoff, select your organization, and approve the connection.
3. Install the resulting plugin and check that its tools are available.

3. Use it in chat

Start a new conversation, type @, and select Handoff.

Use Handoff to list my spaces.

If setup is unavailable

• Check Developer mode under Settings → Security and login. Access depends on your account and workspace policy; a workspace admin may need to enable custom MCP servers.
• If Handoff’s tools change, open its connection in Plugins, refresh it, and start a new conversation.

Official guide: Connect an MCP server in ChatGPT

Codex Setup

Connect through the desktop app, CLI, or IDE extension. They share MCP configuration on the same machine.

Desktop app or IDE extension

1. Open Settings → MCP servers in the app, or MCP servers from the extension’s gear menu.
2. Add a server named handoff, choose Streamable HTTP, and enter:

https://mcp.handoff.computer/mcp

Save and restart when prompted, then select Authenticate. Sign in to Handoff, select your organization, and approve the connection.

CLI alternative

Add the server and complete browser sign-in:

codex mcp add handoff --url https://mcp.handoff.computer/mcp
codex mcp login handoff

Check configuration with codex mcp list. In a new Codex chat, use /mcp to check that Handoff is connected.

Manual configuration

Alternatively, merge this table into ~/.codex/config.toml, or .codex/config.toml for a trusted project:

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

Then run codex mcp login handoff. Remove the obsolete rmcp_client setting from older configurations.

Use Handoff to list my spaces.

Official guide: Codex MCP configuration and authentication

Connect Claude

Connect Handoff over remote MCP with Streamable HTTP. Sign in to Handoff through the browser when prompted to authorize access.

Claude web and Desktop

1. Open Customize → Connectors, then choose + Add → Add custom connector.
2. Name it Handoff and paste this remote MCP server URL:

https://mcp.handoff.computer/mcp

3. Use OAuth and choose Register automatically if asked how to identify the client. Sign in to Handoff, choose your organization, and approve the requested access if prompted.
4. In a conversation, open + → Connectors and enable Handoff.

For managed Claude organizations, an owner or administrator with connector permissions adds Handoff through Organization settings → Connectors. Each member then connects their own Handoff account.

Official Claude connector instructions

Claude Code

Run this in your terminal to make Handoff available across your projects:

claude mcp add --transport http --scope user handoff https://mcp.handoff.computer/mcp

For personal access in just the current project, use --scope local. Use --scope project to save shared project configuration in .mcp.json.

1. Start Claude Code, run /mcp, select Handoff, and complete its browser sign-in.
2. Check /mcp for Handoff’s connection status and tools. If disabled, enable it there.

Official Claude Code MCP instructions

Use Handoff to list my spaces.

Connect Cursor

Open Handoff’s configuration in Cursor, approve the installation, then sign in to Handoff.

1. Use Add to Cursor and allow your browser to open Cursor. Review the Handoff configuration and confirm installation.
2. In Cursor’s Customize sidebar, find Handoff and follow its OAuth sign-in prompt. Choose your Handoff organization and approve the requested access if prompted.
3. Enable Handoff if it is disabled, then check Available Tools in Agent chat.

Use Handoff to list my spaces.

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

Official Cursor MCP instructions · MCP install links

Connect Gemini CLI

Connect Handoff to Gemini CLI with Streamable HTTP and OAuth sign-in.

1. Add the server

Run this in your terminal to use Handoff across your projects:

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

This saves to ~/.gemini/settings.json. For just the current project, use --scope project to save to .gemini/settings.json instead.

2. Sign in to Handoff

Start Gemini CLI with gemini, then enter this command inside the session:

/mcp auth handoff

Sign in to Handoff, choose your organization, and approve the requested access if prompted. Run this from a machine with a browser for the OAuth callback.

3. Check the connection

• Run /mcp list in the session to check Handoff’s status and tools.
• If disabled, run /mcp enable handoff.

Use Handoff to list my spaces.

Official Gemini CLI MCP instructions

Connect another MCP client

Use a client that supports remote Streamable HTTP and browser-based OAuth sign-in. Configuration keys differ between clients; follow your client’s remote MCP instructions with these settings.

Connection settings

https://mcp.handoff.computer/mcp

Name

Handoff

Transport

Streamable HTTP

Authentication

OAuth

Client registration

Automatic (dynamic registration)

Leave optional client ID, client secret, and scope fields blank. Sign in to Handoff, choose your organization, and approve the requested access if prompted. Return to the client and enable Handoff.

Use Handoff to list my spaces.

If your client asks for more details

OAuth discovery supplies the authorization and token endpoints. If an explicit scope list is required, use:

openid profile email offline_access mcp

The mcp scope is required; offline_accessallows the client to refresh the connection. If asked for a resource or audience, use the full MCP URL above, including /mcp.

Troubleshooting

• Use the exact URL above. The legacy SSE transport and /sse endpoint aren’t supported.
• If the client only accepts an API key, use an OAuth-capable client. Handoff’s organization REST API keys don’t authenticate MCP connections.
• If sign-in expires or tools stop loading, reconnect and complete the browser authorization again.

Tools

Current Handoff MCP tools available in supported hosts. For starting context, attach a space resource or point the model at the relevant space before using tools.

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".

Agent Presence

Presence shows where your agents and connected MCP clients are working without taking control of your workspace.

How it works

• The graph shows lightweight, content-free activity such as reading, creating, moving, or linking items.
• A passive avatar dock shows agents assigned to the current space. Active operators appear as colored cursors beside the items they touch.
• Presence is visible only to the owner. It never exposes prompts, resources, tool arguments, or results.

Enable/disable

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

Notes

• Collapsed targets stay collapsed. Activity attaches to the nearest visible ancestor without expanding the graph.
• Passive presence never changes your route, item selection, or graph expansion.