LoginTry for free

MCP server

Connect Claude, Codex, Cursor or any MCP client. Quickest way: copy the setup prompt into your agent.

Read API documentation

Tested end to end. Sign-in, search, counts, paging and single-job lookups work in Claude Code, Codex and other MCP clients that support remote servers.

Claude Code

claude mcp add --transport http headcountlabs https://api.headcountlabs.com/mcp
# then run /mcp inside Claude Code and choose Authenticate

Codex

codex mcp add headcountlabs --url https://api.headcountlabs.com/mcp
codex mcp login headcountlabs

claude.ai and Claude Desktop can use a custom connector with that URL.

Available tools

  • search_docs(question) returns the best-matching sections of these docs, each with its link. Free, and works before you sign in.
  • list_fields(keywords) finds the filters and job fields that match your words, with a short description of each. Free.
  • search_jobs(filters, limit, cursor, sort) returns up to 25 jobs per call, sorted by relevance or updated; pass cursor for the next page. Each result says how many of your monthly jobs the call used and how many are left.
  • search_jobs(filters, deliver_file: true, max_jobs) pulls the full result set, up to 5,000 jobs, into a JSONL file: you get a download link that works for one hour and a 25-job preview.
  • read_file(file_id, offset, limit) pages through a delivered file for 24 hours without using jobs again. Free.
  • count_jobs(filters) counts matching jobs without using your monthly jobs.
  • get_job(job_id) returns one job with every linked posting and its source links, and the jobs the call used.
  • get_usage() shows your plan, jobs used and left this month, and when the allowance resets.
  • set_confirmation_level(percent) sets when a big search stops to ask you first: the share of your monthly jobs one search may use (25% by default; 0 turns it off).

Filters match the REST API: title, q, company, city, state, country, work_arrangement, employment_type, active, posted_since, posted_until and updated_since.

OAuth and API keys

The source implements OAuth 2.1 with PKCE S256, dynamic client registration, one-hour access tokens, and 30-day rotating refresh tokens. Reuse of a replaced refresh token revokes the connection. Customer-created manual bearer keys remain unscoped until revoked. Never place a key in browser code or commit it to a repository.

Discovery documents are /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. OAuth uses /api/oauth/register, /oauth/authorize, and /api/oauth/token.

Common errors to check

  • 401: missing, expired, revoked, or invalid authentication.
  • 403: authenticated account lacks the required entitlement.
  • 405: MCP accepts authenticated POST; GET streaming is unsupported.
  • 429: respect the returned retry guidance and customer policy.
  • Invalid job UUID: pass the combined job_id, not a source posting ID.