Plug Fairy into your AI agent.
The Fairy MCP server lets Claude, GPT-4, Gemini, Cursor, and any other MCP-compatible AI agent request human expert reviews inline — no context switching, no copy-paste, no manual uploads.
The human-in-the-loop API
fairy.resolve()
The moment your AI is unsure whether it can proceed, call one endpoint. Fairy finds the cheapest sufficient source of truth — memory, policy, another AI, an internal human, or a Fairy expert — and returns a decision. Most calls resolve without a human; the rest open a resolution you can poll.
curl -X POST https://askfairy.com/api/resolve \
-H "Authorization: Bearer fry_k_yourkey" \
-H "Content-Type: application/json" \
-d '{"question":"Is it safe to ship this auth token change?","artifact":"https://github.com/acme/api/pull/512"}'Returns
{
"decision": "review", // continue | review | stop
"source": "expert", // ai | memory | policy | human | expert
"confidence": 0.4,
"nextAction": "Routed to a Fairy expert for judgment. Poll this resolution for the verdict.",
"trackingUrl": "https://askfairy.com/cases/…"
}Same thing from an MCP client: call the fairy_resolve tool with the same arguments.
Connect directly to askfairy.com/api/mcp. No local install. Works from any MCP client that supports HTTP transport.
https://askfairy.com/api/mcpRun the MCP server locally via npx fairy-mcp. Your client starts it on demand — nothing to maintain.
npx fairy-mcpfairy_submitSubmit any URL for expert human verification — code diffs, contracts, model outputs, filings. Returns a reviewId.
params: url, scope, speed, context, domain, model, callback_url
fairy_statusPoll for the verdict, findings, and summary once the expert delivers.
params: review_id
fairy_listList your recent reviews and their current statuses.
params: limit
fairy_requestRequest a live screenshare or async expert review — a matched Fairy reaches out within 2 hours.
params: email, description, mode, domain, stakes
fairy_model_scoresQuery the AI model quality benchmark — scores by security, logic, readability, tests.
params: model, min_reviews
fairy_submit_codeSubmit raw file contents directly — no URL, no upload. The expert sees them in a syntax-highlighted code viewer. Returns a reviewId.
params: files, context, scope, speed, model, ai_client, callback_url
fairy_submit_logsPaste terminal output, build errors, or stack traces. A senior engineer diagnoses the root cause and tells you what to fix.
params: logs, context, scope, speed, model, ai_client, callback_url
fairy_estimatePreview the price and delivery time for a scope + speed combination before submitting.
params: scope, speed
Auto-submit on every task
Drop a CLAUDE.md in your project root. Claude Code reads it automatically and will call fairy_submit_code before marking security-sensitive tasks complete — no manual prompting needed.
Setup in 3 steps
Choose your connection method
Remote URL (recommended) — no install, works everywhere:
Claude Code (HTTP)
claude mcp add fairy --transport http \ --url https://askfairy.com/api/mcp \ -H "Authorization: Bearer fry_k_yourkey"
Claude Desktop (HTTP)
Edit ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"fairy": {
"type": "http",
"url": "https://askfairy.com/api/mcp",
"headers": {
"Authorization": "Bearer fry_k_yourkey"
}
}
}
}Local stdio — for clients that only support subprocess transport:
Claude Code (stdio)
claude mcp add fairy \ -e FAIRY_API_KEY=fry_k_yourkey \ -- npx fairy-mcp
Cursor / Windsurf / other stdio clients
{
"mcpServers": {
"fairy": {
"command": "npx",
"args": ["fairy-mcp"],
"env": {
"FAIRY_API_KEY": "fry_k_yourkey"
}
}
}
}OpenAI Agents & Responses API (GPT)
Add Fairy as a hosted MCP tool — your GPT agent calls it like any other tool. In ChatGPT, add the same URL as a custom connector.
{
"type": "mcp",
"server_label": "fairy",
"server_url": "https://askfairy.com/api/mcp",
"headers": { "Authorization": "Bearer fry_k_yourkey" }
}Gemini CLI
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"fairy": {
"command": "npx",
"args": ["fairy-mcp"],
"env": { "FAIRY_API_KEY": "fry_k_yourkey" }
}
}
}GitHub Copilot & any tool that opens PRs
No MCP needed. Install the Fairy GitHub App — when Copilot, Cursor, Claude Code, or Devin opens a pull request, comment @askfairy verify (or enable auto-review) and Fairy reviews it right in the PR.
Ask your agent to use Fairy
Once connected, your agent can use Fairy tools naturally. No special syntax needed.
Submit for expert review
"Get a Fairy expert to review https://github.com/acme/api/pull/512 — this is security-sensitive auth code, use instant speed"
Agent calls fairy_submit and returns a trackingUrl.
Connect with an expert
"Book a Fairy screenshare for me at alice@acme.com — I need a security engineer to review our payment integration"
Agent calls fairy_request. Expert reaches out within 2 hours.
Check review status
"Is the Fairy review for clx_abc123 done yet?"
Agent calls fairy_status and surfaces the verdict, findings, and summary inline.
Submit code inline — no URL needed
"I just wrote src/auth/middleware.ts and src/lib/jwt.ts. Submit them to a Fairy security expert before I ship"
Agent calls fairy_submit_code with raw file contents. The expert sees them in a native code viewer — no GitHub PR or upload required.
Diagnose a build error
"I'm getting a weird TypeScript error I can't figure out. Submit these build logs to a Fairy engineer"
Agent calls fairy_submit_logs with the raw output. Expert returns root cause + exact fix — usually within 30–60 minutes.
Compare AI tools
"How does Claude-generated code score vs GPT-4o on Fairy's benchmark?"
Agent calls fairy_model_scores and shows a ranked comparison across security, logic, readability, and test coverage.
Direct REST API
Prefer the REST API?
All tools map 1-to-1 to REST endpoints under /api/v1/. Authenticate with Authorization: Bearer fry_k_yourkey.
POST /api/v1/submit
POST /api/v1/submit-code
POST /api/v1/submit-logs
GET /api/v1/reviews/:id
GET /api/v1/reviews?limit=10
POST /api/v1/request
GET /api/v1/model-scores
GET /api/v1/estimate