# @getabrain/mcp-server MCP server for [GetABrain.ai](https://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`): ```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: ```json { "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