explanation.md

NPI MCP Server Explanation

Architecture

This project implements a Model Context Protocol (MCP) server that acts as a bridge between an AI Agent and the NPPES NPI Registry.

1. Agent (Client): An AI agent (e.g., LangGraph) running in a separate environment connects to this MCP server.
2. MCP Server (npi_mcp_server): This server, running in a Hugging Face Space, exposes tools defined in the MCP specification (search_npi_providers, get_npi_provider).
3. Modal NPI API (NPI_API): The MCP server does not call the NPPES Registry directly. Instead, it forwards requests to a Modal-hosted FastAPI service (NPI_API). This Modal service handles the complex logic of querying the NPPES API and normalizing the data.
4. NPPES Registry: The ultimate source of truth for provider data.

Flow: Agent -> MCP Server (this repo) -> Modal NPI API -> NPPES Registry

Tools

1. search_npi_providers

Searches for healthcare providers.

Arguments:

• query (str): Name or organization name.
• state (str, optional): 2-letter state code.
• taxonomy (str, optional): Taxonomy code.

Example Invocation (JSON arguments):

{
  "query": "Mayo Clinic",
  "state": "MN"
}

2. get_npi_provider

Retrieves details for a specific NPI.

Arguments:

• npi (str): 10-digit NPI number.

Example Invocation (JSON arguments):

{
  "npi": "1234567890"
}