MCP Reference

What a connected agent sees, once setup is done. The server speaks the 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25 revisions of the protocol.

Tools

• hyreflow_tools_search: find tools by intent ("find software engineers", "verify emails"). The usual entry point. Names a matching recipe in its recipes field.

• hyreflow_tools_describe: input contract and exact credit cost before running. Argument-priced methods quote a worst case, not a base price. Also reports a side_effect flag per method, so an agent can tell a reversible lookup from a write to your ATS.

• hyreflow_tools_execute: run it. Waterfall sourcing like people search runs exactly as the CLI does it: house provider order, dedup, BYOK skips. An enrichment waterfall (email_enrichment, personal_email, linkedin_profile) also takes rows (up to 100 row objects) instead of payload to enrich many people in one call: the chain runs stage by stage and a provider that accepts a batch (FullEnrich) gets one job for every pending row, billed per row. rows is exclusive with payload and method. A step that is still running when the poll budget ends reports still_enriching with job_id and a resume object (tool, method, id_arg), and ends that row's chain there — no further provider runs for it. The job settles on its own server-side and bills once when it finishes; resume it sooner with a poll (free while the job runs; a finished job bills only the rows it revealed, once) rather than resending the row, which would start and bill a second job:

  {"tool":"email_enrichment","rows":[{"first_name":"Jane","last_name":"Doe","company_domain":"acme.example.com"}]}

  Pass those arguments to hyreflow_tools_execute. Use personal_email instead for candidates.

  {"tool": "<resume.tool>", "method": "<resume.method>", "payload": {"<resume.id_arg>": "<job_id>"}}

• hyreflow_workflows_list / hyreflow_workflow_run / hyreflow_workflow_runs: list this workspace's saved workflows, run one by the name or id that list returns, poll the run id it gives back. To drive it from a prompt:

  Run my "<workflow name>" workflow through hyreflow and tell me when it finishes, with the total credits spent.

• hyreflow_enrich_run: generic ordered, per-column enrichment over rows. Its steps execute per row; use hyreflow_tools_execute with an enrichment waterfall plus rows when you want provider-level batching. It polls each async step against a short in-request budget so the call returns well under a minute; a step still running when that budget ends comes back still_enriching with its job_id. Fetch that row later with hyreflow_enrich_job {provider, job_id}, which returns the same settled shape as GET /enrich/jobs/{provider}/{job_id} (status pending/settled/failed/expired, plus charged, email, result once settled) — free while pending, billed once on the poll that finds it settled.

• hyreflow_billing_balance: check spend.

• hyreflow_onet_lookup: job title → O*NET-SOC codes. Free, and needed before job-openings discovery, which takes codes rather than titles. "Head of Talent Acquisition" resolves by dropping the seniority prefix; each result carries the official title and description so a loose match can be checked.

• hyreflow_feedback: send feedback or a bug report, returns the filed issue's URL. Free. The session is attached so we can see the run that prompted it. Your client will ask before sending: it reaches real people.

Every result reports the credits it charged in _meta.

Tools that only read are marked read-only, so a client that groups tools by permission can auto-approve the safe set: catalog search, playbook reading, run status, balance. Anything that spends credits or writes to a connected system stays outside that group and keeps asking: hyreflow_tools_execute, hyreflow_enrich_run, and any workflow run.

The playbooks come with it

An MCP client installs nothing, so the agent skills are served over the connection instead, in full: the recruiting playbook, a playbook per provider covering access rules, payload shapes and cost traps, the pipeline recipes, and the sub-agent prompts.

Reading a provider's playbook before executing that provider's tool is the difference between a call that works and one that burns credits on a malformed payload. Three things point at the right one: hyreflow_tools_search names a recipe, hyreflow_tools_describe names a provider playbook, and every hyreflow_tools_execute result carries the same pointer in _meta.playbook.

Connecting also hands the agent the routing table: the index mapping a task ("a job description → a shortlist", "a company just raised") to the document that covers it, so it knows which playbook to open before reading anything.

They arrive two ways, and every client supports at least one:

• as MCP resources, addressed hyreflow://skills/<skill>/<path>: clients that show resources let you attach one to a conversation directly.
• as tools: hyreflow_skills_list (every skill and document), hyreflow_skill_read (one document in full: a skill name alone returns its SKILL.md, or add a path like provider-playbooks/apollo.md), hyreflow_skill_search (find a document by term; searching a provider name is the fastest route to its playbook).

Billing

Tool calls bill identically on every surface: MCP, CLI, or API. A connected client counts as one session, so per-session spend caps cover everything it does, and every charge lands on the approved workspace's balance. See pricing.

Run recording

A run trace records Hyreflow tool inputs and outputs, provider, timing, outcome, and client information when available, grouped per connection within your workspace. The tools that spend credits require a user_prompt: the request that drove the call, which your agent sends so a trace reads as your ask followed by the tools it drove. Your surrounding conversation is not captured. Traces carry workspace and user identifiers and account email for support attribution. Recognized contact fields and recognizable email addresses, profile links, and phone numbers are filtered from trace payloads; free-form text is not fully anonymized. Recording never changes results or billing.

Recording is on by default. A workspace can also be set to always record or never record, and where it is set it takes precedence over anything a client sends. Ask us what your workspace is set to, or to change it.

A client that lets you set request headers can send X-hyreflow-Telemetry: 0, honored unless your workspace is pinned. In Claude Code, add it when you connect:

claude mcp add --transport http hyreflow https://recruit.hyreflow.ai/api/v2/mcp \
  --header "X-hyreflow-Telemetry: 0"