Connecting Odds MCP developer documentation

One MCP server, one search contract. Every AI client — chat assistant, IDE agent or automation platform — calls the same tools against the same ranked search engine that powers the Connecting Odds website. Interface version: v1.

Endpoint

https://connectingodds.com/mcp

Transport

Streamable HTTP (the current MCP remote transport). Requests are JSON-RPC over HTTPS and must accept both application/json and text/event-stream. Legacy SSE-only transports are not required — use streamable HTTP unless your client only supports the older mode.

Authentication

OAuth 2.1 with PKCE and dynamic client registration. Clients discover the authorisation server from the protected-resource metadata document, register themselves, redirect the user to Connecting Odds for consent, and receive a scoped access token presented as a bearer token on every call. There are no API keys to paste, and no scopes to configure by hand — the token carries the signed-in user’s own permissions.

Available tools

search_jobs

Search the active Connecting Odds catalogue in natural language or with structured filters. Runs the same intent-aware ranked engine as the website.

Input: query (free text), plus optional location, country, remote type, employment type, experience level, company, category, salary floor/ceiling, skills, visa sponsorship, citizenship, security clearance, posted-within-days, limit.

Returns: Ranked job records: title, company, location, workplace type, salary when the posting states it, skills, eligibility signals, posted date and canonical job URL — plus an explanation of how the request was interpreted.

get_job

Fetch the full public detail of a single posting by its job id.

Input: job_id (UUID).

Returns: The public job record: description, requirements, company, location, salary, eligibility, employment type and apply URL. Private, moderation and recruiter-internal fields are never included.

Account-scoped tools (profile, saved jobs, notifications) are also exposed to the signed-in user and documented in the connector itself. Tools that do not exist yet are not documented here; anything planned will be labelled Coming soon before it ships.

Example call

Clients construct the JSON-RPC envelope themselves. Conceptually, a search is:

tool:  search_jobs
args:  {
  "query": "senior python engineer",
  "location": "Texas",
  "remote": "remote",
  "salary_min": 150000,
  "skills": ["aws"],
  "posted_within_days": 30,
  "limit": 10
}

The response contains structured job records:

{
  "total": 18,
  "interpretation": "Remote senior Python roles in Texas paying at least $150K, mentioning AWS",
  "jobs": [
    {
      "id": "…",
      "title": "Senior Python Engineer",
      "company": "Example Company",
      "location": "Remote — US",
      "salary_min": 150000,
      "salary_max": 180000,
      "skills": ["python", "aws", "postgresql"],
      "visa_sponsorship": "available",
      "posted_at": "…",
      "url": "https://connectingodds.com/jobs/…"
    }
  ]
}

Example response — field values are illustrative, not real listings.

Rate limits

Calls are rate limited per authenticated connection to keep search fast for everyone. Agents that loop should batch their reasoning and search once rather than iterating rapidly. When a limit is hit the tool returns an explicit error the assistant can relay; waiting a minute clears it.

Error handling

Tool failures return a structured error result — invalid input (for example a malformed job id), not found, unauthenticated, or rate limited. Internal server details, stack traces and database errors are never returned to the client.

Security

Only public job data leaves the server
MCP job tools return the same fields a signed-out visitor sees on a job page. There is no raw table access and no query passthrough — the AI client calls a named tool with validated arguments.
Fields that are never exposed
Owner user ids, recruiter-private notes, applicant and application data, moderation state, scraper diagnostics, internal processing metadata and database credentials are excluded at the query layer, not filtered client-side.
You authorise the connection
Connecting Odds MCP uses OAuth 2.1 with dynamic client registration. Your AI client is redirected to Connecting Odds, you approve it, and it receives a scoped access token. You can revoke it at any time by removing the connector in your client.
Tools act as you, with your permissions
Account-scoped tools (your profile, saved jobs, notifications) run under your identity with row-level security applied. Another member's private data is unreachable, whatever the assistant asks for.
Never paste secrets
Connecting Odds will never ask you to paste a database credential, service key or private token into an AI client. The only value you enter is the public MCP endpoint URL.

Versioning

This document describes interface v1, pinned at /ai-job-search/developers/v1. New optional parameters and new optional response fields are added in a backward compatible way — existing clients keep working without changes. A breaking change would ship as a new version at its own path, with the previous version kept available.

Browse AI clients Search jobs