# 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

| | Address |
|---|---|
| MCP (Streamable HTTP), every country | `https://api.findadoctor.si/mcp` |
| HTTP API | `https://api.findadoctor.si/api/v1/…` (GET, JSON) |
| OpenAPI 3.1 (parameters and response fields) | [https://api.findadoctor.si/openapi.json](https://api.findadoctor.si/openapi.json) |
| MCP server card | [https://api.findadoctor.si/mcp/server-card](https://api.findadoctor.si/mcp/server-card) |
| Setup guides, examples, Agent Skill, plugins | [github.com/simonlin1212/findadoctor-mcp](https://github.com/simonlin1212/findadoctor-mcp) |

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. Over MCP, 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). The HTTP API below is for the United States only and takes no `country`. New Zealand: [/nz/docs/](/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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

**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](https://developers.openai.com/plugins/deploy/connect-chatgpt).

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](https://github.com/simonlin1212/findadoctor-mcp). 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.

```text
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):

```json
{
  "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

```text
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

| MCP tool | HTTP | What it does |
|---|---|---|
| `search_doctors` | `GET /api/v1/search` | Free short list for a need: condition, procedure, specialty, place or name. |
| `get_doctor` | `GET /api/v1/doctors?ids=…` or `/api/v1/doctors/{doctor_id}` | Evidence for up to 10 doctors, or one by `npi`. Counted per day. |
| `lookup_terms` | `GET /api/v1/terms?text=…` | How a word is understood: MeSH condition terms, procedure groups and specialties. |
| `list_procedures` | `GET /api/v1/procedures` | The 81 procedure groups with Medicare 2024 volumes and ranks among doctors' Medicare volumes. |
| `list_specialties` | `GET /api/v1/specialties` | Specialty names and ids. |
| `about_database` | `GET /api/v1/about` | Sources, build date, coverage, scoring and caveats. |

### search_doctors parameters

| Parameter | Meaning |
|---|---|
| `condition` | Disease, symptom or problem, e.g. `atrial fibrillation`. Matched to NLM MeSH terms, common names (`afib`) and clinical abbreviations (`CAD`). |
| `procedure` | Procedure or surgery, e.g. `knee replacement`, `TAVR`. See `list_procedures`. |
| `specialty` | Specialty id, name or family, e.g. `cardiology`, `ENT`, `pediatric neurology`. See `list_specialties`. |
| `city`, `state` | Practice city and state (2-letter code or full name). A city alone matches only that city; add `within_miles` for a metro area. |
| `near_zip` | One or more ZIP codes, comma-separated. |
| `within_miles` | Radius around `city` + `state` or `near_zip`, up to 100. About 25 for a metro area, 5–10 in a dense city. Can cross state lines. |
| `patient` | `adult` or `child`. `child` lists pediatric specialists and children's hospital doctors first. |
| `medicare_patient` | `true` leaves out doctors on the CMS Medicare opt-out list. |
| `accepting_new_patients` | `true` keeps doctors whose hospital website lists them as accepting new patients. Others are unknown, not "no". |
| `language` | A language other than English, as listed on the doctor's hospital website. |
| `gender` | `F` or `M` (NPI registry). |
| `text` | Free-text filter over specialty, medical school, hospitals, medical group and procedure groups. |
| `name` | Part of the doctor's name. Name searches can also return records that are probably not physicians, marked with a warning. |
| `sort` | `evidence` (default), `volume` (best Medicare procedure rank first) or `standing` (named principal investigator on industry-sponsored research first). |
| `limit`, `offset` | Up to 10 results per page; paging stops at 30 results. |

### get_doctor parameters

| Parameter | Meaning |
|---|---|
| `doctor_ids` | Up to 10 `doctor_id`s from search results (HTTP: `ids`, comma-separated). |
| `doctor_id` | One `doctor_id`. |
| `npi` | A 10-digit NPI, instead of a `doctor_id`. |
| `detail` | `summary` (default) or `full`. |

## Errors

| Status | Meaning | What to do |
|---|---|---|
| 400 | A parameter is missing or invalid | The message names what to change. |
| 401 | Sign-in needed, or the key is not valid | Follow the OAuth metadata in the `WWW-Authenticate` header, or send a valid account key. |
| 429 | Rate limit or daily doctor allowance used up | Tell the person; the message says when it resets. |
| 503 | Busy or starting | Retry shortly. |

Limits per connection: [Limits](/us/docs/limits/). What the data holds and where it comes from: [Data](/us/docs/data/).

---

Web page: https://findadoctor.si/us/docs/ · FindADoctor.si · data version public-2026-10-13.2 · Not medical advice; in an emergency, call 911.