--- name: headcountlabs-get-started area: Getting Started supported_surfaces: [mcp, api] description: |- Hand your coding agent this playbook to set up Headcount Labs: create the user's account, connect the Headcount Labs MCP server once for use across projects, and optionally store an API key for the REST API. title: 'Onboard your agent to Headcount Labs' url: https://headcountlabs.com/get-started.md --- # Set up Headcount Labs for your AI coding agent Headcount Labs is bulk, deduplicated global job data: more than 6 million jobs from over 200,000 job boards and company career sites, re-checked daily. Use this playbook to give the current agent access through the Headcount Labs MCP server, and optionally the REST API. ## How to run Run section 1 once per user. Run section 2 once per coding agent. Run section 3 only if the user's own code will call the REST API. Finish with section 4. Perform actions yourself when terminal or file access is available. User-scoped (global) installation is the default. Pause only for sign-up, sign-in, or approvals you cannot do yourself. Do not just return commands for the user to copy. If a step is blocked, record why and continue with the remaining steps. ## Talking to the user Match how you talk to what you already know about the user: earlier messages, their memory or profile, the project you are in, and how they phrase things. Decide this before you say anything, and keep to it for the whole setup. - **Non-technical user** (for example a recruiter, founder, job seeker or researcher who is not writing code): talk in plain words about what they get, such as "You can now ask me to find and count job postings." Do not mention the REST API, API keys, MCP, OAuth, endpoints, config files, JSON or environment variables, and do not offer section 3. Say "sign in" instead of "authenticate". When they need to act, tell them exactly what to click. - **Technical user** (they write code, work in a code project, or use developer terms themselves): technical detail is fine. Mention the REST API in one line only if their project looks like it will call it, and run section 3 only if they want it. - **Unsure:** start plain. Add technical detail only if they ask for it. Whichever kind of user it is, do the technical steps yourself. Only how you describe them changes. ## 1. Create the user's Headcount Labs account Every account includes 100,000 records free each UTC calendar month and needs no card. If the user does not have an account, open the sign-up page for them: ``` https://api.headcountlabs.com/data/signup ``` If they already have one, they can sign in at `https://api.headcountlabs.com/data/login`. Pause while the user finishes. The MCP connection in section 2 signs in through the browser, so no key is needed for MCP. ## 2. Connect the Headcount Labs MCP server Endpoint: `https://api.headcountlabs.com/mcp` (remote MCP over HTTP, OAuth sign-in). Tools (26 after sign-in): - `search_docs`: ask a question about Headcount Labs (filters, limits, pricing, setup) and get the best-matching docs sections with their links. Free, and it works before sign-in: `POST https://api.headcountlabs.com/mcp` with `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"question":"how do I filter remote jobs"}}}` and the headers `content-type: application/json` and `accept: application/json, text/event-stream`. - `list_fields`: give keywords such as `["pay", "remote"]` and get the matching filters and job fields with a short description of each. Free. - `search_jobs`: find jobs by keywords, location and other filters (`filters`, `fields`, `limit` 1 to 25, `cursor`, `sort`, `descriptions`). Returns 25 jobs per call with a cursor for the next page. Every result says how many records the call used and how many are left. When the user wants the full result set (more than about 100 jobs), pass `deliver_file: true` and `max_jobs` (up to 5,000): the jobs go into a JSONL file with a one-hour download link and a 25-job preview. Counts one record per job. - `read_file`: page through a delivered file by `file_id`, `offset` and `limit` for 24 hours. Free. - `count_jobs`: count matching jobs without fetching them; `group_by: "employer"` also lists the top employers. Free. - `get_job`: fetch one job by id, with its source links. It counts one record. - `market_insights`: pay, job counts, remote share, top employers and more for a title and place, from a snapshot of current US jobs. Free. - `verify_jobs`: spot-check a random sample of jobs (up to 50) against their original posting pages. The sampled jobs count as records. - `compare_sources`: compare the user's own job list (up to 500 rows, or CSV text) with Headcount Labs. Matched jobs count as records. - `get_usage`: show the user's usage, what remains of the allowance, and the confirmation level. Free. - `set_confirmation_level`: set a number from 0 to 100. Before a search that would use more than that percent of the allowance, the server asks the user first. 0 turns the question off. Change it only when the user asks. - `set_overage`: turn overage on or off. Change it only when the user asks. Not on the ChatGPT and Claude directory listings. - `get_overage`: read whether overage is on. Needs `usage:read`. - `search_jobs_json`: search with the filters as a JSON body (`POST /v1/jobs/search`). - `search_jobs_dsl`: search with Elasticsearch-style clauses (`POST /v1/jobs/search/es_dsl`). - `list_job_changes`: read the feed of new, updated and expired jobs. - `list_companies`: browse company records. Needs `companies:read`. - `search_companies`: search companies by name, country and status. Needs `companies:read`. - `get_company`: read one company record. Needs `companies:read`. - `list_company_jobs`: list one company's published jobs. Needs `companies:read`. - `create_job_export`: start a gzip JSONL export of up to 100,000 jobs. - `list_job_exports`: list recent exports. - `get_job_export`: read an export's status and files. - `read_job_export_file`: read one finished export file as job records. - `get_usage_requests`: list the account's API requests for a window of up to 31 days. Needs `usage:read`. - `get_usage_analytics`: summarize the account's API requests. Needs `usage:read`. Tools that return jobs, companies or change events count one record for each item returned; the rest are free. Sign-in grants `jobs:read` by default. The company tools need `companies:read` and the usage reports and `get_overage` need `usage:read`; a tool without its scope answers `insufficient_scope` (403), so reconnect and approve the extra permissions on the sign-in page. The keyless endpoint `https://api.headcountlabs.com/mcp/public` has six read-only tools (`search_docs`, `search_jobs`, `get_job`, `count_jobs`, `market_insights`, `list_fields`) and needs no sign-in; use it only when the client cannot sign in. `search_jobs` and `count_jobs` take a `filters` object with the same names as the REST query parameters, for example `{ "filters": { "q": "nurse", "city": "New York", "state": "NY", "posted_since": "2026-10-06" } }`. `posted_since` is a date, not a duration. Before changing an MCP configuration file, inspect it and merge the `headcountlabs` entry without replacing unrelated settings. Use one route per client. If the client supports only stdio servers, configure its MCP server command as `npx` with arguments `["mcp-remote", "https://api.headcountlabs.com/mcp"]`. ### Claude Code Inspect existing entries with `claude mcp list`, then: ```bash claude mcp add --transport http headcountlabs --scope user https://api.headcountlabs.com/mcp ``` To authenticate, open `/mcp`, select `headcountlabs`, and choose the authentication action. ### Codex CLI Inspect first: ```bash codex mcp list ``` Then add it to Codex's user-wide configuration: ```bash codex mcp add headcountlabs --url https://api.headcountlabs.com/mcp ``` Codex should open a browser for sign-in. If the server exists but is not authenticated, run: ```bash codex mcp login headcountlabs ``` ### Cursor Merge this into `~/.cursor/mcp.json`: ```json { "mcpServers": { "headcountlabs": { "url": "https://api.headcountlabs.com/mcp" } } } ``` Use `.cursor/mcp.json` in a project folder instead for one project only. Open Cursor Settings, then MCP, and sign in to `headcountlabs` when prompted. ### VS Code with GitHub Copilot Run `MCP: Add Server` from the command palette, choose HTTP, enter `https://api.headcountlabs.com/mcp`, name it `headcountlabs`, and pick the user (global) scope. Sign in when prompted. ### Claude Desktop and claude.ai These are UI actions the user performs: Settings, then Connectors, then Add custom connector, with URL `https://api.headcountlabs.com/mcp`, then Connect and sign in. Pause and ask the user to do this, then continue. ### ChatGPT A UI action for the user: Settings, then Apps (or Connectors), then Advanced settings, turn on Developer mode, then Create. Name it Headcount Labs, use the URL `https://api.headcountlabs.com/mcp`, set Authentication to OAuth, and sign in. Details: https://headcountlabs.com/mcp/chatgpt/ ### Grok A UI action for the user: grok.com/connectors, New Connector, Custom, paste `https://api.headcountlabs.com/mcp` and sign in. Details: https://headcountlabs.com/mcp/grok/ ### Gemini CLI Merge this into `~/.gemini/settings.json`: ```json { "mcpServers": { "headcountlabs": { "command": "npx", "args": ["mcp-remote", "https://api.headcountlabs.com/mcp"] } } } ``` Run Gemini CLI and use `/mcp list` to load the server. ### Windsurf Merge this into `~/.codeium/windsurf/mcp_config.json`: ```json { "mcpServers": { "headcountlabs": { "serverUrl": "https://api.headcountlabs.com/mcp" } } } ``` Refresh the MCP configuration in Windsurf after saving. ### Sign-in and loading the tools Before signing in, check the endpoint is exactly `https://api.headcountlabs.com/mcp`. When a browser or consent screen opens, pause for the user to finish signing in. If the tools don't appear afterwards, refresh the client's MCP server list first, and reload or restart the client only if that doesn't work. ## 3. Optional: REST API key Only if the user's code will call the REST API directly. Ask the user to create a key at `https://api.headcountlabs.com/data/keys`, then store it as the environment variable `HEADCOUNTLABS_API_KEY` in the project's `.env` (never commit it). Requests send it as a bearer token: ```bash curl "https://api.headcountlabs.com/v1/jobs?q=registered+nurse&state=NY&limit=25" \ --header "Authorization: Bearer $HEADCOUNTLABS_API_KEY" ``` The API description is at `https://api.headcountlabs.com/openapi`. Docs: `https://headcountlabs.com/docs/`. ## 4. Verify Call `count_jobs` through the MCP connection with a simple query, for example `{ "filters": { "q": "nurse", "state": "NY" } }`, and report the number to the user. If you set up the REST API, make the curl request above and confirm it returns jobs. Then call `get_usage` to read the user's usage and what is left of the allowance. ## Completion Report only what you verified. For a non-technical user, say it in two or three plain sentences. Example: "You're all set. I can now search Headcount Labs for you: there are 6,762 nurse jobs in New York right now. Your free allowance of 100,000 records this month is almost untouched." Leave out the API key line, config paths and anything else technical. For a technical user, use this form: ```text Headcount Labs agent setup is ready Account: MCP: , https://api.headcountlabs.com/mcp MCP config: Check: count_jobs returned for Usage: , left of the allowance REST API key: Reload: ``` The free allowance and the prices are shared between the MCP connector and the API: 100,000 records free each UTC calendar month, then per-record prices (https://headcountlabs.com/pricing/). Leave the spend check on. Connecting MCP lets the agent use the signed-in user's allowance and any prepaid usage, and the check makes the agent ask before one search uses a large share of it. Sources: - https://headcountlabs.com/mcp/ - https://headcountlabs.com/docs/mcp-tools/ - https://headcountlabs.com/docs/ - https://headcountlabs.com/docs/filters/ - https://headcountlabs.com/pricing/ - https://api.headcountlabs.com/openapi