docs mcp

MCP overview

Toolsets, the one-call search, prompts, resources, and the confirm gate.

Streamable HTTP at https://mcp.recruitmcp.com/mcp. This server also accepts the same protocol at /mcp and /api/mcp.

Connect with OAuth (claude.ai and other clients that support it find the sign-in on their own) or with an API key:

Authorization: Bearer rmcp_live_…
Accept: application/json, text/event-stream

The one-call search

start_search with the job description. Free. Returns search_id, a plain-language summary, the estimate, applied_filters, ignored_fields, and warnings. Show the summary and estimate.credits_max to the recruiter.
After the recruiter agrees: start_search with search_id and confirm=true (add budget_credits to cap spend). Returns run_id.
get_search_results with run_id and wait_seconds: 25 until done is true. The call waits for news, so the agent does not poll in a loop.

When the budget is already agreed, one call is enough: start_search with job_description, budget_credits, and confirm=true. refine_search changes the intent behind a search_id (send only the blocks to change) and plans again for free.

The confirm gate

Every tool that spends credits or sends a message returns a free preview until it is called again with confirm=true. A repeated confirmed call with the same arguments replays the first answer and does not charge or send twice. Pausing and stopping an enrollment always act at once. A refusal includes next_available_at.

Toolsets

Pick toolsets with ?toolsets= on the URL: sourcing,outreach by default, add advanced, or use all. Example: https://mcp.recruitmcp.com/mcp?toolsets=sourcing,advanced.

Toolset	Tools
`sourcing`	`start_search`, `refine_search`, `get_search_results`, `list_searches`, `extend_search`, `cancel_search`, `lookup_people`, `get_people_job`, `find_contact_details`, `save_to_list`, `list_lists`, `get_list`, `set_candidate_status`, `check_candidates`, `get_account_overview`, `get_guide`
`outreach`	`connect_outreach_account`, `list_outreach_accounts`, `get_outreach_limits`, `list_sequences`, `save_sequence`, `enroll_candidates`, `list_enrollments`, `update_enrollment`, `approve_message`, `list_replies`, `get_conversation`, `send_reply`, `send_outreach_action`, `get_outreach_activity`
`advanced`	`resolve_location`, `resolve_area`, `resolve_companies`, `list_filter_values`, `draft_intent`, `update_intent`, `plan_search`, `search_people_raw`, `match_person`, `add_suppression`, `list_events`

Every tool has an output schema, so clients can read results as structured data. Candidates are compact unless view is full; distance_km is always included. Each tool checks the same scopes as the REST call behind it, and a preview needs only the read scope.

There is no scoring tool. Candidates are facts; the agent judges fit.

Prompts

Prompt	Does
`source_from_job_description`	Plans from job text, confirms the cost with you, runs, and summarises the strongest candidates. Arguments: `job_description`, optional `budget_credits`
`daily_reply_triage`	Reads conversations that need a reply, groups them, and drafts answers for your approval
`pipeline_review`	Summarises recent searches, outreach progress, replies waiting, and credits. Optional `run_id`

Resources

URI	What it is
`recruitmcp://guide`	The agent guide (also llms.txt, and `get_guide`)
`recruitmcp://cost`	Credit prices
`recruitmcp://recipes`	Search recipes
`recruitmcp://outreach`	Outreach safety rules
`recruitmcp://runs/{run_id}`	A run with its first 25 candidates, as JSON
`recruitmcp://lists/{list_id}`	A list with its first 100 people, as JSON

Customers

To act inside a customer, send RecruitMCP-Customer: cus_… on the connection, connect with a key bound to that customer, or pick the customer on the OAuth consent page.

Check the connection

#!/usr/bin/env bash
set -euo pipefail
DOMAIN="${RECRUITMCP_DOMAIN:-recruitmcp.com}"
BASE="${RECRUITMCP_BASE:-https://api.${DOMAIN}}"
MCP="${RECRUITMCP_MCP:-https://mcp.${DOMAIN}/mcp}"
WS=$(curl -fsS -X POST "$BASE/v1/workspaces" -H 'content-type: application/json' -d '{"name":"Northwind Search","email":"ada@northwind.example"}')
KEY=$(node -e 'process.stdout.write(JSON.parse(process.argv[1]).api_key)' "$WS")
LIST=$(curl -fsS -X POST "$MCP" \
  -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')
node -e 'const j=JSON.parse(process.argv[1]); const names=(j.result?.tools||[]).map(t=>t.name); for (const n of ["start_search","get_search_results","save_to_list","enroll_candidates","update_enrollment","send_reply"]) if(!names.includes(n)) { console.error(names); process.exit(1); }' "$LIST"

Setup for each app: Claude Code, Claude Desktop, claude.ai. A single file an agent can follow is /mcp.md.

API reference