npi-providers-mcp-server

Npi Lookup Taxonomy

npi_lookup_taxonomy

Read-onlyIdempotent

Resolve and browse the NUCC Healthcare Provider Taxonomy — the specialty code set NPPES uses — fully offline (bundled). Mode resolve turns a plain-language specialty (e.g. "cardiologist", "heart doctor") into matching active taxonomy entries, excluding codes NUCC marks inactive; mode get returns the full entry for an exact code, including NUCC's Notes; mode browse walks the hierarchy (grouping → classification → specialization), optionally filtered by grouping and by NPI section (Individual/NPI-1 vs Non-Individual/NPI-2). Every entry carries its status, and an inactive code names its replacement when NUCC gives one; get and browse still return inactive codes. A resolved entry's specialization, or its classification when specialization is absent, maps directly to npi_search_providers.taxonomy_description.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The limit that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of entries returned.
`notice`	No	Guidance — how to page a truncated result with skip, or how to broaden when nothing matched.
`matches`	No	Matching taxonomy entries. For mode "get" this is the single requested entry; for "resolve"/"browse" it is the ranked/sorted matches up to limit.
`truncated`	No	True when the list was capped at `limit` (more entries may match).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 25, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: A get code matched no taxonomy entry, or a resolve query matched no active one (the message names any inactive codes it matched). `missing_argument`: The required query or code was present but blank after trimming. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_match`: A get code matched no taxonomy entry, a resolve query matched no active one (the message names any inactive codes it matched), or a resolve query was made only of generic words (\"doctor\", \"M.D.\", \"specialist\") that name no specialty. `missing_argument`: The required query or code was present but blank after trimming. Other values are possible when a failure originates below the handler."

Changed5 schema fields changedSep 24, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_match`: A resolve query or get code matched no taxonomy entry. `missing_argument`: The required query or code was present but blank after trimming. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `no_match`: A get code matched no taxonomy entry, or a resolve query matched no active one (the message names any inactive codes it matched). `missing_argument`: The required query or code was present but blank after trimming. Other values are possible when a failure originates below the handler."

addedOutput schema / properties / matches / items / properties / notes

Added value: +{
+  "description": "NUCC Notes: sources, revision history, and status remarks. Returned by mode \"get\" only, when NUCC records a note.",
+  "type": "string"
+}

addedOutput schema / properties / matches / items / properties / replacedBy

Added value: +{
+  "description": "For an inactive code, the active replacement code NUCC names, when it names one.",
+  "type": "string"
+}

addedOutput schema / properties / matches / items / properties / status

