> ## Documentation Index
> Fetch the complete documentation index at: https://jobo.world/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Give Claude, ChatGPT, Cursor, or any MCP client live job search over Jobo's index — including the search/fetch pair ChatGPT Deep Research requires.
**jobo-job-search-mcp** is a remote [MCP](https://modelcontextprotocol.io) server over Jobo's live job index — millions of listings from employer career sites and 100+ applicant tracking systems. Clients sign in with a Jobo account instead of pasting an API key.
This is the **jobs** MCP server. Jobo also runs a separate **analytics** MCP server at `mcp.jobo.world`, which exposes SQL-style querying over the dataset rather than job search tools — that's a different product, documented on its own [marketing page](https://jobo.world/mcp). If you want an assistant to search and cite individual job listings, you want this page; if you want it to run aggregate queries across the dataset, you want that one.
npmjs.com/package/jobo-job-search-mcp
This page assumes you've read the shared [Authentication](/docs/connectors/overview#authentication) section on the [connectors overview](/docs/connectors/overview) — this connector is the one exception to it, so read on for what's different.
***
## Add the hosted server to your client
The hosted server runs at `https://jobs-mcp.jobo.world/mcp`. Add it wherever your client supports a remote MCP server over Streamable HTTP:
```json Claude Desktop / Claude Code theme={null}
{
"mcpServers": {
"jobo-job-search": {
"url": "https://jobs-mcp.jobo.world/mcp"
}
}
}
```
```json ChatGPT (Connectors) / Cursor theme={null}
{
"mcpServers": {
"jobo-job-search": {
"url": "https://jobs-mcp.jobo.world/mcp"
}
}
}
```
```bash Codex CLI theme={null}
codex mcp add jobo-job-search --url https://jobs-mcp.jobo.world/mcp
```
In Claude Desktop, add it under **Settings → Connectors**. In ChatGPT, add it as a connector from the connector settings. Any MCP client that supports Streamable HTTP works the same way.
***
## Sign in (OAuth)
The first tool call opens a Jobo login in your browser. Approve access and the token refreshes itself from then on — there's no key to copy or rotate by hand. Under the hood, the server is an OAuth 2.1 **Resource Server**; the Jobo API is the Authorization Server, and every tool call forwards the bearer token your client currently holds.
If your client keeps asking you to re-authenticate, the access token likely expired without the client refreshing it — remove and re-add the connector. The server issues a standard challenge that any compliant client uses to re-authorise automatically on the next attempt.
***
## Self-hosting
Run the same server yourself with:
```bash theme={null}
npx jobo-job-search-mcp
```
This starts the Streamable HTTP server on `$PORT` (default `3002`); point your client at `http://localhost:3002/mcp` (or wherever you deploy it) instead of the hosted URL. Self-hosting is about controlling where the process runs — it does **not** switch the server to API-key auth. It's still an OAuth resource server gated on the same Jobo account sign-in, since the upstream API validates every request against Jobo's Authorization Server regardless of which copy of the gateway made it.
Configuration is via environment variables:
| Variable | Default | Notes |
| ----------------------- | ------------------------------- | --------------------------------------------------------------------------- |
| `JOBO_API_URL` | `https://connect.jobo.world` | Upstream Jobs API. |
| `MCP_RESOURCE_URL` | `https://jobs-mcp.jobo.world` | OAuth audience — set this to wherever you're actually serving the endpoint. |
| `OAUTH_AUTH_SERVER_URL` | `https://enterprise.jobo.world` | Authorization Server. |
| `PORT` | `3002` | |
***
## Tools
| Tool | Purpose |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search` | Canonical Deep Research contract: `{query}` → `{results: [{id, title, url}]}`. |
| `fetch` | Canonical Deep Research contract: `{id}` → `{id, title, text, url, metadata}`. `text` is self-contained prose built from the AI-extracted job fields, since Deep Research reads it directly and never opens the URL. |
| `search_jobs` | Structured search — location, work model, employment type, experience level, source, skills, industries, salary, date, facets, and paging as real parameters. |
| `get_job_details` | Full listing detail, including the raw description if requested, for clients not using the Deep Research contract. |
| `list_filters` | Accepted values for every filter, with live counts — lets the model use real values instead of guessing. |
`search` and `fetch` deliberately take the minimum arguments the Deep Research contract allows. Anything with more structure — a location, a salary floor, a specific ATS — should go through `search_jobs` instead.
***
## Credits
Searching costs credits from the same wallet the rest of the Jobo API bills against, at the same rate as `GET /api/jobs`: **you pay per job returned**, not per tool call. A search that comes back with ten jobs costs ten jobs' worth of credits; one that comes back empty costs nothing.
| Tool | Cost |
| -------------------------- | ---------------------------------------------------- |
| `search`, `search_jobs` | Per job returned, at your account's job-search rate. |
| `fetch`, `get_job_details` | Free. |
| `list_filters` | Free. |
**No subscription is required** — a wallet balance is enough. If you hold a Job Search plan, its included monthly quota is consumed first and only the overage touches the wallet, exactly as on the REST API.
There's no separate rate limit on the MCP server: your balance is the ceiling. When it runs out, tools return a message saying how many credits the search needed and where to top up, and nothing is billed for that call. Top up at [enterprise.jobo.world/credits](https://enterprise.jobo.world/credits).
***
## Troubleshooting
| Problem | Fix |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The client keeps asking to authenticate | The access token expired and the client isn't refreshing it. Remove and re-add the connector. |
| It can't be added as a ChatGPT Deep Research connector | Deep Research requires the canonical `search`/`fetch` tools. Confirm you added `jobs-mcp.jobo.world`, not the analytics server at `mcp.jobo.world` — the analytics server doesn't expose them. |
| The assistant invents job listings | Ask it to cite the listing URL for each role. Every real result carries one; anything without a URL didn't come from a tool call. |
| Self-hosted instance returns 401 on every call | Confirm `OAUTH_AUTH_SERVER_URL` and `MCP_RESOURCE_URL` match what you told your client to expect — a mismatch between the resource URL you advertise and the one your client requests a token for breaks the OAuth challenge. |
***
For a scheduled workflow rather than a conversational assistant, the n8n node covers the same search surface plus a polling trigger.