Use 50heads from an AI assistant.
Connect 50heads to a compatible AI assistant so it can ask real people a question and receive the result. It takes about ten minutes to set up and costs from $0.25 per answer. It works through MCP, the standard that lets an assistant use outside tools, so it runs in Claude, Cursor, ChatGPT and any host that supports 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/mcpClaude 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/mcpCursor
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/mcpVS 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/mcpThe basic flow is three steps
Estimate is free and never spends. Ask reserves the credits. Wait for results: 50heads holds the wait, so your assistant makes one call instead of checking again and again.
> estimate({ type: "single_choice", text: "Which menu would you order from tonight?",
options: [{ label: "Menu A" }, { label: "Menu B" }], n: 50, tier: 1 })
20 credits × 50 = 1000 credits · 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 highAvailable tools
estimate- Price, time and validation for a question. Never spends.
ask- Posts a question. Needs an idempotency key: retrying with the same key cannot create a second question or a second charge.
get_results- The results so far, without waiting.
wait_for_results- Waits on our side until the question is answered, so the client does not have to keep checking.
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.
Controls for unattended use
- Every connection has a daily spend cap, 5,000 credits unless you change it. The server refuses an ask that would go over it.
- Ask needs an idempotency key. Retrying with the same key cannot create a second question or a second charge.
- 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"