Added value: +{
+  "description": "NUCC status. Inactive codes are no longer maintained: mode \"resolve\" excludes them, while \"get\" and \"browse\" return them.",
+  "enum": [
+    "active",
+    "inactive"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / matches / items / required

Previous value: -[
-  "code",
-  "grouping",
-  "classification",
-  "displayName",
-  "section"
-]New value: +[
+  "code",
+  "grouping",
+  "classification",
+  "displayName",
+  "section",
+  "status"
+]

Changed8 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / oneOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "limit": {
+        "default": 20,
+        "description": "Maximum matching entries to return (1–50).",
+        "maximum": 50,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "mode": {
+        "const": "resolve",
+        "description": "Resolve a plain-language specialty to taxonomy codes.",
+        "type": "string"
+      },
+      "query": {
+        "description": "The plain-language specialty term to resolve, e.g. \"pediatric cardiologist\".",
+        "minLength": 1,
+        "type": "string"
+      },
+      "skip": {
+        "default": 0,
+        "description": "Entries to skip before the page (0–1000). Keep the same query and limit, then raise skip by limit each call.",
+        "maximum": 1000,
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "mode",
+      "query"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "description": "The exact NUCC taxonomy code, e.g. \"207RC0000X\".",
+        "minLength": 1,
+        "type": "string"
+      },
+      "mode": {
+        "const": "get",
+        "description": "Fetch one exact taxonomy entry by code.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "mode",
+      "code"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "grouping": {
+        "description": "Filter to a top-level grouping by case-insensitive substring, e.g. \"physicians\".",
+        "type": "string"
+      },
+      "limit": {
+        "default": 20,
+        "description": "Maximum entries to return (1–50).",
+        "maximum": 50,
+        "minimum": 1,
+        "type": "integer"
+      },
+      "mode": {
+        "const": "browse",
+        "description": "Browse the taxonomy hierarchy.",
+        "type": "string"
+      },
+      "section": {
+        "description": "Filter by NPI section: Individual (NPI-1) or Non-Individual (NPI-2).",
+        "enum": [
+          "Individual",
+          "Non-Individual"
+        ],
+        "type": "string"
+      },
+      "skip": {
+        "default": 0,
+        "description": "Entries to skip before the page (0–1000). Keep the same filters and limit, then raise skip by limit each call.",
+        "maximum": 1000,
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "mode"
+    ],
+    "type": "object"
+  }
+]

removedInput schema / properties

Removed value: -{
-  "code": {
-    "description": "For mode \"get\": the exact NUCC taxonomy code (e.g. \"207RC0000X\").",
-    "type": "string"
-  },
-  "grouping": {
-    "description": "For mode \"browse\": filter to a top-level grouping by case-insensitive substring (e.g. \"physicians\").",
-    "type": "string"
-  },
-  "limit": {
-    "default": 20,
-    "description": "Maximum entries to return for resolve/browse (1–50). Ignored for get.",
-    "maximum": 50,
-    "minimum": 1,
-    "type": "integer"
-  },
-  "mode": {
-    "description": "resolve: plain term → codes. get: exact code → entry. browse: walk the hierarchy.",
-    "enum": [
-      "resolve",
-      "get",
-      "browse"
-    ],
-    "type": "string"
-  },
-  "query": {
-    "description": "For mode \"resolve\": the plain-language specialty term to resolve (e.g. \"pediatric cardiologist\").",
-    "type": "string"
-  },
-  "section": {
-    "description": "For mode \"browse\": filter by NPI section — Individual (NPI-1) or Non-Individual (NPI-2).",
-    "enum": [
-      "Individual",
-      "Non-Individual"
-    ],
-    "type": "string"
-  },
-  "skip": {
-    "default": 0,
-    "description": "Entries to skip before the page, for paging past a truncated resolve/browse result (0–1000). Keep the same query/filters and limit, raise skip by limit each call. Ignored for get.",
-    "maximum": 1000,
-    "minimum": 0,
-    "type": "integer"
-  }
-}

removedInput schema / required
```
Removed value: -[
-  "mode"
-]
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "matches"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_match`: A resolve query or get code matched no taxonomy entry. `missing_argument`: The required query or code was present but blank after trimming. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_match",
+            "missing_argument"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required
```
Removed value: -[
-  "matches"
-]
```

Changed2 schema fields changedJul 11, 2026

addedInput schema / properties / skip

Added value: +{
+  "default": 0,
+  "description": "Entries to skip before the page, for paging past a truncated resolve/browse result (0–1000). Keep the same query/filters and limit, raise skip by limit each call. Ignored for get.",
+  "maximum": 1000,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing matched — suggests broadening or browsing the hierarchy."New value: +"Guidance — how to page a truncated result with skip, or how to broaden when nothing matched."

First observedJun 16, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false; the description adds significant context beyond these. It discloses that the tool works offline (bundled), that it excludes inactive codes in `resolve` but includes them in `get`/`browse`, and that inactive entries may name replacements. It also explains the status field and the linkage to NPI sections, providing richer behavioral details than annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive yet tightly written, covering all modes, behaviors, and usage guidance in a single paragraph. It front-loads the core purpose and mode descriptions, then adds details in a logical order. Every clause earns its place, providing high information density without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple modes, hierarchical data, relations to NPI sections) and the presence of an output schema, the description is exceptionally complete. It explains mode-specific behaviors, edge cases (inactive codes, replacements), and how to map results to sibling tools. The output schema likely covers return fields, so the description does not need to restate them, allowing the description to focus on decision-making and behavioral nuances.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. However, the description adds critical meaning: it explains the purpose of each mode's parameters (e.g., mode-specific query vs code vs grouping/section), clarifies the `section` parameter's relationship to NPI-1/NPI-2, and provides concrete examples. It goes beyond the schema by elaborating on the hierarchy (grouping → classification → specialization) and the mapping logic for resolved entries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: resolving and browsing the NUCC taxonomy code set. It enumerates three distinct modes (`resolve`, `get`, `browse`) with specific actions and examples, making it immediately clear what the tool does. It also differentiates from siblings by mentioning its use in `npi_search_providers.taxonomy_description`, establishing a distinct role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use each mode: `resolve` for plain-language terms, `get` for exact codes, and `browse` for hierarchy exploration. It also references sibling `npi_search_providers` and explains how to map resolved entries to its taxonomy_description field, giving clear routing context. It explicitly notes that `get` and `browse` return inactive codes, which helps the agent choose the right mode based on need.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All npi-providers-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.