HandoffKit Plugin Setup

Connect Claude Code to HandoffKit via MCP. Push session handoffs directly from your terminal — no copy-paste, no manual steps.

What This Does

HandoffKit exposes a remote MCP (Model Context Protocol) server at handoffkit.com/api/mcp. Once connected, Claude Code gains a push-handoff tool that sends your session's chat message directly to HandoffKit as a new cell. No curl commands, no JSON escaping — just a typed tool call.

The full handoff file stays local in your project. Only the concise copy-paste message is sent. Each project directory gets its own connection — NewsplanetAI pushes to your NewsplanetAI project, ShipMind pushes to ShipMind.

Prerequisites

• A HandoffKit account (free tier works)
• Claude Code installed

Quick Setup (Recommended)

Step 1: Install the Plugin

claude plugin add github:Norsninja/handoffkit-plugin

Step 2: Generate a Token

1. Go to handoffkit.com/settings
2. In the Plugin Integration section, select the project you want to link
3. Click Generate Token
4. Copy the token (starts with hk_setup_) — it expires in 10 minutes

Step 3: Run Setup

In your project directory in Claude Code, run:

/handoffkit:setup

Paste your token when prompted. The plugin exchanges it for an API key and configures the MCP connection automatically. Restart Claude Code and the push-handoff tool is available.

Manual Setup (Without Plugin)

If you prefer not to install the plugin, you can set up the MCP connection manually:

1. Exchange your token

curl -s -X POST https://handoffkit.com/api/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"setup_token": "hk_setup_YOUR_TOKEN_HERE"}'

2. Add the MCP connection

Copy the api_key from the response and run:

claude mcp add handoffkit \
  --transport http \
  --scope local \
  --header "Authorization: Bearer hk_key_YOUR_KEY_HERE" \
  -- https://handoffkit.com/api/mcp

Restart Claude Code and the push-handoff tool is available. Your API key is stored securely by Claude Code — not in any project file, not in git.

Usage

Once connected, you have two ways to push handoffs:

Automatic (recommended)

Add a push step to your /handoff command. When the handoff is generated, the AI uses the push-handoff MCP tool to send the chat message to HandoffKit automatically. The handoff file and chat message are created first — the push is the final step.

Manual

Ask Claude Code to push content anytime: "push this to HandoffKit" or "save this as a cell in HandoffKit." The AI will use the MCP tool directly.

Either way, you'll see a confirmation:

Handoff pushed to HandoffKit.
Project: NewsplanetAI
Cell: Session Handoff - 2026-04-11
View at: handoffkit.com/projects

Multiple Projects

Each project directory gets its own MCP connection with its own API key. Run the setup in each project directory:

1. Generate a token for that HandoffKit project (from Settings)
2. Exchange it for an API key
3. Run claude mcp add in that project's directory

When you switch between project directories in Claude Code, the correct HandoffKit project is automatically selected.

Managing API Keys

View and manage your API keys at handoffkit.com/settings under API Keys.

• Revoke a key — immediately disconnects the linked project. Click the trash icon next to the key.
• Re-link a project — generate a new setup token, exchange it, and run claude mcp add again.
• Remove the MCP connection — run claude mcp remove handoffkit in the project directory.

Troubleshooting

Token expired

Setup tokens expire after 10 minutes. Generate a new one from Settings.

API key rejected (401)

The key may have been revoked. Run claude mcp remove handoffkit, generate a new token, exchange it, and re-add the MCP connection.

Wrong project (403)

Each API key is scoped to one project. If you need to push to a different HandoffKit project, set up a new connection in that project's directory.

MCP tool not showing up

Restart Claude Code after running claude mcp add. Check that the server appears in /mcp. If not, verify the command ran in the correct project directory.

Push failed but handoff is fine

The push is a convenience — your local handoff file and chat message are always created first. If the push fails, you can copy the chat message manually into HandoffKit.

Security

• Setup tokens are single-use and expire in 10 minutes
• API keys are scoped to one project — they can't access other projects
• Keys are stored by Claude Code in ~/.claude.json, not in project files
• MCP connections use --scope local — per-project, not global
• All communication is HTTPS
• Keys can be revoked instantly from Settings
• Only the chat message is sent — full handoff files stay local

How It Works Under the Hood

HandoffKit runs a remote MCP server at handoffkit.com/api/mcp that speaks the Model Context Protocol. When Claude Code calls the push-handoff tool, it sends a JSON-RPC request with your title and content. The server authenticates your API key, checks your quota, creates the cell, and returns a confirmation. No intermediate scripts, no shell commands, no JSON escaping.