DocNexus MCP — Tool Reference

A read-only MCP connector that lets Claude query DocNexus Advanced Search on behalf of a logged-in platform user. 11 tools · read-only · capped at 10 rows/query · AWS Cognito auth · backend advanced-search.docnexus.ai.

All tools were verified live against production Advanced Search.

Sample queries supported today

Shared clinical filter set

Search tools accept these optional clinical filters (resolve codes/names via lookup_values first):

• diagnoses[] — ICD codes
• procedures[] — CPT/HCPCS codes
• drugs[] — brand names
• year_min, year_max
• patient_gender[] — M | F | O | U
• patient_age_min, patient_age_max

Plus limit / offset (hard-capped at 10 rows).

Tools

* = required.

lookup_values — resolver (call first)

Resolve free-text terms to canonical DocNexus values.

• *kind — diagnosis | procedure | drug | specialty | condition | system | hospital | executive_system | executive_title
• *query — string
• limit — int ≤50
• Returns: { values: string[] } — e.g. ["c830","c8300"] or ["Keytruda"]

find_hcps — individual providers (Type-1 NPIs)

• specialties[], states[] (full name, e.g. "California"), cities[], hospital_names[], system_names[], conditions[]
• gender (M|F), first_name, last_name, deciles[] (1–10; require a clinical filter), type_1_npis[]
• • clinical filter set
• Returns: provider rows — type_1_npi, name, gender, cities, states, specialties, affiliations, phone, email, socials, payment & trial counts, patient count, docnexus_url

find_kols — key opinion leaders

Find KOLs for a condition / therapeutic area. Resolve the condition via lookup_values kind=condition first.

• *condition — condition / therapeutic area (e.g. "breast cancer")
• emerging — false (default): established KOLs tagged by expertise tier; true: rising-star KOLs ranked by publications + clinical trials
• tiers[] — global | expert (established mode only; default both)
• specialties[], states[] (established mode only)
• Returns: KOL provider rows — established: tagged by expertise tier; emerging: ranked by research footprint

find_executives — leadership

Separate vocabulary — resolve via lookup_values executive_system / executive_title. No clinical filters.

• standard_titles[], departments[], position_levels[], system_names[], facility_names[], firm_types[], states[], cities[]
• Returns: executiveName, title, standardTitle, department, email, direct phone, LinkedIn

hcp_claim_volume — top providers, ranked

• metric — claims (default) | patients
• specialties[], states[], system_names[], hospital_names[], type_1_npis[]
• • clinical filter set (required)
• Returns: provider rows ordered high→low with group_1_claim_count or group_1_patient_count

org_claim_volume — top organizations, ranked

Orgs use 2-letter state codes (e.g. "CA"), not full names.

• metric — claims (default) | patients
• states[], cities[], org_names[], org_types[]
• • clinical filter set (required)
• Returns: org rows ranked with name, type, address, linked orgs, claim/patient counts

market_volume — total market size

• *metric — claims | patients
• • clinical filter set (required)
• Returns: { claim_count } or { patient_count }

patient_volume_trend — time series

• • clinical filter set (required), year_min, year_max
• Returns: one row per year — { year, patient_count }

find_referrals — referral network (platform redirect)

Referral-network analysis is an interactive view that lives in the DocNexus platform. This tool doesn't run the query here — calling it returns a link to open the analysis in platform.docnexus.ai. It exists so referral questions get a fast, branded pointer instead of a ~15s query, and to funnel that intent to the platform.

• topic (optional) — what the user wants to explore; used only to frame the pointer
• Returns: { message, url: "https://platform.docnexus.ai" }

hcp_affiliations — a provider's org ties over time

• *type_1_npis[], year_min, year_max, current_only
• Returns: affiliation rows — systems/hospitals per NPI, by period

opportunity_map — targeting / whitespace map (platform redirect)

Opens the DocNexus platform's interactive Opportunity Map pre-filtered to a market. Like find_referrals, this doesn't run in-chat — it returns a deep link to open the map in platform.docnexus.ai. Driven by codes + org name, not free text (no specialty/condition-name filter).

• diagnoses[] / procedures[] / drugs[] — resolve via lookup_values (codes only; brand names for drugs)
• org_search — fuzzy health-system/hospital/org name (one term; not conditions/specialties/drugs)
• states[] (full names), organization_types[], postal_codes[]
• At least one of diagnoses / procedures / drugs / org_search required — states or postal codes alone render an empty map
• Returns: { message, url: "https://platform.docnexus.ai/opportunity-map?…" }

Response envelope

// search tools
{ "rows": [ /* ≤10 records */ ], "row_count": 10, "sql": "SELECT …", "pagination": { "limit": 10, "offset": 0 }, "hint": "…" }
// lookup_values
{ "values": ["c830", "c8300"] }
// errors (isError: true)
{ "error": "…", "details": {}, "hint": "…" }

sql is the exact query run (transparency). hint appears on empty results. 401 → re-auth, 429 → retry, timeout → narrow filters.

Notes & constraints

• Read-only, capped at 10 rows — a discovery/"taste" surface; deeper lists, exports, opportunity maps, and saved lists live in platform.docnexus.ai. Deliberate, not a limitation.
• Runs as the logged-in platform user — Claude authenticates through Cognito; the user's token is forwarded to Advanced Search unchanged. No separate credentials, no broader access.
• Unfiltered queries refused — every search needs ≥1 filter; volume/trend tools need a clinical filter.
• find_referrals and opportunity_map redirect to the platform — those views are interactive (and the underlying queries slow), so rather than a slow or non-visual response each tool returns a deep link to platform.docnexus.ai. Keeps the connector feeling fast and funnels that intent to the full product.
• Two vocabularies differ and Claude is told which is which: claims specialties & provider states are UPPERCASE, org states are 2-letter codes.
• Everything (except the referral redirect) is under a 60s timeout, and typical questions land at 2–3s.