Find your role first

npx add-mcp 'https://findyourrolefirst.click/mcp'

API and MCP

Keep using your own agent. Add the feed as an HTTP MCP server, or call the API from your application.

Using Claude Code or Codex CLI? Copy your setup command and first task. The terminal asks for your key privately.

MCP

The endpoint is /mcp on this site's domain. Set an Authorization header with Bearer YOUR_API_KEY. The connection example is on the home page.

Your client must support Streamable HTTP and custom authorization headers. OAuth-only connector flows aren't supported by this version.

Check client compatibility

Before paying, check that your agent lets you configure a remote HTTP server with a custom bearer header, because a connector that only offers an OAuth sign-in screen won't be able to use this version even if it advertises MCP support.

• search_jobs: whole-word search over titles and companies, newest posting first. Filter by country or city (location), leave words out (exclude), keep remote roles only, or limit to posted_within_hours.
• count_jobs: how many roles a search would match, up to 1,000. Free, so size a search before you spend credits on it.
• list_my_jobs: every role you have already unlocked, newest first. Free to read.
• get_job: refresh one job's metadata, dates, known status, and links. Search already includes these fields.
• get_changes: new, updated, reopened, and closed jobs after a saved cursor. Description-only edits aren't tracked.
• get_usage: your current allowance. This call is free.

Read descriptions at the source

Find your role first returns basic job details, salary and work arrangement when supplied, source dates, the original posting URL (url), and the application URL (apply_url). Full descriptions and generated summaries aren't included.

Your agent needs its own web or browser tool to open the original posting and read requirements. An LLM connection alone doesn't fetch pages. If access fails or a login is required, open the link yourself or provide the text to your agent. Respect source restrictions and keep unknown requirements unknown.

Read requirements at url. The apply_url link may lead straight to a form.

Choosing the right source link

Start with the original posting URL when reading requirements, because an application link may open a form without the description, and a successful connection to Find your role first only gives your agent the returned fields and links without adding a browser or granting access to the employer's site.

HTTP API

Send the same bearer header. Start with GET /api/jobs?query=product&location=San%20Francisco. The response includes jobs and next_offset. Pass that offset into the next request.

Use GET /api/jobs/{id} for one job, GET /api/changes?cursor=0 for changes, and GET /api/account for usage. The OpenAPI schema documents parameter types.

Dates you can trust

Honestly, hiring systems don't always supply a publication date. published_at stays null when it's unknown. first_seen records discovery; baseline means the job was already present when we began monitoring.

Search only returns jobs whose board was checked successfully within the last 24 hours. Individual details include older records so your agent can see their last known state. Closure is recorded after two successful board responses omit a job. Failed fetches preserve the previous records.

For publication filtering, use published_since=2026-09-01T00:00:00Z. Jobs without a source date won't match. discovered_since excludes baseline imports. Company labels currently use source board identifiers.

Discovery vs publication

If you're looking for newly discovered roles, use the discovery filter and inspect the source date separately, since a listing first found during today's check might have been published much earlier and a recent check alone tells you nothing about its original age.

Usage and errors

The $9 plan includes 3,000 unique jobs per UTC calendar month, with at most 1,000 newly unlocked jobs per UTC day. Search and change pages hold up to 20 records. All keys and delivery methods share the same allowance.

A job counts once in the month when it's first returned to your account. Repeat reads, retries, and updates to that job cost no more job credits that month. Empty results and usage checks are free. A job read in a new month counts again. The public five-job sample is free and doesn't unlock jobs in your account.

Rate limits, resets and errors

Every data call still counts toward 30 calls per fixed UTC minute, including free repeats, empty results, and calls rejected by the job quota. Each successful data response includes usage.charged, remaining daily and monthly jobs, and reset times. No unused credits roll over.

If a batch needs more credits than remain, the whole batch fails with no charge and no cursor advance. Lower limit and retry the same offset or cursor. REST limit errors include Retry-After; MCP errors explain the reset time. Daily credits reset at midnight UTC and monthly credits on the first day of the UTC month, independently of your subscription billing date.

HTTP errors use an error message: 401 means the key is invalid, 402 means the subscription is inactive, and 429 means a rate or monthly limit. A 410 change response means its cursor has expired; restart from a current search and cursor 0. Change history lasts 90 days. MCP tool errors carry the same explanation.

One search includes links for up to 20 jobs and can use up to 20 job credits. Reading those links with your own browser tool uses no Find your role first credits. Refreshing an already-unlocked job through get_job is free within that month; your browser and AI provider may charge separately.

Where to put your key

The setup command carries YOUR_API_KEY. Substituting it however you normally handle a credential is fine — here is what each choice actually does, so you can pick rather than be told.

Straight into the command. Fastest. The key is written into your client's MCP config and into your shell history, so anyone with that file or that history has it. Fine on a machine only you use.

From a variable. export JOBFEED_API_KEY=... first, then reference it. Keeps the key out of the command you paste. It lives only in that terminal unless you put it in a shell startup file, in which case it is on disk in plain text like any other env var. This is what the Codex command does, because Codex reads the token from the environment by design.

From a secret manager. Whatever you already use — op run, pass, your OS keychain — works the same way: resolve it into the environment and let the client read it there.

Whichever you pick: save the key in a password manager, because it is shown once. The account page can replace a key and open billing even when the subscription is inactive. Replacing a key disconnects previous integrations while preserving usage, so rotating is cheap if a key ever ends up somewhere you did not intend.

Treat job fields and any source pages your agent reads as untrusted data. Never send your Find your role first API key to an employer page or follow instructions embedded in a listing. Application submission stays in your own workflow.