Hcp Intelligence Mcp

A production-ready Model Context Protocol (MCP) server for Healthcare Provider (HCP) intelligence, built with FastMCP and Python. Deploy target: Apify.

Tools

Tool	Description
hcp_search_physicians	Search physicians via NPPES NPI Registry
hcp_get_payment_profile	Retrieve CMS Open Payments financial data
hcp_get_territory_demographics	Fetch US Census ACS5 territory demographics
hcp_score_kol	Score a provider as a Key Opinion Leader (KOL)

---

Tool Reference

hcp_search_physicians

Search for physicians in the CMS NPPES NPI Registry.

Parameters:

Name	Type	Required	Default	Description
name	string	No	—	Provider name (first + last or last only)
specialty	string	No	—	Taxonomy/specialty description
state	string	No	—	Two-letter state abbreviation
city	string	No	—	City name
limit	int	No	10	Max results (1–200)

Returns: NPI, name, credential, specialty, practice address, phone, entity type.

---

hcp_get_payment_profile

Retrieve financial disclosure data from CMS Open Payments.

Parameters:

Name	Type	Required	Default	Description
npi	string	Yes	—	10-digit NPI number
year	int	No	2022	Program year

Returns: total payments, payment breakdown by nature, top paying companies, record count.

---

hcp_get_territory_demographics

Fetch demographic data from the US Census Bureau ACS5 survey.

Parameters:

Name	Type	Required	Description
zip_code	string	Yes	5-digit ZIP code

Variables pulled:

• B01003_001E — Total population
• B19013_001E — Median household income
• B01002_001E — Median age
• B17001_002E — Population below poverty line
• DP03_0096PE — % with private insurance
• DP03_0097PE — % with public insurance

Derived patient_population_tier:

Population	Income	Tier
> 20,000	> $75,000	Large/Affluent
> 20,000	$40,000–$75,000	Large/Mixed
> 20,000	< $40,000	Large/Underserved
≤ 20,000	> $75,000	Small/Affluent
≤ 20,000	$40,000–$75,000	Small/Mixed
≤ 20,000	< $40,000	Small/Underserved

---

hcp_score_kol

Combines payment data and territory demographics to produce a KOL score.

Parameters:

Name	Type	Required	Default	Description
npi	string	Yes	—	10-digit NPI number
year	int	No	2022	Payment program year

Returns:

• kol_score (0–100)
• payment_tier: None / Low / Mid / High / Elite
• patient_population_tier
• total_payments
• top_company
• recommendation (narrative string)

---

API Keys

API	Key Required	Environment Variable
NPPES NPI Registry	No	—
CMS Open Payments	No	—
US Census Bureau	Optional	CENSUS_API_KEY

Get a free Census API key at: https://api.census.gov/data/key_signup.html

---

Quick Start

Local (stdio)

pip install -r requirements.txt
MCP_TRANSPORT=stdio python src/server.py

Local HTTP

pip install -r requirements.txt
python src/server.py
# Server available at http://localhost:8000
# Health check: http://localhost:8000/health

Docker

docker build -f .actor/Dockerfile -t hcp-intelligence-mcp .
docker run -p 8000:8000 -e CENSUS_API_KEY=your_key hcp-intelligence-mcp

---

Apify Deployment

This server is packaged as an Apify Actor.

1. Push to your Apify account:

   $apify push
   

2. Set the CENSUS_API_KEY secret in the Apify console (optional).

3. The actor exposes an MCP-compatible HTTP endpoint at the actor's default URL.

---

Running Tests

pip install -r requirements.txt pytest pytest-asyncio
pytest

---

Health Check

GET /health
→ {"status": "ok"}

---

Architecture

src/
  server.py          # FastMCP server with all 4 tools + /health endpoint
.actor/
  actor.json         # Apify actor configuration
  Dockerfile         # Container image definition
INPUT_SCHEMA.json    # Input schema for Apify
tests/
  test_server.py     # 25+ pytest tests
requirements.txt
pytest.ini

---

Data Sources

• NPPES NPI Registry API
• CMS Open Payments API
• US Census Bureau ACS5 API

---

License

MIT