50heads
Sign inGet the app
Language
For agents and developers

A human judgment, one tool call away.

Your agent can ask fifty verified people and get a distribution back in about ten minutes, from 12p an answer. The 50heads MCP server works with Claude, Cursor, ChatGPT and anything that speaks MCP.

Add it to your host

Claude

In Claude, open Settings, then Connectors, and add a custom connector with this URL. You'll sign in and set a daily spend cap.

https://mcp.50heads.com/mcp

Claude Code

Run this in a terminal. Claude Code opens a browser for you to sign in and set a daily spend cap.

claude mcp add --transport http 50heads https://mcp.50heads.com/mcp

Cursor

Add this to ~/.cursor/mcp.json, then sign in when Cursor asks.

{
  "mcpServers": {
    "50heads": {
      "url": "https://mcp.50heads.com/mcp"
    }
  }
}

ChatGPT

In ChatGPT, open Settings, then Apps and connectors, then Advanced settings, and turn on Developer mode. Choose Create, paste this URL and pick OAuth.

https://mcp.50heads.com/mcp

VS Code

Add this to .vscode/mcp.json in your workspace, or run MCP: Add Server. VS Code opens the sign-in page.

{
  "servers": {
    "50heads": {
      "type": "http",
      "url": "https://mcp.50heads.com/mcp"
    }
  }
}

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json, with an API key from the portal.

{
  "mcpServers": {
    "50heads": {
      "command": "npx",
      "args": [
        "-y",
        "@50heads/mcp"
      ],
      "env": {
        "FIFTYHEADS_API_KEY": "fh_live_…"
      }
    }
  }
}

Other (npx)

For hosts that launch a local command. Needs Node 20 or later and an API key from the portal.

FIFTYHEADS_API_KEY=fh_live_… npx -y @50heads/mcp

Three calls

Estimate is free and never spends. Ask reserves the credits. Waiting happens on our side, so your agent makes one call instead of polling.

> estimate({ type: "single_choice", text: "Which menu would you order from tonight?",
             options: [{ label: "Menu A" }, { label: "Menu B" }], n: 50, tier: 1 })
  12 credits × 50 = £6.00 · eta 10 min

> ask({ ...same question, idempotency_key: "4f9c…" })
  task q_8k2f · working · 0 of 50 answered

> get_results("q_8k2f")        # or wait_for_results on older hosts
  complete · winner "Menu B" · margin 36 points · confidence high

Tools

estimate
Price, time and validation for a question. Never spends.
ask
Posts a question. Needs an idempotency key, so a retry is never a second ask.
get_results
The results so far, without waiting.
wait_for_results
Waits on our side until the question is answered.
list_questions
Recent questions, so an agent can reuse a result before re-asking.
cancel
Stops a live question and refunds the answers not given.
templates
Fixed-price question templates.
balance
Credits, and what's left under the connection's daily cap.

Safe to leave running

  • Every connection has a daily spend cap, £50 unless you change it. An agent can't spend past it.
  • Ask needs an idempotency key. The same key returns the same question.
  • Questions pass the same content rules as everyone else's. A refused question costs nothing.
  • Results never identify a head.

Or call the API

Everything the MCP server does is a plain HTTPS call. Keys start fh_live_ and are shown once.

curl https://api.50heads.com/v1/billing/estimate \
  -H "Content-Type: application/json" \
  -d '{"draft":{"type":"single_choice","text":"Which menu would you order from tonight?",
       "options":[{"label":"Menu A"},{"label":"Menu B"}],"n":50,"tier":1}}'

curl https://api.50heads.com/v2/questions \
  -H "Authorization: Bearer $FIFTYHEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"draft":{"type":"single_choice","text":"Which menu would you order from tonight?",
       "options":[{"label":"Menu A"},{"label":"Menu B"}],"n":50,"tier":1,"language":"en"}}'

curl "https://api.50heads.com/v2/questions/q_8k2f/wait?seconds=25" \
  -H "Authorization: Bearer $FIFTYHEADS_API_KEY"

A human judgment, one tool call away.

API docsMCP setupWebhooks