API DOCUMENTATION / DOCTORS CONNECTOR
Doctors connector
Find U.S. doctors, clinics, hospitals and nursing homes by specialty and place.
What it is
Find U.S. doctors, practices, hospitals and nursing homes by specialty and place: practice address, NPI, Medicare enrolment, telehealth, gender, and hospital affiliations. Built from public CMS data (NPPES, Medicare Care Compare) and state licence files. Directory information only: it is not medical advice and does not know whether a doctor is accepting new patients. Preview data: coverage is partial and fields may change. Every record links to its sources; check anything important at the source.
Connect
Endpoint: https://doctors-mcp.headcountlabs.com/mcp/public/doctors. It uses Streamable HTTP, is stateless and takes POST requests only. No account or key is needed. The data is read-only and U.S. only.
Example prompts
- Female pediatricians within 5 km of Brooklyn Heights who offer telehealth.
- Look up NPI 1003000126.
- Which hospitals is Dr. Jane Smith in Chicago affiliated with?
- Dermatologists near Lincoln Park, Chicago, who take Medicare.
- Which hospitals is this cardiologist affiliated with?
Tools
These are the tools the endpoint returns from tools/list. A * marks a required input.
| Tool | What it does | Inputs |
|---|---|---|
find_doctors | Find doctors, nurse practitioners, dentists and other clinicians whose practice location is near a point, nearest first. | lat*, lon*, radius_m, walk_minutes, specialty, taxonomy, q, accepts_medicare, telehealth, gender, entity_type, limit, cursor, fields |
find_facilities | Find Medicare-certified nursing homes and hospitals (CMS) by CMS Certification Number (ccn), name prefix (q), state and city, or near a point (nearest first). | lat, lon, radius_m, ccn, q, state, city, limit, cursor, fields |
get_doctor | One doctor, nurse practitioner, dentist or other clinician, or a group practice, by UUID or NPI: credential, specialties, NUCC taxonomy, practice addresses and phones, whether they are enrolled in Medicare and accept assignment, telehealth, and how many hospitals and groups they are affiliated with (doctor_affiliations lists them). | id, npi, fields |
get_facility | One Medicare-certified hospital or nursing home by UUID or CMS Certification Number: name, kind, address, phone, certified beds and CMS overall star rating. | id, ccn, fields |
search_doctors | Find a doctor or other clinician by name (last name, or first and last name, e.g. | q*, state, city, specialty, entity_type, limit, cursor, fields |
doctor_affiliations | The hospitals and other facilities a clinician is affiliated with and the group practices they bill through (CMS Doctors and Clinicians), by clinician UUID or NPI. | id, npi, fields |
facility_clinicians | Clinicians affiliated with a hospital or nursing home (by UUID or CCN) or billing through a group practice (by UUID or NPI), alphabetical, optionally only one specialty word (e.g. | id, ccn, npi, specialty, limit, cursor, fields |
specialty_counts | Count clinicians with a practice location near a point: total, top 25 specialties, how many are in Medicare and how many offer telehealth. | lat*, lon*, radius_m, walk_minutes |
get_doctor_record | The full stored record of one clinician, group practice or facility by its UUID (the id returned by find_doctors, search_doctors, find_facilities, get_doctor, get_facility, doctor_affiliations or facility_clinicians): every field with the source it came from. | id* |
Every tool only reads public records and changes nothing. Pages hold at most 100 items, 20 by default. fields trims each item. Record IDs are for follow-up calls only.
Limits
Rate limits: 20 tool calls per minute per conversation (ChatGPT openai/session or the Mcp-Session-Id issued at initialize) and 600 requests per minute per network; over the limit, a tool call returns isError with the wait time and HTTP requests get 429 with Retry-After.
Responses are capped at 60,000 characters (items trimmed from the end, meta.truncated set).
Errors
A failed call returns an MCP tool result with isError: true and the API error JSON (invalid_parameter 400 naming the parameter, not_found 404, invalid_cursor 400, query_timeout 503 asking for a narrower search, read_only 503). Unknown tools and record paths outside this index are refused with a message. JSON-RPC errors: -32700 parse error, -32601 unknown method. HTTP 405 for GET/DELETE, 413 over 256 KB.