New Zealand

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. This is the New Zealand service; the United States has its own at /us/docs/. One MCP address serves both countries.

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

1. Connect

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.

With the address for every country, decide the country first: where the person wants to see a doctor, from 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, such as Hamilton, with no other clue), ask the person before searching; do not guess, and do not search every country. Pass country: "NZ" to search_doctors, list_specialties and about_database (left out, they use the United States, for clients that connected before New Zealand was added). get_doctor reads the country from the nz_ id. search_gp_practices and public_waitlist are New Zealand only and need no country. The New Zealand-only address needs no country at all.

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 guide.

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 or name. need is a condition, procedure or focus in plain English; place is a New Zealand city, suburb, or region or Health NZ district.

GET https://api-nz.findadoctor.si/api/v1/search?need=hip%20replacement&place=Christchurch

Each result has doctor_id, name, specialties, vocational scope, cities, sectors (private, public), specialist_since (the year the Medical Council first registered them as a specialist in New Zealand, when known), recognition (a New Zealand honour or a University of Auckland academic title, when there is one), match_basis (with a need: stated_focus, services_listed, shared_service_listed, specialty, specialty_for_symptom, profile_text or partial; shared_service_listed means only a hospital department or large group page the doctor is linked to lists it, so they may not do it themselves; specialty_for_symptom means the need is a symptom few doctors list, such as back pain or dizziness, and the doctor’s specialty usually sees it), place_match (with a place: city_or_address; city_in_region when you gave a region or Health NZ district and the doctor’s town is in it; address_contains, maybe a street name; or region_page_only, often a doctor visiting from elsewhere), detail_has (what get_doctor adds for this doctor) and, when there are any, warnings (for example not practising on the Medical Council register). Doctors who are only on the Medical Council register, with no Healthpoint listing, have listing: "medical_council_register_only": their name, specialty and registration dates are known, but no clinic, phone, fees or focus areas, so search the web for where they practise. When a Healthpoint listing we could not match to the register and a register-only entry share a first and last name, both carry possibly_same_person_as (the other entry’s doctor_id): they may be one doctor, so do not present them as two.

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

{
  "provider": { "name": "FindADoctor.si New Zealand", "url": "https://findadoctor.si/nz/", "data_version": "nz-public-2026-10-15.5" },
  "before_answering": "This is the free short list: who the doctors are, not the evidence. Before recommending anyone, call get_doctor …",
  "total_matches": 26,
  "offset": 0,
  "results": [
    {
      "rank": 1,
      "doctor_id": "nz_4k9m2x7qph3t",
      "name": "Dr Example Doctor",
      "kind": "Specialist",
      "specialties": ["Orthopaedics"],
      "vocational_scope": "Orthopaedic Surgery",
      "cities": ["Christchurch", "Timaru"],
      "sectors": ["private"],
      "match_basis": "stated_focus",
      "detail_has": ["7 focus areas they list", "clinic phone numbers and addresses", "Medical Council register entry"]
    }
  ],
  "next_step": "Call get_doctor with doctor_ids (up to 10 at once) for the doctors you are considering. …",
  "note": "Confirm phone numbers, fees, insurer status and availability with the clinic before booking. Not medical advice; in an emergency call 111."
}

Results are ranked first by how directly the doctor’s own listing matches the need: doctors who list all its words, then (for a symptom) specialty_for_symptom, then doctors who list some of the words, then words only in profile text. Within each, results are ranked by place_match; with experienced_first=true, by specialist_since (earliest first) after that. Doctors only on the register come after all listed doctors. Not by quality or outcomes: years as a specialist are seniority, not skill. need_note names the specialties added for a symptom (a grouping by common sense, not a diagnosis), or says that no doctor lists all the words. When you search a town or suburb, place_note says how many more doctors match with the wider region as the place (in another town of the region, or only on Healthpoint’s region page, often public-hospital doctors whose page names only the hospital) and which place to search to include them. With specialty, specialty_read_as lists the specialty names searched, and specialty_note explains when a child-specific wording was searched as the general specialty with child=true. 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-nz.findadoctor.si/api/v1/doctors?ids=nz_4k9m2x7qph3t,nz_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.

Each doctor can have: specialties, title and qualifications; focus areas and subspecialties they list; languages; whether their services see children; every private and public service with clinic addresses, phone numbers and websites, the procedures and conditions the service lists, fee categories, ages, hours and how to get referred; whether a service or the doctor’s own page says Southern Cross Affiliated Provider or nib First Choice; the Medical Council register entry (status, scope of practice, conditions, practising certificate dates); and source links with read dates. The doctor’s own profile text is not reproduced: give the person the Healthpoint link (sources.healthpoint).

Phone numbers, fees and insurer status change. Tell the person to confirm them with the clinic, and cover with their insurer (often prior approval), before booking.

Each doctor can also have experience: every vocational scope with the date it was granted and years since, years as a specialist in New Zealand (provisional scopes not counted), earliest registration date on the register entry, primary medical degree year, New Zealand honours (with the list and citation), University of Auckland academic title and hospital appointments, and an approximate count of papers with a New Zealand affiliation in Europe PMC (with a link to the list). Seniority signals, not a measure of quality.

4. General practices

search_doctors is for specialists: general practitioners are left out unless you ask for the specialty General Practice. To find a GP, search practices instead:

GET https://api-nz.findadoctor.si/api/v1/gp-practices?place=Hamilton&enrolling=yes&age=34

Each practice has enrolling (yes, restricted, no, does not apply for urgent care, or unknown), its own note on who it takes, locations with phone numbers, the first fee table on the page, usually for enrolled patients (or with age, just the row for that age), online booking, hours and the GPs listed there. Each result’s kind says what sort of practice it is (for example nurse-led, online, or a student health clinic). kind=urgent_care finds accident and urgent medical care and after-hours clinics. Practices are not doctors: searching them does not count toward the daily doctor allowance. Enrolment and fees change often, so tell the person to phone the practice.

5. Public waiting lists

GET https://api-nz.findadoctor.si/api/v1/waitlist?specialty=Orthopaedic&district=Canterbury

Health NZ figures by district and specialty, for the latest month and the same month a year earlier: people waiting for a first specialist assessment and for planned treatment, and the share waiting over 120 days. Useful when the person is weighing public against private care. Health NZ names some specialties differently in the two lists (for example Orthopaedics for a first assessment and Orthopaedic Surgery for treatment); asking for either returns both.

Tools

search_doctors parameters

get_doctor parameters

A doctor keeps the same doctor_id when the database is rebuilt, including when a doctor who was only on the Medical Council register is later found on Healthpoint. If an id does change, the old id still returns the doctor, and the reply’s id_changed gives the current id to use from then on.

search_gp_practices parameters

public_waitlist parameters

Errors

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