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 accept, their intro lands in your email — their contact, their message, and a one-time code so you know it's really them. Reply directly and you're talking.

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 (with skills_matched showing which of your terms each card hit), 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. With skills, results default to skill_match order (ties by recency); sort: "recency" opts out. 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 they accept, their intro arrives in your account email with their contact and 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 (returns shared_contact — what they chose to share — and whether their intro was emailed to you), or declined. Also shows any hire outcome either side reported.
report_contact_outcome	One-tap outcome on an accepted contact: hired, not_hired, or in_progress. Optional but appreciated — it's how the marketplace measures that consented outreach beats cold outreach.
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.
get_docs	This reference — how it works, all tools and filters, search tips, rate limits, and privacy.

Search filters

search_candidates and get_new_candidates accept any combination of: skills (any-of, case-insensitive partial — "React" also matches "React 19"), location + radius_miles, 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, sort ("skill_match" — the default when skills are present — or "recency"), 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.

Searching well

Every filter is a hard requirement — they're combined with AND, so each one you add narrows the pool. Stack too many and a strong-but-imperfect candidate (open to hybrid, one town over, a year light on experience) silently drops out.

The API filters; your AI ranks. You'll get the best results by filtering only on true dealbreakers — must-have skills, hybrid vs. remote, work authorization — then letting your AI weigh the softer preferences (exact location, salary, years) across the cards that come back. When you pass skills, results default to skill_match order — candidates matching more of your stated skills first, ties by recency — and each card's skills_matched shows which terms hit; pass sort: "recency" for pure recency (searches without skills are always recency-ordered). That's arithmetic over your own criteria, not a fit score: the platform never judges who is better; that stays with your AI. Cast a slightly wider net and judge the matches yourself rather than encoding every preference as a filter.

Location: pass a city with its state ("Schaumburg, IL") or a 5-digit zip code ("60133" — the most precise option, and it works for tiny towns not in the city gazetteer) plus radius_miles (5, 10, 25, 50 — max 100). The query geocodes against a US places gazetteer and returns every candidate within the radius, so nearby suburbs are included and lookalike names ("West Chicago" for "Chicago") are excluded. Ambiguous names without a state resolve to the most populous match — "Springfield" alone means the biggest Springfield, so include the state. The response echoes location.resolved and location.mode ("radius" or "text") so you can confirm what was actually searched; free-text that doesn't geocode falls back to substring matching. Location data from GeoNames (CC BY 4.0).

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: only one active offer to the same candidate at a time, a cooldown between offers to that candidate, and blocked recruiters can't reach a candidate again. (You can have offers out to many different candidates at once.)

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.