MCP server

POST https://api.jobopportunitiesapi.org/mcp carries every JSON-RPC 2.0 message: initialize, notifications/initialized, ping, tools/list, tools/call. Every response is a single application/json object — never Server-Sent Events, because nothing here pushes unprompted. GET on the same path answers 405, which is spec-legal for a server with nothing to stream. No session id is issued: the server is stateless, and every call carries its own Authorization header.

Six tools wrap six parts of the REST API, and each tool call replays through the exact same request path a direct curl of the wrapped endpoint would use — the same handler, the same auth check, the same metering. There is no second implementation of any of this to drift out of sync with the API you already know.

A row-serving tool called with no Authorization header never reaches the database: it answers a structured refusal naming the free-key page, the same shape every tool's own description tells the calling model to expect — never a bare 401 the model has to interpret.

Claude Desktop and Claude.ai use the streamableHttp shape below, either pasted into Settings → Connectors → Add custom connector, or written directly into claude_desktop_config.json.

{
  "mcpServers": {
    "joa": {
      "type": "streamableHttp",
      "url": "https://api.jobopportunitiesapi.org/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Cursor, VS Code and Cline all read the plain shape below — Cursor's project or global .cursor/mcp.json, VS Code's .vscode/mcp.json (or Command Palette → "MCP: Add Server" → HTTP), and Cline's MCP Servers → Configure MCP Servers, which reads the identical mcpServers block.

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

Windsurf: Cascade → Plugins → MCP Servers → add a custom server with the same URL and header, or edit ~/.codeium/windsurf/mcp_config.json directly — same JSON shape as Cursor's above.

initialize first, then a tool call. The handshake needs no key; a keyed tool call does.

A tool call replays through the same request path the matching REST endpoint uses, so a search_jobs call and a direct curl of /v1/jobs with the identical filter and the same key charge the identical number of records — there is one metering implementation, reached two ways, not two that could drift apart.

changes_since on a plan without the delta-feed entitlement gets the same 403 a direct curl of /v1/changes would get. A free Explore key (1,000 records a month, no card) is enough to try every keyed tool — get one here.