QueryQuarry MCP Reference

QueryQuarry exposes a consent-based talent graph over the Model Context Protocol (MCP). Connect it to your AI assistant and search, evaluate, and reach out to candidates in natural language — the recruiter's AI is the intelligence; QueryQuarry is the corpus.

Connecting

QueryQuarry's MCP server lives at https://queryquarry.com/api/mcp. There are two ways to authenticate:

• OAuth — add QueryQuarry as a connector in an MCP-capable client (Claude, ChatGPT, etc.) and authorize it. Best for interactive use.
• API key — send an Authorization: Bearer qq_… header. Best for scripts and custom integrations. Generate and manage keys in your recruiter dashboard.

Either way you act as one recruiter account, with your subscription tier and limits applied server-side. To create an account, start at recruiter sign-up.

How it works

QueryQuarry is a double-blind escrow marketplace. Identities are revealed last, only by mutual, deliberate action:

1. Search the graph — you get anonymous match cards (no name, no contact).
2. Evaluate a promising card with a deeper, still-anonymous profile.
3. Request contact — you identify yourself; the candidate is notified.
4. The candidate decides. If they're interested, they reach out to you directly, quoting a one-time code so you know it's really them.

The candidate's name and contact details are never handed to you by the platform — they stay private until the candidate chooses to respond. That consent step is what keeps the corpus opt-in and spam-free.

Tools

Tool	What it does
search_candidates	Search the talent graph. Returns anonymous match cards — headline, skills, seniority, location, availability, salary range, and a snippet — but no name or contact. Filter by skills, location, remote, seniority, employment type, salary, experience, work authorization, relocation, and more. Paginated (max 25/page).
get_candidate	Evaluate one candidate in depth. Full skills, summary, seniority, experience (titles + what they did) and education — but still anonymous: no name or contact, and the candidate's name and contact details are scrubbed from the text. Metered (counts toward your reveal limit).
request_contact	Reach out to one candidate. You identify yourself (name + company, from your account) and add a short message; the candidate is notified and decides. If interested, they reach out to you and quote the returned code. Metered; requires a prior get_candidate; one active offer per candidate.
get_contact	Check the status of a contact request you sent: sent, accepted (they're interested — they'll reach out), or declined.
get_new_candidates	Resumes new or updated since a timestamp — your standing alert. Same filters as search.
save_candidate / get_watchlist	Save a candidate to your watchlist and review your saved list.
get_corpus_stats	Aggregate stats about the corpus — counts, top skills, top locations.
check_subscription	Your tier, status, rate limits, and usage this hour.

Search filters

search_candidates and get_new_candidates accept any combination of: skills (any-of, case-insensitive partial — "React" also matches "React 19"), location, remote_ok, seniority_levels, employment_types, work_location_types, work_authorization, open_to_relocation, experience_years_min / experience_years_max, salary_min / salary_max, availability, page, and limit.

Skills, seniority, employment type, and work-location values are normalized — plain terms and common variants resolve to the same match, so you don't have to guess exact spellings.

Rate limits

Two separate, generous limits protect candidates and reflect your plan:

• Reveals (get_candidate) — for evaluating candidates. Capped per seat to prevent bulk harvesting.
• Contacts (request_contact) — the metered, monetized action. Smaller per-seat caps, plus a per-candidate guard: one active offer at a time, a cooldown between offers, and blocked recruiters can't reach a candidate again.

Free accounts get a small allowance of each to try things out. Call check_subscription to see your current tier, caps, and usage.

Privacy & consent

Every profile in the corpus is explicitly opted in — never scraped. Candidates control their visibility and can delete their data anytime. The platform never exposes a candidate's name or contact to a recruiter; the candidate reveals themselves by responding. This is the contract that makes QueryQuarry a trusted place for both sides.