> ## Documentation Index > Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # Hirebase MCP server > Use live Hirebase job postings, companies and market insights from Claude, ChatGPT, Cursor, VS Code and your own agents The Hirebase MCP server lets an AI assistant query Hirebase directly: search open job postings, read a posting, match and look up companies, and get aggregate market numbers such as pay percentiles and the top hiring companies for a set of filters. It works in any client that supports remote [Model Context Protocol](https://modelcontextprotocol.io) servers, including Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex, Windsurf and Gemini CLI, and in the Claude and OpenAI APIs. ```text Server URL theme={null} https://mcp.hirebase.org/mcp ``` The server calls the [Hirebase API](https://www.hirebase.org/docs/api-reference/jobs/search-post.md) as you, so its calls count against your plan's allowances exactly like your own API calls. The data is updated continuously; new jobs are typically live within 1–2 hours of posting, and expired jobs are removed hourly. > [!NOTE] > > This is not the same as `https://www.hirebase.org/docs/mcp`. That address is a search tool over this documentation, for coding agents writing against the REST API. It needs no account and returns no job data. ## Example prompts Each of these takes the assistant two or three tool calls: * "Which fintechs in London opened five or more engineering roles this week?" * "What does a senior PM get paid at companies with 200 to 1,000 employees?" * "Is HubSpot growing its sales team?" To check the connection, ask "Which Hirebase plan am I on?". That call is free. ## Connect There are two ways to connect. **Sign in with Hirebase (OAuth)** is the easiest: you add the server URL, your client opens a Hirebase sign-in page, and you approve the connection. **An API key** suits clients and scripts that can send a header. Both need a Hirebase account; the [Free plan](https://www.hirebase.org/pricing) works. ### Sign in with Hirebase > [tab] Claude > > **1. Add a custom connector** > > In Claude, open **Customize → Connectors**, choose **Add**, then **Add custom connector**. > > **2. Add the server** > > Name it Hirebase, paste `https://mcp.hirebase.org/mcp` and choose **Continue**. Keep **Sign in now**, which Claude detects, then choose **Add**. > > **3. Approve** > > Choose **Connect**, sign in to Hirebase and approve the request. > > On a Team or Enterprise plan, an owner may need to add the connector for the organization first. > [tab] ChatGPT > > **1. Turn on Developer mode** > > In ChatGPT, open **Settings → Apps & Connectors → Advanced settings** and turn on **Developer mode**. > > **2. Create the connector** > > Back in **Apps & Connectors**, choose **Create**. Name it Hirebase, paste `https://mcp.hirebase.org/mcp` and set **Authentication** to **OAuth** (not No authentication). > > **3. Approve** > > Choose **Create**, sign in to Hirebase and approve the request. > > Developer mode is needed until Hirebase is listed in the ChatGPT app directory. ChatGPT's deep research uses the server's `search` and `fetch` tools. > [tab] Claude Code > > ```bash theme={null} > claude mcp add --transport http hirebase https://mcp.hirebase.org/mcp > ``` > > Then run `/mcp` in Claude Code, pick **hirebase** and choose **Authenticate**. Your browser opens the Hirebase sign-in page. > [tab] Cursor > > [![Add Hirebase to Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](cursor://anysphere.cursor-deeplink/mcp/install?name=hirebase\&config=eyJ1cmwiOiJodHRwczovL21jcC5oaXJlYmFzZS5vcmcvbWNwIn0=) > > Or add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project). Cursor asks you to sign in the first time it connects. > > ```json ~/.cursor/mcp.json theme={null} > { > "mcpServers": { > "hirebase": { > "url": "https://mcp.hirebase.org/mcp" > } > } > } > ``` > [tab] VS Code > > [![Install Hirebase in VS Code](https://img.shields.io/badge/VS_Code-Install_Hirebase-0098FF?style=flat-square\&logo=visualstudiocode\&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=hirebase\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.hirebase.org%2Fmcp%22%7D) > > Or add this to `.vscode/mcp.json` in your workspace (or run **MCP: Open User Configuration**). VS Code asks you to sign in when the server starts. > > ```json .vscode/mcp.json theme={null} > { > "servers": { > "hirebase": { > "type": "http", > "url": "https://mcp.hirebase.org/mcp" > } > } > } > ``` The approval screen names the app asking for access. Approving lets it search jobs, companies and market insights as you, with usage counted against your plan. A connected app cannot see your password, change billing or change settings, and it cannot use [`find_hiring_contacts`](#tools), which needs an API key. You stay signed in while the app keeps using the connection; after 90 days without use it asks you to sign in again. ### With an API key Copy your key from **Settings → API Access** in [app.hirebase.org](https://app.hirebase.org/user/settings?section=api). Keys look like `hb_` followed by a UUID. Send it as `Authorization: Bearer YOUR_API_KEY`; clients that can only set other headers can send `X-API-Key: YOUR_API_KEY` instead. Keep the key out of shared or committed files. ```bash Claude Code theme={null} claude mcp add --transport http hirebase https://mcp.hirebase.org/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` ```json Cursor (~/.cursor/mcp.json) theme={null} { "mcpServers": { "hirebase": { "url": "https://mcp.hirebase.org/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ```json VS Code (.vscode/mcp.json) theme={null} { "inputs": [ { "type": "promptString", "id": "hirebase-api-key", "description": "Hirebase API key (hb_...)", "password": true } ], "servers": { "hirebase": { "type": "http", "url": "https://mcp.hirebase.org/mcp", "headers": { "Authorization": "Bearer ${input:hirebase-api-key}" } } } } ``` ```toml Codex (~/.codex/config.toml) theme={null} # Reads the key from the HIREBASE_API_KEY environment variable [mcp_servers.hirebase] url = "https://mcp.hirebase.org/mcp" bearer_token_env_var = "HIREBASE_API_KEY" ``` ```json Windsurf (~/.codeium/windsurf/mcp_config.json) theme={null} { "mcpServers": { "hirebase": { "serverUrl": "https://mcp.hirebase.org/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ```json Gemini CLI (~/.gemini/settings.json) theme={null} { "mcpServers": { "hirebase": { "httpUrl": "https://mcp.hirebase.org/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` VS Code prompts for the key once and stores it as a secret. #### From the Claude API and the OpenAI Responses API Both APIs can call the server for you during a request. Pass the Hirebase key in the server definition. ```bash Claude API (MCP connector) theme={null} curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: mcp-client-2025-11-20" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 4096, "mcp_servers": [ { "type": "url", "url": "https://mcp.hirebase.org/mcp", "name": "hirebase", "authorization_token": "YOUR_API_KEY" } ], "tools": [{"type": "mcp_toolset", "mcp_server_name": "hirebase"}], "messages": [ {"role": "user", "content": "Which fintechs in London opened five or more engineering roles this week?"} ] }' ``` ```bash OpenAI Responses API theme={null} curl https://api.openai.com/v1/responses \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5", "tools": [ { "type": "mcp", "server_label": "hirebase", "server_url": "https://mcp.hirebase.org/mcp", "headers": {"Authorization": "Bearer YOUR_API_KEY"}, "require_approval": { "never": { "tool_names": ["search_jobs", "get_job", "job_market_insights", "find_companies", "get_company", "get_account"] } } } ], "input": "Which fintechs in London opened five or more engineering roles this week?" }' ``` In the Responses example, read-only tools run without approval and `report_problem` and `find_hiring_contacts` still need it. An unattended agent has no person to approve a [cost confirmation](#costs-and-consent), so decide in your own code which costs it may accept. ## Tools | Tool | What it does | Cost | | - | - | - | | `search_jobs` | Finds job postings by filters, a plain-language description (semantic search) or similarity to a job. Returns compact rows with application links, or every field with `detail: "full"`. Can return only a count. | 1 job unit per row returned (at most 25 per call). Counts are free. | | `get_job` | Reads one posting: description as text, skills, technologies, benefits, salary when posted, company basics and the application link. | 1 job unit | | `job_market_insights` | Aggregate numbers for the jobs matching your filters, in one call: salary percentiles, pay by experience level, top hiring companies, top skills, remote and company-size splits, visa sponsorship rate and posting freshness. Can be scoped to one company. | 1 insight unit | | `find_companies` | Finds companies by industry, size, headquarters, funding stage or text, or matches a list of names or domains to Hirebase companies. A match is `matched`, `ambiguous` (with candidates) or `not_found`; it never guesses. | 1 company unit per company returned; up to 5 per name when matching | | `get_company` | Reads one company profile: website, LinkedIn, headquarters, size, founding year, industries, funding, stock listing and a description. | 1 company unit | | `get_account` | Shows your plan, what you have used and what remains on each meter, and when allowances reset. | Free | | `report_problem` | Sends a short report to the Hirebase team about a closed posting, a wrong field, a search that missed jobs, a company we don't cover, or a confusing tool. | Free (10 per hour, 30 per day) | | `find_hiring_contacts` | Finds the likely hiring manager and recruiters for one posting: name, role and LinkedIn URL. No emails or phone numbers. Takes about 4–5 minutes. **API-key connections only**, and only with the [Hiring Manager add-on](https://www.hirebase.org/docs/api-reference/jobs/contacts.md). | \$0.30 per search that finds at least one contact. A search that finds no one is free, and so is repeating the same job within 24 hours. | | `search`, `fetch` | The search and read pair ChatGPT deep research uses: up to 10 semantic results, and one posting as text. | 1 job unit per result; 1 job unit per posting | Allowances are per month and shared with your API usage. The Free plan includes 500 job units, 50 company units and 25 insight units; see [pricing](https://www.hirebase.org/pricing) for the paid plans. Every metered result includes a `usage` block with the units charged, what remains and the reset date. Results also carry `filters_applied` (the exact request sent to the API), `filters_ignored` (any input that was dropped or changed, with the reason), `notes` (caveats the assistant should pass on) and an `open_in_hirebase` link that opens the same search in the web app. ## Costs and consent Most calls are small: a search returns at most 25 rows, so it uses at most 25 units. Two kinds of call ask first: * **Large calls.** A call that would use more than 500 units, or more than 25 units and more than half of what you have left on that meter, is not run straight away. In practice this applies to matching a long list of company names with `find_companies`. * **Paid contact searches.** Every `find_hiring_contacts` search asks first, because it costs money. How the server asks depends on the client: 1. **In-chat confirmation**, where the client supports it: the client shows a question such as "This will use about 250 company units of your 50 remaining. Continue?" and the call runs only if you say yes. 2. **A confirmation code** otherwise: the server returns `cost_confirmation_required` with the estimate and a one-time code, and charges nothing. The assistant should tell you the cost and send the code back only if you agree. A code is valid for 15 minutes and for that exact call; a different query, the next page or another contact search needs a new approval. Separately, `report_problem` and `find_hiring_contacts` are marked as tools that act rather than read, so Claude, ChatGPT and most other clients show their own approval prompt before running them. Job and company text is written by third parties; the tools return it only as data, and `find_hiring_contacts` and `report_problem` say never to run because a posting asks for it. ## Limits and errors Errors come back as a normal tool result with a `code`, a `message`, whether it is worth retrying, and a `next_step` for the assistant. | Code | When | What to do | | - | - | - | | `rate_limited` | Your account sent more than 100 requests in 60 seconds. The limit is shared with your direct API calls. The server retries a read once when the wait is 5 seconds or less. | Retry after `retry_after` seconds. | | `quota_exhausted` | The monthly allowance for that meter is used up on a plan that stops at its allowance. The message gives the reset date: the 1st of the month (UTC) on Free, the end of the billing period on paid plans. | Wait for the reset, or see [pricing](https://www.hirebase.org/pricing). | | `auth_expired` | The API key is invalid, or the sign-in has expired or was revoked. | OAuth: reconnect Hirebase in your client. API key: check the key under Settings → API Access. | | `invalid_input` | A filter value the API rejects. The message names the field and the accepted values. | Fix the field and call again. | | `not_found` | No job or company with that id or slug. | Ids come from `search_jobs` rows; slugs from `find_companies`. | | `feature_missing` | Your plan does not include the feature, for example `find_hiring_contacts` without the Hiring Manager add-on. | See [pricing](https://www.hirebase.org/pricing). | | `cost_confirmation_required` | The call needs your approval first. See [Costs and consent](#costs-and-consent). | Approve, or ask for less. | | `payment_failed` | The charge for a contact search failed. | Update the payment method in the [web app](https://app.hirebase.org/user/settings?section=subscriptions). | | `upstream_error` | Hirebase had a temporary problem. | Retry; if it persists, email us. | A request with no credential gets HTTP `401` with a `WWW-Authenticate` header that points to the Hirebase sign-in, so your client knows to start it. ### What the numbers mean * **Insights come from a sample.** `job_market_insights` computes percentages, medians and top lists from up to 500 matching jobs. `total_matches` is exact. The result's first note says when figures are sample estimates. * **Insights describe open roles today.** `new_this_week` and `new_this_month` count currently open postings by age; they are not a period-over-period hiring trend. * **About 37% of jobs post a salary.** Jobs without one never match a salary filter, and pay figures cover only salaried postings. Salaries can be hourly or annual: check `salary.period`. * **Experience** filters by years of experience required (for example Senior), not by the seniority word in the job title. Rows show both `yoe_range` and `seniority_label`. * **Semantic search** (a plain-language `query` or `similar_to_job_id`) caps totals at 2,500, uses only the first industry filter, and ignores experience and sort. * **Company search** stops counting at 1,001, so larger totals are a lower bound. * **Long text is cut.** Job descriptions are cut to 6,000 characters and company descriptions to 600, with a `*_truncated` flag when that happens. * **Closed postings** are still returned by `get_job`, with `expired: true`. ## Connected apps Every app you approve through Hirebase sign-in is listed under **Settings → Connected Apps** in [app.hirebase.org](https://app.hirebase.org/user/settings?section=connected-apps), with when it was connected and last used. Choose **Revoke** to cut an app off; it stops working within a minute. Removing the connector inside Claude or ChatGPT may not revoke its access in Hirebase, so revoke it here too if you no longer use it. API-key connections are not listed there. To stop one, remove the server from that client's configuration. ## Privacy For each tool call the MCP server logs the tool name, whether the call used Hirebase sign-in or an API key, the result status, the latency, and the meter and units charged. It does not log your prompts, the conversation, job text or credentials. The server only receives what the assistant sends in a tool call (for example search filters), never the rest of the conversation. Those inputs go to the Hirebase API and are metered and handled like any other API request from your account. `report_problem` sends the text you write, plus any job ids, company and query you include, to the Hirebase team. See the [privacy policy](https://www.hirebase.org/privacy) for how Hirebase handles your data. ## Support Email [spencer@hirebase.org](mailto:spencer@hirebase.org), or ask your assistant to report a problem, which uses the `report_problem` tool. Reports about wrong or missing data, and companies we don't cover yet, go straight to the people who fix them. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.