# Quickstart

Two calls: search for a short list, then open the evidence for the doctors you are seriously considering. For surgery or a procedure, a third tool shows which hospitals and clinics do it most. The MCP server and the HTTP API have the same tools and return the same JSON. This is the France service. The United States and New Zealand have their own, at [/us/docs/](/us/docs/) and [/nz/docs/](/nz/docs/), and one MCP address serves all three.

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

## 1. Connect

| | Address |
|---|---|
| MCP (Streamable HTTP), every country: pass `country: "FR"` | `https://api.findadoctor.si/mcp` |
| MCP (Streamable HTTP), France only | `https://api-fr.findadoctor.si/mcp` |
| HTTP API | `https://api-fr.findadoctor.si/api/v1/…` (GET, JSON) |
| OpenAPI 3.1 (parameters and response fields) | [https://api-fr.findadoctor.si/openapi.json](https://api-fr.findadoctor.si/openapi.json) |
| MCP server card | [https://api-fr.findadoctor.si/mcp/server-card](https://api-fr.findadoctor.si/mcp/server-card) |
| Guide for agents | [https://api-fr.findadoctor.si/llms.txt](https://api-fr.findadoctor.si/llms.txt) |

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

### Decide the country first

With the address for every country, first work out where the person wants to see a doctor. Use the place they mention, or what you know about where they live.

- **If nothing settles it** (no place given, or a place name used in more than one country, with no other clue), ask the person before searching. Do not guess, and do not search every country.
- **Tools that take `country`:** pass `country: "FR"` to `search_doctors`, `list_specialties` and `about_database`. Left out, they use the United States, for clients that connected before France was added.
- **Tools that don't:** `get_doctor` reads the country from the `fr_` id. `hospital_procedure_volumes` is France only.
- **France-only connections:** the France-only MCP address needs no `country` at all. Neither does the HTTP API below: it is France only, and sending `country` is an error.

### Add it to your client

**In Claude** (Free, Pro, Max, Team and Enterprise; the Free plan allows one custom connector):

1. Go to Customize → Connectors → + Add → Add custom connector.
2. Enter a name and the MCP URL, then click Continue. Under Authentication choose No sign in (or add an account key under Request headers as Authorization: Bearer), then Add.
3. On Team and Enterprise, an Owner first adds it under Organization settings → Connectors; members then Connect it.
4. Turn it on in a chat with + → Connectors.

See [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:

1. Go to Plugins → + → Add custom MCP server.
2. Enter a name and the MCP URL, and set authentication. Choose no authentication.
3. Create it as a plugin and install it.
4. In a chat, type @ and pick it.

See [OpenAI's guide](https://developers.openai.com/plugins/deploy/connect-chatgpt).

**In Claude Code, Codex CLI, Gemini CLI and other MCP clients**: add a remote (Streamable HTTP) MCP server with the URL above.

## 2. Search

Give at least one of `need`, `specialty`, `place`, `name` or `hospital_finess`.

- `need` is a condition, procedure or focus, in French or English. Common English words are also searched in French, so `knee replacement` finds `prothèse genou`.
- `place` can be:
  - a city (`Paris` includes every arrondissement);
  - a postcode (`75015`);
  - an arrondissement (`Paris 15`, `Lyon 3e`);
  - a département number (`69`, `2A`);
  - or a practice or hospital name.

  It is a text match on practice addresses, not a distance search.

```text
GET https://api-fr.findadoctor.si/api/v1/search?need=endom%C3%A9triose&place=Lyon
```

### What each result has

- **Who:** `doctor_id`, `name`, `gender`, `specialties` (French, as registered) and `specialties_en`.
- **Where:** `places`, up to 3 practices, with those matching `place` first.
- **Fees:** `fee_sectors`, the Assurance Maladie category:
  - `Secteur 1` = standard fees;
  - `Secteur 2` = may charge extra;
  - `Non conventionné` = not contracted, little reimbursed.

  `optam` means the doctor has agreed to limit extra fees.
- **`match_basis`**, with a need, says how the doctor's own data matches it:

  | Value | Meaning |
  |---|---|
  | `stated_expertise` | the expertise or procedures the doctor states on a profile page |
  | `official_competence` | an official competence or university diploma in the register |
  | `hospital_department_or_training` | a hospital department, role or training |
  | `several_fields` | the words are spread over several of these |
  | `specialty` | the specialty name |
  | `specialty_usually_treats` | the need is a condition few doctors list, and the doctor's specialty usually treats it |
  | `partial` | some of the words |

- **`register`:**
  - `rpps` = in the official register;
  - `ameli_only` = only in the Assurance Maladie directory;
  - `website_only` = a hospital page we could not match to either register.
- **Other fields:** `warnings` (for example barred from practising), when there are any, and `detail_has`, which says what `get_doctor` adds for this doctor.

A trimmed example (the doctors' names and ids are made up; `…` marks shortened text):

```json
{
  "provider": { "name": "FindADoctor.si France", "url": "https://findadoctor.si/fr/", "data_version": "fr-public-2026-10-16.3" },
  "before_you_answer": "This is the free short list: who the doctors are, not the evidence. Before recommending anyone, call get_doctor …",
  "count": 10,
  "more": true,
  "offset": 0,
  "doctors": [
    {
      "doctor_id": "fr_4k9m2x7qph3t",
      "name": "Dr Example Doctor",
      "gender": "female",
      "specialties": ["Gynécologie-obstétrique"],
      "specialties_en": ["Obstetrics and gynaecology"],
      "places": ["Cabinet médical, 69006 Lyon", "Clinique Exemple, 69003 Lyon"],
      "fee_sectors": ["Secteur 2"],
      "optam": true,
      "match_basis": "stated_expertise",
      "register": "rpps",
      "detail_has": ["stated_expertise", "procedures", "university_diplomas", "practices_with_phone_and_fee_category"]
    }
  ],
  "need_note": "…"
}
```

### How results are ordered

**With a need**, results are ranked by how directly the doctor's own data matches it, in the order of the `match_basis` table above: stated expertise first, down to some of the words. **Without a need**, doctors with more data (stated expertise, official competences, profile pages) come first, then the rest in a fixed shuffled order. Results are never ranked by quality, outcomes, fees or industry links.

### Notes in the reply

- `need_note` says when no doctor lists all the words of the need, and which specialties were added for a condition few doctors list.
- `place_note` says when a place matched several départements or was read as a practice name.
- `filter_note` says when a filter only knows doctors with a profile page.
- `hospital_note` explains a `hospital_finess` search.

### Paging

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-fr.findadoctor.si/api/v1/doctors?ids=fr_4k9m2x7qph3t,fr_8w2c5n1kd7ra
```

Up to 10 doctor ids per call. Without an account, each network address can open 5 different doctors' evidence a day; with an account key (by invitation), 100. Opening the same doctor again the same day is free. Doctors that do not fit in one reply come back under `not_returned_yet`, already counted, so ask again for them at no extra cost.

### What each doctor can have

- **From the register:**
  - the RPPS number (`rpps`; check it on annuaire.sante.fr);
  - official specialties;
  - official extra competences;
  - university diplomas (DU/DIU);
  - practice modes.
- **Every practice** (`practices`), from the RPPS register and the Ameli directory:
  - address and phone;
  - setting and role;
  - fee category (Secteur 1 or 2, OPTAM);
  - the hospital's FINESS number.
- **From a Maiia or hospital page**, when the doctor has one:
  - stated expertise and the procedures offered;
  - hospital department and role;
  - qualifications and languages;
  - consultation fees;
  - online booking, video consultations, and whether online booking is open to new patients.

  The source pages are listed with their read dates.
- **`industry_links`:** Transparence Santé declarations by drug and device companies (agreements, benefits, payments), grouped by year, kind, company and purpose and shown as declared. They are not evidence of expertise or wrongdoing. Licence CC BY-NC-SA 4.0: if you pass them on, keep the source, date and licence, and do not use them commercially.

The doctor's own profile text is not reproduced; give the person the source page link (`sources`).

> Fees, phone numbers and availability change. Tell the person to confirm them with the practice, and to book on Doctolib or with the practice.

## 4. Hospital procedure volumes

```text
GET https://api-fr.findadoctor.si/api/v1/procedure-volumes?procedure=cataract&place=Lyon
```

From Open CCAM (ATIH): which hospitals and private clinics performed the procedure most, per year, 2021–2025. Each hospital comes with its FINESS number, the acts counted by year and by CCAM code, and the share done as day cases.

- **Check the codes.** The reply lists the CCAM acts it added up (`acts_counted`), so check they fit the need, or pass exact `codes` over MCP to narrow it. For an aneurysm or a stent, say where (brain, aorta, heart or carotid).
- **What is counted.** Only hospital stays and day cases. Procedures done in a doctor's office or a hospital outpatient clinic are not counted, and a site with fewer than 11 stays for an act is not listed.
- **Per hospital, not per surgeon.** To find doctors there, search with `hospital_finess` for salaried hospital doctors. In private clinics, most surgeons are self-employed (libéral) and registered at their own office, so search the clinic's postcode with the specialty instead.

Hospital volumes are free: they do not count toward the daily doctor allowance.

## Tools

| MCP tool | HTTP | What it does |
|---|---|---|
| `search_doctors` | `GET /api/v1/search` | Free short list for a need, specialty, place, name or hospital. |
| `get_doctor` | `GET /api/v1/doctors?ids=…` or `/api/v1/doctors/{doctor_id}` | Evidence for up to 10 doctors. Counted per day. |
| `hospital_procedure_volumes` | `GET /api/v1/procedure-volumes` | Which hospitals and clinics perform a procedure most (Open CCAM). Not counted. |
| `list_specialties` | `GET /api/v1/specialties` | Specialty names (official French and English) with doctor counts. |
| `about_database` | `GET /api/v1/about` | Sources, licences, read dates, coverage counts and known gaps. |

### search_doctors parameters

| Parameter | Meaning |
|---|---|
| `need` | Condition, procedure or focus, in French or English, e.g. `endométriose`, `prothèse genou`, `knee replacement`, `cataract`. Matched against the expertise and procedures doctors state, their official competences and university diplomas, hospital departments and roles, and specialty. |
| `specialty` | French or English, e.g. `cardiologie`, `dermatology`, `pédiatre`, `ORL`, `GP`, `généraliste` (see `list_specialties`). |
| `place` | City, postcode, arrondissement (`Paris 15`), département number (`69`, `2A`) or a practice or hospital name. A text match, not a distance search. |
| `name` | The doctor's name or part of it, to check a named doctor. |
| `gender` | `female` or `male`. Only when the person asks. From the register's civil title; recorded for almost all doctors. |
| `language` | A language other than French, e.g. `English`, `Arabic`. Only known for doctors with a profile page (about 1,840 list one); many others speak it too. |
| `fee_sector` | `any` (default), `secteur_1` (standard fees), `secteur_1_or_optam` (standard fees, or extra fees the doctor agreed to limit) or `secteur_2` (may charge extra). A doctor is kept if any practice has it; check each practice in `get_doctor`. Most hospital-only doctors have no category. |
| `online_booking` | `true` keeps doctors whose Maiia or hospital page shows online booking (Doctolib is not covered). |
| `teleconsultation` | `true` keeps doctors offering video consultations on Maiia. |
| `hospital_finess` | A hospital site's FINESS number (from `hospital_procedure_volumes`): doctors whose register address is that site, mostly salaried hospital doctors. |
| `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`. |

A doctor keeps the same `doctor_id` when the database is rebuilt.

### hospital_procedure_volumes parameters

| Parameter | Meaning |
|---|---|
| `procedure` | The procedure in English or French (`cataract`, `knee replacement`, `prothèse genou`, `coloscopie`), or CCAM codes. |
| `codes` | MCP only: exact CCAM codes to add up, instead of `procedure`, to narrow it (e.g. `BFGA427`). |
| `place` | City, postcode, arrondissement, département number, or a hospital FINESS number. Without it, all of France is ranked. |
| `year` | 2021–2025; default the latest year. |
| `limit`, `offset` | Up to 20 hospitals per page; paging stops at 120. |

## Errors

| Status | Meaning | What to do |
|---|---|---|
| 400 | A parameter is missing or invalid | The message names what to change. |
| 401 | The account key is not valid | Send a valid key, or none. |
| 403 | A web page on another site asked for doctor details from a visitor's browser (`cross_site`) | Call from your agent or server, not from another site's page. |
| 404 | No doctor with that id | Use a `doctor_id` from a search. |
| 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](/fr/docs/limits/). What the data holds and where it comes from: [Data](/fr/docs/data/).

---

Web page: https://findadoctor.si/fr/docs/ · FindADoctor.si France · data version fr-public-2026-10-16.3 · Not medical advice; in an emergency, call 15 (SAMU) or 112.