Hirebase MCP server

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 servers, including Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex, Windsurf and Gemini CLI, and in the Claude and OpenAI APIs.

Server URL

https://mcp.hirebase.org/mcp

The server calls the Hirebase API 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.

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 works.

Claude
ChatGPT
Claude Code
Cursor
VS Code

Add a custom connector

In Claude, open Customize → Connectors, choose Add, then Add custom connector.

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.

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.

Turn on Developer mode

In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.

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).

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.

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.

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.

~/.cursor/mcp.json

{
  "mcpServers": {
    "hirebase": {
      "url": "https://mcp.hirebase.org/mcp"
    }
  }
}

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.

.vscode/mcp.json

{
  "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, 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. 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.

claude mcp add --transport http hirebase https://mcp.hirebase.org/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

{
  "mcpServers": {
    "hirebase": {
      "url": "https://mcp.hirebase.org/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "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}"
      }
    }
  }
}

# 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"

{
  "mcpServers": {
    "hirebase": {
      "serverUrl": "https://mcp.hirebase.org/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "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.

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?"}
    ]
  }'

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, 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.	$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 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. 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:

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.
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.
`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.
`cost_confirmation_required`	The call needs your approval first. See 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.
`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, 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 for how Hirebase handles your data.

Support

Email 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.

Getting Started

Use with AI

Guides

Example prompts

Connect

With an API key

From the Claude API and the OpenAI Responses API

Tools

Limits and errors

What the numbers mean

Connected apps

Privacy

Support

​Example prompts

​Connect

​Sign in with Hirebase

​With an API key

​From the Claude API and the OpenAI Responses API

​Tools

​Costs and consent

​Limits and errors

​What the numbers mean

​Connected apps

​Privacy

​Support

Example prompts

Connect

Sign in with Hirebase

With an API key

From the Claude API and the OpenAI Responses API

Tools

Costs and consent

Limits and errors

What the numbers mean

Connected apps

Privacy

Support