mcpField
H
handoff-mcp-server

handoff-mcp-server

Remote
github.com/josephibraAI & Agents0Updated 24w ago
Repository

About handoff-mcp-server

handoff-mcp-server provides durable handoffs and a shared scratchpad for multi-agent workflows. It is an HTTP-based MCP server with configurable API-key authentication for tool calls.

Key features

  1. 01Durable agent-to-agent handoffs
  2. 02Shared workflow scratchpad
  3. 03HTTP transport for MCP
  4. 04Configurable tool-call authentication

Use cases

  1. 01Pass work between agents
  2. 02Share notes during multi-agent workflows

MCP support

It exposes handoff and scratchpad capabilities through an HTTP MCP endpoint at `/mcp`. Discovery methods may be public, while tool calls require valid authentication when an API key is configured.

Configuration

Remote servers need no local install. Pick your client, then copy the config or install in one click.

Endpointhttps://handoff-mcp-server-production.mcp.xpay.sh/mcp
Copy install command
Claude CodeTerminal
Cursor.cursor/mcp.json
VS Code.vscode/mcp.json
Claude Desktopclaude_desktop_config.json
Windsurf~/.codeium/windsurf/mcp_config.json

Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.

All endpoints
Streamable HTTPhttps://handoff-mcp-server-production.mcp.xpay.sh/mcp
Streamable HTTPhttps://handoff-mcp-server-production.up.railway.app/mcp

Tools

Details

From the project README

handoff-mcp-server

Durable handoffs and shared scratchpad for multi-agent workflows over MCP (HTTP transport).

Endpoints

  • GET / basic service info
  • GET /health health and storage stats
  • POST /mcp JSON-RPC MCP endpoint
  • GET /robots.txt discovery file
  • GET /llms.txt discovery file
  • GET /sitemap.xml discovery file

Environment Variables

  • PORT default 3000
  • DATA_DIR default /data
  • MCP_API_KEY required in production (NODE_ENV=production)
  • PUBLIC_MCP_DISCOVERY default true
  • PUBLIC_BASE_URL optional, used for absolute links in discovery files

Local Run

npm ci
npm run build
MCP_API_KEY=test-secret node dist/index.js

MCP Auth Behavior

  • Discovery methods (initialize, tools/list, resources/list, prompts/list, ping) can be public when PUBLIC_MCP_DISCOVERY=true.
  • tools/call requires valid upstream auth when MCP_API_KEY is set:
    • Authorization: Bearer <MCP_API_KEY> or
    • x-api-key: <MCP_API_KEY>

Xpay + Railway Configuration (Required)

  1. Railway variables:
  • MCP_API_KEY=<your-strong-key>
  • PUBLIC_MCP_DISCOVERY=true
  • PUBLIC_BASE_URL=https://handoff-mcp-server-production.up.railway.app
  1. Xpay MCP URL:
  • Use https://handoff-mcp-server-production.mcp.xpay.sh/mcp?key=xpay_sk_...
  • Without ?key=..., Xpay returns auth required and requests will not forward.
  1. Client calls through Xpay:
  • Keep the Xpay key in URL.
  • Also send upstream auth header for tools/call (x-api-key or Bearer token matching MCP_API_KEY).

Publishing

MCP Registry
  • Server name: io.github.josephibra/handoff-mcp-server
  • Primary remote: Xpay URL (with key at client usage time, not committed)
  • Secondary remote: Railway URL
Smithery
  • Namespace: josephibrahim
  • Server ID: handoff-mcp-server
  • MCP Server URL: https://handoff-mcp-server-production.mcp.xpay.sh/mcp?key=xpay_sk_...
Agentverse
  • Create a new agent and attach MCP server:
    • URL: https://handoff-mcp-server-production.mcp.xpay.sh/mcp?key=xpay_sk_...
    • Headers: x-api-key: <MCP_API_KEY> for tool execution paths

Recommended Extra Discovery Listings

  • PulseMCP directory
  • mcp.so
  • OpenTools catalog
  • MCPmarket / mcpservers.org

Use the same canonical MCP URL and matching auth notes everywhere to avoid inconsistent behavior.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.