@getabrain/mcp-server

MCP server for GetABrain.ai — give your AI agent real human judgment as native tools.

Use with Claude Desktop / Cursor

Add to your MCP client config (e.g. `claude_desktop_config.json`):

{
  "mcpServers": {
    "getabrain": {
      "command": "npx",
      "args": ["-y", "@getabrain/mcp-server"],
      "env": {
        "GETABRAIN_API_KEY": "gab_k_…",
        "GETABRAIN_API_SECRET": "gab_s_…"
      }
    }
  }
}

Get your API key by signing up at https://getabrain.ai.

Remote (hosted) MCP server -- no install

Prefer not to run anything locally? GetABrain also hosts this same server over Streamable HTTP at

`https://www.getabrain.ai/api/mcp`. Point any MCP client that supports remote servers at that URL and

pass your key pair as headers instead of env vars:

{
  "mcpServers": {
    "getabrain": {
      "url": "https://www.getabrain.ai/api/mcp",
      "headers": {
        "X-API-Key": "gab_k_…",
        "X-API-Secret": "gab_s_…"
      }
    }
  }
}

Same 7 tools, same schemas, same test-mode support -- see `docs/deploy/remote-mcp.md` in this repo for

details (Smithery-style clients, auth requirements, etc).

Test mode

Test mode is a flag on the key, not a different key format. When you mint an API key — via

`POST /api/v1/requestor/keys` with `{"mode":"test"}`, or by choosing "test" in the dashboard — you get

back a completely normal `gab_k_…` / `gab_s_…` key pair. There's no `_test_` in the string; the

test-ness lives in the database as an `is_test` flag on that key. No funding or card required.

Point `GETABRAIN_API_KEY` / `GETABRAIN_API_SECRET` at a test-mode key and the server behaves identically, except:

• `submit_query` never touches your balance — no charge, no `insufficient_balance` errors.
• Responses come back synthetic and are always marked `simulated: true`, so your pipeline (submit →

wait/poll → rate) can be built and exercised end-to-end before any real human worker or real money is

involved.

• `get_balance` reports `mode: "test"` so the agent/human can tell at a glance which environment it's in.

When you're ready to go live: mint a live-mode key (same call, `{"mode":"live"}` or the dashboard

default), fund the account with `create_topup_link` (works with either key type — a test-mode agent can

generate the link, a human completes checkout to add real funds), and swap the env vars. `get_balance`

then reports `mode: "live"`, and `submit_query` starts spending real balance and dispatching to real paid

workers.

Tools

• `get_balance` — read-only: prepaid balance (cents), `mode` (`"test"`/`"live"`), and `auto_reload_enabled`

(with a setup link + hint when it's off and would otherwise stall a live account at zero balance).

• `create_topup_link` — mints a Stripe Checkout URL to add funds (min $5); a human opens it in a browser to

pay — the agent cannot complete payment itself.

• `submit_query` — ask real humans a question (16 query types: A/B test, rating, ranking, sentiment, yes/no,

image/video/audio review, voice/video/photo capture, …). Returns a `query_id`. Spends balance on a live

key; free and `simulated: true` on a test key.

• `get_responses` — one-shot, read-only: current status + whatever responses exist right now, no waiting.
• `wait_for_responses` — bounded polling (up to `max_wait_seconds`, default/max 50s); returns `ready` with

responses once enough arrive, or `pending` — call again to keep waiting. Use this instead of `get_responses`

when you want the tool call itself to wait.

• `list_queries` — read-only: your recent queries, optionally filtered by `status`.
• `rate_response` — rate a worker's answer 1–5 (optional `feedback_text`); feeds the worker quality system.

Example agent flow

1. `get_balance` → confirm funds (or `mode: "test"` for a free sandbox run).

2. If funds are short on a live key: `create_topup_link` → human completes checkout → `get_balance` again.

3. `submit_query` → get `query_id`.

4. `wait_for_responses` (repeat while `pending`) → read the human (or simulated, in test mode) answers.

5. `rate_response` → optionally rate each response to improve future worker matching.

Full API docs: https://getabrain.ai/docs/api