MCP server

handoff-it exposes an MCP (Model Context Protocol) server so AIs can recall project context and save checkpoints directly, inside the conversation. Streamable HTTP transport with OAuth 2.1 or API-key authentication.

Connection

Endpoint	`https://handoff-it.com/mcp`
Transport	Streamable HTTP (spec 2025-03-26+)
Auth	Header `Authorization: Bearer hof_…` — create the key at Dashboard → API & MCP — or OAuth 2.1 (ChatGPT/Claude.ai: automatic, no key)

Setup per tool

Claude Code / Cowork plugindocs ↗

The handoff-it plugin bundles the remote MCP connector and the setup/checkpoint/recall skills. After it is approved in the community directory, install it from Claude Code or Cowork and run /handoff-it:setup. OAuth opens in the browser; never paste an API key into chat.

# After community-directory approval
/plugin install handoff-it@claude-plugins-community
/handoff-it:setup

# Local repository test
claude --plugin-dir ./handoff-it-skill

Claude Desktop / claude.ai (custom connector)docs ↗

URL: https://handoff-it.com/mcp
Authentication: OAuth 2.1 (browser)

ChatGPT plugin / Developer Modedocs ↗

After directory approval, find handoff-it under Plugins. For development, use Settings → Connectors → Advanced → Developer mode → Create and paste the endpoint URL above. No key is needed: ChatGPT self-registers and signs in via OAuth 2.1; you approve it once on a consent screen. Manage or revoke the connection later in Dashboard → API & MCP → Connected apps. Claude.ai's custom connector also works with just the URL (OAuth) if you skip the header.

https://handoff-it.com/mcp

Cursor / VS Code (mcp.json)docs ↗docs ↗

{
  "mcpServers": {
    "handoff-it": {
      "url": "https://handoff-it.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Gemini CLIdocs ↗

~/.gemini/settings.json

{
  "mcpServers": {
    "handoff-it": {
      "httpUrl": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Windsurfdocs ↗

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "handoff-it": {
      "serverUrl": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Cline (VS Code)docs ↗

cline_mcp_settings.json

{
  "mcpServers": {
    "handoff-it": {
      "type": "streamableHttp",
      "url": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

JetBrains AI Assistantdocs ↗

Settings → Tools → AI Assistant → MCP → Add

{
  "mcpServers": {
    "handoff-it": {
      "url": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Zeddocs ↗

settings.json (bridge via mcp-remote)

{
  "context_servers": {
    "handoff-it": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://handoff-it.com/mcp",
          "--header",
          "Authorization: Bearer YOUR_KEY"
        ]
      }
    }
  }
}

OpenCodedocs ↗

opencode.json

{
  "mcp": {
    "handoff-it": {
      "type": "remote",
      "url": "https://handoff-it.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Kirodocs ↗

.kiro/settings/mcp.json

{
  "mcpServers": {
    "handoff-it": {
      "url": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Traedocs ↗

.trae/mcp.json

{
  "mcpServers": {
    "handoff-it": {
      "url": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Replit (Agent)docs ↗

Settings → MCP Servers (UI)

+ Add MCP server → URL: https://handoff-it.com/mcp
Advanced → Header: Authorization = Bearer YOUR_KEY

ZCode (Z.ai)docs ↗

MCP Servers page (UI) — or import your Claude Code config

{
  "mcpServers": {
    "handoff-it": {
      "url": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

GitHub Copilot (coding agent)docs ↗

Repo → Settings → Copilot → Coding agent → MCP

{
  "mcpServers": {
    "handoff-it": {
      "type": "http",
      "url": "https://handoff-it.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Tools like Lovable, Base44, Bolt and Bubble are app builders that expose their ownMCP servers (you connect Claude/Cursor to them) — they can't consume external MCP servers like handoff-it yet.

OAuth and revocation

Browser-based clients use Authorization Code + PKCE and refresh tokens. Authorization lets the app read your projects and conversations and save memories. Revoke a client at any time under Dashboard → API & MCP → Connected apps; access stops immediately.

Available tools

Tool	Description	Parameters
`recall_project`	The headline tool: returns the project's distilled context — checkpoints (full content, pinned first), note excerpts, recent sessions and drill-down pointers. Call it FIRST when resuming work.	`project` · Project name, git origin URL or working-directory path
`list_projects`	Lists every project with session/memory counts and last activity.	—
`list_sessions`	Lists archived conversations, newest first; filter by project or tool.	`projectId`? · Filter by project `tool`? · claude_code \| codex \| cursor \| copilot `limit`? · Page size `cursor`? · From the previous page
`get_session_messages`	Pages through one archived conversation by srcOffset. direction 'older' (default) starts from the end; pass fromOffset from a previous page or a search hit.	`sessionId` · Session id `fromOffset`? · Continue from this offset `direction`? · older \| newer `limit`? · Page size
`search_memories`	Searches saved memories (notes and checkpoints) by text, tag, kind or project.	`query`? · Text to match `tag`? · Filter by tag `projectId`? · Filter by project `kind`? · note \| checkpoint
`search_conversations`	Full-text search across every archived conversation. Hits carry {sessionId, srcOffset} — open the surrounding context with get_session_messages.	`query` · Search terms `projectId`? · Filter by project `tool`? · Filter by tool
`save_memory`	The single write tool. kind 'checkpoint' = distilled work state (what recall_project serves back): keep it under ~2 KB with state, decisions, pending work and pointers. NEVER include secrets.	`title` · Milestone name `content` · The memory body `kind`? · note (default) \| checkpoint `projectId`? · Provenance project `tags`? · Labels `pinned`? · Survives later checkpoints

Typical flow

A common conversation between a user and an AI connected to handoff-it:

You:  "Pick up the handoff-it project — where did we stop?"
AI:   → recall_project("handoff-it")
      ← 3 checkpoints · 5 notes · 12 sessions
      … continues the work with full context …
      → save_memory(kind: "checkpoint", title: "Webhook fixed")
AI:   "Done — webhook fixed, checkpoint saved for the next session."

When the distilled answer is not enough, search_conversations finds the exact moment and get_session_messages opens the surrounding transcript.

Errors

Without the authorization header the server responds 401. Business errors (storage limit reached, project not found) come back as tool results with isError: true and a message explaining what to do:

quota_exceeded: Storage limit exceeded on the Free plan — archive less or upgrade.