Quickstart: Agents

From zero to a running Handler-powered agent in under 5 minutes. Pick your path below, connect via MCP or REST, and run your first mission.

1. Get a key

Two paths — choose one:

Either way, your key looks like sk-profile-... and goes in the Authorization header on every request.

2. Connect via MCP

Handler speaks the Model Context Protocol. Add it as an MCP server in your agent's config — it works with Claude Code, Cursor, and any MCP-compatible client.

Claude Code

Run this command from your terminal:

claude mcp add --transport http handler https://mcp.usehandler.dev/mcp \
  --header "Authorization: Bearer sk-profile-YOUR_KEY"

Or add it manually to your claude_desktop_config.json (Claude Desktop) or .claude/mcp.json (project-level):

{
  "mcpServers": {
    "handler": {
      "url": "https://mcp.usehandler.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk-profile-YOUR_KEY"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or the global Cursor settings):

{
  "mcpServers": {
    "handler": {
      "url": "https://mcp.usehandler.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk-profile-YOUR_KEY"
      }
    }
  }
}

Generic MCP JSON (any client)

{
  "mcpServers": {
    "handler": {
      "url": "https://mcp.usehandler.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk-profile-YOUR_KEY"
      }
    }
  }
}

Once connected, your agent gets 14 tools: 7 superpowers + 7 utilities. Call handler_status first — it is always free and confirms your key works, shows your balance, and lists every available tool.

3. Or raw REST

No MCP client? Call the API directly. Here is a web search via handler_research:

curl -X POST https://api.usehandler.dev/v2/superpowers/handler_research \
  -H "Authorization: Bearer sk-profile-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "search", "query": "AI agent frameworks 2026"}'

Response:

{
  "status": "executed",
  "result": { "results": [...] },
  "cost": { "charged": 0.005, "superpower": "handler_research", "task": "search" },
  "budget": { "remaining": 4.995, "calls_remaining": 999 }
}

All superpowers follow the same pattern: POST /v2/superpowers/:slug with a task field and any task-specific params.

4. First mission

Paste this prompt into your connected agent to put all the core superpowers through their paces:

This prompt exercises handler_research (web search), handler_monitor (social listening), and handler_skills — which surfaces the 68 built-in workflow recipes available to your profile, including the battlecard generator.

5. What happens when your agent needs approval

Some actions — typically writes to external services like email or CRM — are held for human review based on your org's governance rules. When that happens, Handler returns "status": "pending" instead of "executed". The call is logged in your dashboard's Activity view, and the owner is notified via their configured approval channel (dashboard, Slack, or email). Once a human approves, Handler retries the original call automatically — your agent does not need to resend anything.

What's next