United States

Quickstart

Two calls: search for a short list, then open the evidence for the doctors you are seriously considering. The MCP server and the HTTP API have the same tools and return the same JSON.

No sign-up. Short lists are free; full evidence has a daily allowance.

1. Connect

MCP clients that support remote servers connect to the URL above. No sign-in is needed. An optional account key, sent as Authorization: Bearer, raises the daily allowance.

The same MCP address serves every country on this site (the United States and New Zealand). Decide the country first: where the person wants to see a doctor. If that is unclear, ask the person before searching; do not guess, and do not search every country. For the United States pass country: "US" to search_doctors, list_specialties and about_database, or leave it out (it defaults to the United States, for clients that connected before New Zealand was added). get_doctor reads the country from the doctor id (dr_ = United States). New Zealand: /nz/docs/.

In Claude (Free, Pro, Max, Team and Enterprise; the Free plan allows one custom connector): Customize → Connectors → + Add → Add custom connector, enter a name and the MCP URL, and Continue. Under Authentication choose No sign in (or add an account key under Request headers as Authorization: Bearer), then Add. On Team and Enterprise an Owner adds it first under Organization settings → Connectors, and members then Connect it. Turn it on in a chat with + → Connectors. Claude’s guide.

In ChatGPT, where your plan and workspace allow custom MCP servers: Plugins → + → Add custom MCP server, enter a name and the MCP URL, set authentication, then Create as a plugin and install it; in a chat, type @ and pick it. Choose no authentication. OpenAI’s menus differ between plans and have changed recently: OpenAI’s guide.

These steps were checked against the official guides on 2026-10-12.

In Claude Code, Codex CLI, Gemini CLI, Cursor and VS Code: one-step installs and setup guides are in the GitHub repository. It is also a plugin for Claude Code, Codex and Gemini CLI that adds the MCP server and an Agent Skill.

2. Search

Give at least one of condition, procedure, specialty, name, or a place. Pass medicare_patient=true for anyone 65 or older or on Medicare.

GET https://api.findadoctor.si/api/v1/search?condition=atrial%20fibrillation&city=Phoenix&state=AZ&within_miles=25&medicare_patient=true

Each result has doctor_id, name, degree, NPI, specialty (with its source), city, state, distance_miles, detail_has (what get_doctor adds for this doctor) and, when there are any, warnings (federal exclusion list, Medicare opt-out). With a condition or procedure, match_basis says whether the doctor has direct evidence (a listed focus, procedure volume or many such patients) or only a fitting specialty.

A trimmed example (the doctor’s name, ids and website are replaced; … marks shortened text):

{
  "before_answering": "This is the free short list: who the doctors are, not the evidence. Before recommending anyone, call get_doctor with the doctor_ids you are considering …",
  "interpreted": {
    "medicare_patient": "doctors on the CMS Medicare opt-out list are left out (3 removed)",
    "condition_mesh": [{ "mesh_ui": "D001281", "name": "Atrial Fibrillation", "match": "exact" }],
    "volume_from_procedure_groups": ["afib_ablation", "laa_closure"],
    "location": { "center": ["Phoenix, AZ"], "within_miles": 25, "zip_codes_in_area": 144, "note": "…" }
  },
  "total_matches": 449,
  "offset": 0,
  "results": [
    {
      "rank": 1,
      "doctor_id": "dr_example00001",
      "name": "Example Doctor",
      "degree": "MD",
      "npi": "1234567893",
      "specialty": "Cardiac Electrophysiology",
      "specialty_source": "official records (NPI registry, CMS)",
      "hospital_website_specialties": [{ "site": "Example Health", "specialties": ["Electrophysiology"] }],
      "city": "Phoenix",
      "state": "AZ",
      "distance_miles": 4.2,
      "match_basis": "direct_evidence",
      "detail_has": ["hospital_website_profile", "procedure_volume_for_this_need", "phone", "new_patient_status", "languages"]
    }
  ],
  "warnings": ["3 matching doctors are on the CMS Medicare opt-out list and left out because medicare_patient=true."],
  "next_step": "Call get_doctor with doctor_ids (up to 10 at once) for the doctors you are considering. …"
}

Results are ranked by evidence of focus and experience for the need, not by quality or outcomes. Up to 10 results per search; paging stops at 30. Narrow the need or the place instead of paging.

3. Open the evidence

GET https://api.findadoctor.si/api/v1/doctors?ids=dr_example00001,dr_example00002

Up to 10 doctor ids per call, or one npi. Without an account, each network address can open 5 different doctors' evidence a day; with an account key, 100. Opening the same doctor again the same day is free. One reply holds about 2–3 doctors; the rest come back under not_returned_yet, already counted, so ask again for them at no extra cost.

Insurance, languages and new-patient status come from hospital pages and can be out of date. Tell the person to confirm them with the practice before booking.

Tools

search_doctors parameters

get_doctor parameters

Errors

Limits per connection: Limits. What the data holds and where it comes from: Data.