Onboarding (mcp-init / mcp-token)

1. Point at a registry

mcp-init needs a registry URL, pass --url, or set HANDOFF_CLOUD_URL / have it resolvable from an existing project config.

2. Run handoff-app mcp-init

handoff-app mcp-init --url https://your-registry.example.com

This is one-step onboarding:

• Signs you in if you aren't already, kicks off the device-code flow (opens a browser unless --browser=false).
• Fetches DESIGN.md from the registry and writes it to the project root.
• Writes/merges an handoff entry into .mcp.json:

{
  "mcpServers": {
    "handoff": {
      "type": "http",
      "url": "https://your-registry.example.com/api/mcp",
      "headers": { "Authorization": "Bearer ${HANDOFF_MCP_TOKEN}" }
    }
  }
}

• Upserts a managed "Design System" block into CLAUDE.md pointing your agent at DESIGN.md and the MCP server.

3. Set the token

By default the config references an env var (HANDOFF_MCP_TOKEN) rather than embedding the literal token, so .mcp.json is safe to commit:

export HANDOFF_MCP_TOKEN=$(handoff-app mcp-token)

Prefer a fully self-contained local config? Pass --embed to mcp-init instead, it writes the literal token into .mcp.json and adds that file to .gitignore for you. Don't commit an embedded-token config.

4. Restart your client

Restart Cursor / Claude Code / Claude Desktop so it picks up the new .mcp.json.

1. Add a custom connector

In claude.ai, add a custom connector pointing at your registry's MCP endpoint: https://your-registry.example.com/api/mcp.

2. Approve the OAuth prompt

claude.ai registers itself against /api/oauth/register, then redirects you through /api/oauth/authorize to approve access. No token ever needs to be copied manually.

3. Done

claude.ai stores and refreshes the resulting token itself.