MCP server

One hosted, stateless Streamable HTTP endpoint for every host, with OAuth 2.1, plus a small npx wrapper for hosts that only run local servers.

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

Hosted: add the endpoint and sign in with OAuth in the browser. Nothing to install, and you set the connection's daily spend cap when you sign in. Local: npx -y @50heads/mcp runs the same tools over stdio for hosts that launch a command. It needs Node 20 or later and an API key from Developers in the portal, or a one-time npx -y @50heads/mcp login.

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

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

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

claude mcp add --transport http 50heads https://mcp.50heads.com/mcp --header "Authorization: Bearer fh_live_…"

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

{
  "mcpServers": {
    "50heads": {
      "url": "https://mcp.50heads.com/mcp",
      "headers": {
        "Authorization": "Bearer fh_live_…"
      }
    }
  }
}

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

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

code --add-mcp '{"name":"50heads","type":"http","url":"https://mcp.50heads.com/mcp"}'

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

{
  "mcpServers": {
    "50heads": {
      "serverUrl": "https://mcp.50heads.com/mcp",
      "headers": {
        "Authorization": "Bearer fh_live_…"
      }
    }
  }
}

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

{
  "mcpServers": {
    "50heads": {
      "url": "https://mcp.50heads.com/mcp",
      "headers": {
        "Authorization": "Bearer fh_live_…"
      }
    }
  }
}

npx -y @50heads/mcp config [host] prints any of these. To check it works, ask your host to use 50heads to estimate a question: an estimate is free and never spends credits.

Where to find 50heads

Until a directory listing is live, add the hosted server yourself with the instructions above. Releases use calendar versions (2026.924.1 is the first release on 24 September 2026); the hosted server, the npm package and the registry entry carry the same one.

We don't use your questions, the answers you buy or the reasons heads write to train AI models, and we don't sell them. More in AI and your data and the privacy policy.

OAuth

The server is an OAuth 2.1 resource server. Hosts discover everything from https://mcp.50heads.com/.well-known/oauth-protected-resource, which points at the authorization server https://auth.50heads.com. PKCE (S256) and the resource parameter are required; dynamic client registration and client ID metadata documents are both supported. Access tokens last an hour; refresh tokens rotate and last 30 days.

At consent the person picks scopes and a daily spend cap for the connection (5,000 credits unless they change it). They can change or revoke it any time under Developers in the portal; a revoked connection stops within a second.

Scopes

questions:read, questions:write, templates:read, account:read, webhooks:read, webhooks:write, apps:read, apps:write, organization:read, organization:write, members:read, members:write, audit:read, events:read. A call that needs a scope the token lacks returns insufficient_scope so the host can ask for it.

What an agent can do

The server lists its tools to the host when it connects (tools/list), with a description and a schema for each, so a host never needs this page to know them. The package README names every tool and its parameters, and is the place to look: github.com/50heads/mcp, also shown on npm. Tool names can change between releases, so read them from the server or the README rather than from here.

Nothing here changes an organization, a key or single sign-on: those stay with a person (see Authentication). Asking tools need an idempotency_key, so a retry never asks or charges twice.

Pre-filled ask links

https://50heads.com/app/ask?… opens the composer with a question filled in, for a person to check the price and time and ask. The server can write these for an agent; you can write them by hand too. Nothing is asked until the person presses Ask. The composer fills itself only when the link has text or at least one optionLabel.

Errors

JSON-RPC errors carry error.data.code: validation and not_found as −32602; insufficient_credits, spend_cap_exceeded (the API's spend_cap_reached), idempotency_conflict and content_refused as −32001; rate_limited and unavailable as −32000. Every message is one sentence a model can act on.

Limits

1 MB request bodies. Images by URL or upload only, never large inline base64. 60 requests a minute per connection and 10 asks a minute.