EARLY ACCESS

API & MCP reference

Honest, normalized salary data. Ask for an occupation in a country — or compare across countries — and get the median (or mean) pay in local currency, USD, and PPP, from official statistics, with every caveat labeled.

Overview

salarymcp is a REST API and an MCP server over the same data. Every value carries what it is: median or mean, role- or group-level, reference year, source, and a comparability note. Nothing is silently estimated.

The API is in early access. Request a key to start.

Authentication

Pass your API key in the X-API-Key header on every request. Keys look like sk_…. A missing or invalid key returns 401.

curl https://api.salarymcp.com/v1/coverage \
  -H "X-API-Key: sk_your_key_here"

Keep your key server-side. Never ship it in client-side code.

Base URL

https://api.salarymcp.com

All data endpoints live under /v1. Responses are JSON; amounts are strings (two decimals) to avoid float rounding.

Get a salary

GET /v1/salary — median (or mean) annual pay for one occupation in one country.

Param	Type	Notes
`country`	string	required · ISO-2 (e.g. `DE`)
`occupation`	string	required · free text or ISCO code
`year`	int	optional · reference year
`to_year`	int	optional · age the value to a year (LCI uplift)

curl "https://api.salarymcp.com/v1/salary?country=DE&occupation=software" \
  -H "X-API-Key: sk_…"

{
  "country": "DE",
  "occupation_title": "Software developers",
  "value_original": "72000.00", "currency_original": "EUR",
  "value_usd": "78000.00",
  "value_pps": "92000.00",
  "stat_type": "median",
  "isco_level": "major_group",
  "reference_year": 2022,
  "is_estimated": false,
  "source": "Eurostat",
  "comparability_note": "group-level ISCO; comparable"
}

No data for that country + occupation returns 404 — never a guessed number.

Compare across countries

GET /v1/compare — the same occupation across several countries, each in local currency, USD, and PPP.

Param	Type	Notes
`occupation`	string	required
`countries`	string	required · comma-separated ISO-2 (e.g. `US,DE,BR`)
`year` / `to_year`	int	optional · same as above

curl "https://api.salarymcp.com/v1/compare?occupation=software&countries=US,DE,BR" \
  -H "X-API-Key: sk_…"

Coverage

GET /v1/coverage — which countries, sources, ISCO levels and years are available. No params.

Search occupations

GET /v1/occupations/search?q= — find canonical ISCO-08 occupations by text.

curl "https://api.salarymcp.com/v1/occupations/search?q=nurse" \
  -H "X-API-Key: sk_…"

Usage

GET /v1/usage — your current plan and monthly consumption.

{ "plan": "pro", "period": "2026-09", "used": 1240, "quota": 100000, "remaining": 98760 }

Response fields

Field	Meaning
`value_original` / `currency_original`	Salary in the country's local currency + its ISO code
`value_usd`	Converted to USD (ECB reference rates)
`value_pps`	Purchasing-power adjusted (World Bank PPP)
`stat_type`	`median` or `mean` — Europe sometimes only publishes mean
`isco_level`	`detailed` (specific role) or `major_group`
`reference_year`	Year the salary refers to
`is_estimated` / `aged_to_year`	Whether the value was uplifted, and to which year
`source`	Eurostat · U.S. BLS · RAIS · …
`comparability_note`	Plain-language caveat for honest comparison

Errors

Errors follow RFC 9457 (application/problem+json).

Status	When
`401`	Missing or invalid API key
`404`	No data for the requested country + occupation
`429`	Monthly quota exceeded (or per-minute rate limit)

{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "sem dado para país+ocupação" }

MCP server

salarymcp is also an MCP server — plug it straight into Claude and other AI agents, no glue code. It exposes four tools:

Tool	Does
`get_salary`	Annual median/mean for an occupation in a country — local currency, USD, PPP
`compare_salaries`	The same occupation across countries
`get_coverage`	Available countries, sources, levels, years
`search_occupations`	Find ISCO-08 occupations by text

Authenticate with the same sk_… key. Connection details ship with your early-access key.

Plans & limits

Plan	Monthly quota
Free	1,000 requests / mo
Pro	100,000 requests / mo
Enterprise	Custom

A per-minute rate limit also applies to protect the service. See pricing.

Ready to build? Get an early-access key.