API

MCP server for U.S. dental provider data

270,000+ U.S. dentists across 41 states + DC, plus 49 Medicaid programs state Medicaid fee schedules. Four read-only tools, citation envelope on every response, two billing rails. Compatible with Claude.ai, Cursor, Cline, Continue, ChatGPT, and any MCP-aware client.

Connect from Claude.ai x402 per-call rail

Use Cases Live Demo Tools Billing Pricing Endpoint Response Validation Rate Limits Discovery Connect FAQ References Full API reference →

TL;DR for agents reading this page

Streamable HTTP MCP server at https://mcp.providersignal.com/mcp. Four tools (lookup_provider_by_npi, search_providers, get_dso_affiliation, get_territory_summary) wrap the ProviderSignal /api/v1/agent/* REST API. Authenticate with Authorization: Bearer ps_live_<key> for subscription billing, or pay per call in USDC on Base mainnet via x402. Discovery manifest at /.well-known/mcp.json. Every response carries a citation envelope with source attribution and a confidence score.

curl - 30-second integration

curl -X POST https://mcp.providersignal.com/mcp \ -H "Authorization: Bearer ps_live_<your_key>" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Four tools, dozens of agent workflows

Each card below is a real prompt a buyer might give an AI agent that has this MCP server connected. The tool pills show how the workflow maps back to the underlying calls.

Supply rep

"Find dentists in Dallas County whose licenses expire in the next 6 months and aren't affiliated with a DSO."

search_providersget_dso_affiliation

Outcome: Renewal-window call list, filtered to rep-direct buyers (no chain procurement gates).

DSO biz dev

"Show me Texas markets with the highest density of solo independents over 55, and tell me how many practices each ZIP code has."

get_territory_summarysearch_providers

Outcome: Acquisition heatmap of retirement-risk independents, ranked by ZIP-level concentration.

Practice broker

"Look up NPI 1376155820 and tell me if there are any disciplinary actions, OIG exclusions, or anomalies I should disclose to a buyer."

lookup_provider_by_npi

Outcome: One-shot due-diligence check before engaging a seller. Citation envelope shows the source date and confidence score for legal defensibility.

AI agent / app builder

"Cross-reference these 200 NPI numbers from a CRM export and flag any that have changed addresses, expired, or moved into a DSO since last quarter."

lookup_provider_by_npiget_dso_affiliation

Outcome: Bulk freshness check that turns a stale CRM into a maintained source of truth. Per-call USDC billing fits batch jobs cleanly.

A 2-tool answer in a real Claude.ai conversation

The flow below is what a connected client renders for the user. The MCP server calls the tools, the agent formats the final answer.

1. User prompt

"How saturated is the dental market in Travis County, Texas, and what share of practices belong to a DSO?"

2. Agent calls `get_territory_summary`

tool call

{ "method": "tools/call", "params": { "name": "get_territory_summary", "arguments": { "state": "TX" } } }

tool result

{ "data": { "state": "TX", "total_providers": 21847, "dso_flagged": 4982, "dso_penetration_pct": 22.8 }, "meta": { "source_attribution": [ { "table": "providers", "last_refresh": "2026-05-05" } ] } }

3. Agent calls `search_providers` (Travis County subset)

tool call

{ "method": "tools/call", "params": { "name": "search_providers", "arguments": { "state": "TX", "city": "AUSTIN", "per_page": 100 } } }

tool result (truncated)

{ "data": { "results": [ /* 100 Travis County practices */ ], "total": 1842 } }

4. Agent answer to the user

Travis County (Austin) has roughly 1,842 active dental practices. Statewide DSO penetration in Texas is 22.8%. Source: ProviderSignal providers table, last refreshed 2026-05-05. To break the local DSO share down by ZIP, call get_territory_summary with a specific zip parameter.

Two tool calls, ~$2.85 total in per-call USDC (x402 rail) or 3 credits on the subscription rail. Citation envelope provides the freshness date the agent quotes back to the user.

Tools (4 read-only)

Each MCP tool maps to one path under /api/v1/agent. Every response is wrapped in a citation envelope (see Response Shape). Full input schemas (JSON Schema for every parameter) are served by the tools/list JSON-RPC method.

lookup_provider_by_npi(npi)

forwards to /api/v1/agent/lookup-by-npi

Resolve a 10-digit NPI to a full provider record. Use when an agent has the NPI and needs name, taxonomy, practice address, license status, DSO flag, OIG-exclusion flag, lat/lon, CMS-claims flag, and a 0-100 confidence score (about 30 fields).

Sample call & response ›

input

{ "npi": "1376155820" }

output

{ "data": { "npi": "1376155820", "first_name": "JOHN", "last_name": "SMITH", "specialty": "DENTIST - GENERAL PRACTICE", "practice_address": "1234 MAIN ST", "city": "DALLAS", "state": "TX", "zip": "75201", "license_status_normalized": "active", "is_dso": false, "is_federally_excluded": false, "has_cms_claims": true, "co_located_count": 2 }, "meta": { "envelope_version": "1.0", "source_attribution": [ { "table": "providers", "last_refresh": "2026-05-05", "schema_version": "v2", "license": "public" } ], "confidence": { "provider_record": { "score": 92 } } } }

search_providers({state, city, zip, license_status, page, per_page})

forwards to /api/v1/agent/search

Filtered list with pagination. Use when an agent needs to find practices by geography or status. Filters compose with AND. per_page caps at 100. Returns the same envelope as lookup with a compact per-row record array.

Sample call & response ›

input

{ "state": "TX", "city": "DALLAS", "license_status": "active", "per_page": 25 }

output

{ "data": { "results": [ { "npi": "1376155820", "name": "SMITH, JOHN", "city": "DALLAS", "is_dso": false }, { "npi": "1487266931", "name": "PATEL, RAJ", "city": "DALLAS", "is_dso": true, "dso_label": "HEARTLAND DENTAL" } ], "page": 1, "per_page": 25, "total": 1842 } }

get_dso_affiliation(npi)

forwards to /api/v1/agent/dso/affiliation

Determine whether a provider is part of a Dental Service Organization, which one, and how confident the inference is. Use when buying decisions hinge on chain procurement vs independent rep-direct.

Sample call & response ›

input

{ "npi": "1487266931" }

output

{ "data": { "is_dso": true, "dso_label": "HEARTLAND DENTAL", "signal_type": "address_cascade", "signal_confidence": 0.87, "cluster_size": 14, "sibling_npi_sample": ["1376155820", "1295366042", "1639400138"] } }

get_territory_summary({state, zip})

forwards to /api/v1/agent/territory/rollup

Aggregate market intelligence for a geography. Use when scoping a new sales territory, evaluating an acquisition market, or comparing regions. Returns provider count, DSO penetration, retirement-risk count, license-status breakdown, organization count.

Sample call & response ›

input

{ "state": "TX" }

output

{ "data": { "state": "TX", "total_providers": 21847, "dso_flagged": 4982, "dso_penetration_pct": 22.8, "retirement_risk_55_plus": 6431, "license_status_breakdown": { "active": 18234, "expired": 2091, "retired": 412 }, "distinct_organizations": 8104 } }

Pick a billing rail

Both rails authenticate against the same backend. Choose based on your traffic profile.

Rail 1 · Default for MCP today

Bearer-token subscription

Pass an existing ProviderSignal API key on every request. Per-call usage rides your subscription tier's rate limit.

header

Authorization: Bearer ps_live_<your-key>

Pro / Rep tiers: 500 req/min
Team: 200 req/min
Enterprise: 1,000+ req/min
Get a key at /settings/api-keys

Rail 2 · No signup required

x402 per-call USDC

Skip the subscription. Call /api/v1/agent/* directly. The first request returns 402 with PaymentRequirements; sign a USDC transfer on Base mainnet and retry with X-PAYMENT.

$0.10 to $2.50 per call (see pricing below)
No signup, no credit card
Settles on Base mainnet (chain id 8453)
Full flow: /docs/agent-payments

Native x402 challenge inside an MCP tool call is a v1.1 deferred item. Most MCP clients today don't handle the tool-call payment-challenge loop. Until they do, x402 is reachable outside MCP via the direct /api/v1/agent/* endpoints.

Per-call USDC pricing

Subscription becomes more economical above roughly $30/mo of per-call spend. For batch jobs and infrequent calls, x402 wins on simplicity (no key management) and cost.

Endpoint	Tier	USD/call	Subscription breakeven
/api/v1/agent/lookup-by-npi	basic	$0.10	~990 calls/mo vs $99 Starter
/api/v1/agent/search	basic	$0.25	~396 calls/mo vs $99 Starter
/api/v1/agent/dso/affiliation	moat	$1.00	~99 calls/mo vs $99 Starter
/api/v1/agent/scoring	moat	$1.00	~99 calls/mo vs $99 Starter
/api/v1/agent/license/events/historical	moat	$1.50	~66 calls/mo vs $99 Starter
/api/v1/agent/territory/rollup	moat	$2.50	~40 calls/mo vs $99 Starter
/api/v1/free/lookup	free	$0.00	100/day per IP

basic tier endpoints (lookup, search) are priced near commodity because the underlying data is largely derivable from public NPI sources. moat tier endpoints (DSO inference, scoring, license events history, territory rollup) encode work that takes months to replicate from raw sources, and are priced 10-25x basic.

Endpoint

Streamable HTTP transport per the Model Context Protocol spec. POST JSON-RPC 2.0 messages to:

endpoint

POST https://mcp.providersignal.com/mcp

Discovery manifest (no auth required):

manifest

GET https://mcp.providersignal.com/.well-known/mcp.json

MCP protocol version implemented: 2025-06-18. Notifications return HTTP 204; batched JSON-RPC requests are supported.

Response Shape

Every tool returns a JSON-RPC result with a single content array carrying the citation envelope as text.

Initialize

json-rpc

{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18" } }

List tools

json-rpc

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Call a tool

json-rpc

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "lookup_provider_by_npi", "arguments": { "npi": "1376155820" } } }

Tool response (envelope)

json-rpc

{ "jsonrpc": "2.0", "id": 3, "result": { "content": [ { "type": "text", "text": "{ \"data\": {...}, \"error\": null, \"meta\": { \"envelope_version\": \"1.0\", \"source_attribution\": [...], \"confidence\": {...}, \"request\": {...} } }" } ], "isError": false } }

The envelope inside content[0].text carries:

data — provider record, search results, or aggregate
meta.source_attribution — one entry per data table touched, with last_refresh, schema_version, and license posture
meta.confidence.provider_record — 0-100 score with breakdown (completeness, multi-source, freshness)
meta.request — request id, endpoint, billed credits, billing method (subscription or per_query)

The full field glossary lives at /docs/fields.

Input Validation

Tool arguments are validated at the edge before any database call. Validation errors return JSON-RPC -32602 (invalid params) and never burn rate-limit quota. Defense in depth: the main API re-validates everything server side.

npi: /^\d{10}$/
state: /^[A-Z]{2}$/
zip: /^\d{5}(-\d{4})?$/ (5- or 9-digit)
license_status: enum (active, inactive, expired, retired, deceased)
page: integer 1 to 10000
per_page: integer 1 to 100
strings: 200 chars max (city: 80 max)

Rate Limits & Body Cap

Three guard rails:

60 req/min per IP at the MCP edge, enforced by the Cloudflare-native rate limiter. Fires before any auth or parse work, so anonymous probes cost almost nothing.
16 KB body cap via Content-Length. Larger requests return HTTP 413 before parse.
Per-key tier limit from your subscription (Pro 500/min, Team 200/min, Enterprise higher). Enforced after key validation.

When you hit a 429, the response includes a retry_after_seconds hint plus standard X-RateLimit-* headers.

Discovery Manifest

The .well-known/mcp.json manifest is the 2026 MCP-discovery convention. MCP-aware clients fetch it on connect and render the results in their connector picker.

Server name, version, protocol version, transport
Primary auth: Bearer; alternateBilling block with the full x402 price ladder
Tool list with names and short descriptions

curl

curl -s https://mcp.providersignal.com/.well-known/mcp.json

Connect a Client

Claude.ai (Pro / Team / Enterprise)

Settings › Connectors › Add custom connector
URL: https://mcp.providersignal.com/mcp
Bearer token: paste your ps_live_ key
Save. Claude probes the manifest and registers all four tools.

Cursor

Settings › MCP › Add new MCP server. Same URL + Bearer token. Cursor lists the tools in its agent panel and makes them available in any chat.

Cline (VS Code)

~/.config/cline/mcp.json

{ "mcpServers": { "providersignal": { "transport": "streamable-http", "url": "https://mcp.providersignal.com/mcp", "headers": { "Authorization": "Bearer ps_live_<your_key>" } } } }

Continue (JetBrains / VS Code)

Add to your config.json under experimental.modelContextProtocolServers with the same URL and Authorization header.

ChatGPT

Custom connector via the developer settings. URL and Bearer token same as above.

Custom agent code

Open a POST stream to the endpoint. Send initialize, then tools/list, then tools/call per the MCP spec. JSON-RPC 2.0 batches are supported.

curl

curl -X POST https://mcp.providersignal.com/mcp \ -H "Authorization: Bearer ps_live_<your_key>" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Frequently asked questions

How do I connect to the ProviderSignal MCP server from Claude.ai?›

Open Claude.ai Settings, then Connectors, then Add custom connector. Paste https://mcp.providersignal.com/mcp as the URL and your ProviderSignal API key (ps_live_<...>) as the Bearer token. Save. Claude probes the discovery manifest at /.well-known/mcp.json and registers all four tools automatically.

What tools does the MCP server expose?›

Four read-only tools: lookup_provider_by_npi (full provider record by NPI), search_providers (filtered list by state/city/zip/license_status), get_dso_affiliation (Dental Service Organization chain inference), and get_territory_summary (aggregate market intelligence for a geography).

What does each call cost?›

Two billing rails. On the Bearer-token subscription rail, calls ride your existing tier rate limit (Pro/Rep 500 req/min, Team 200, Enterprise 1,000+). On the x402 per-call rail, prices range from $0.10 (basic lookup) to $2.50 (territory rollup) in USDC on Base mainnet. Subscription becomes more economical above ~$30/mo of per-call spend.

Is there a free tier?›

Yes. /api/v1/free/lookup serves 100 NPI lookups per IP per day with no authentication. Use it to evaluate data quality before committing to a subscription or x402 wallet setup. See /docs/free-tier.

What data sources back the responses?›

NPPES (HHS National Plan and Provider Enumeration System), state dental boards (41 states + DC enriched), CMS Medicare Part B billing data, NPDB malpractice and adverse-action data, OIG LEIE federal exclusion list, and 49 state Medicaid fee schedules. Every response carries a meta.source_attribution array listing the tables touched and their last refresh dates.

What is the citation envelope?›

Every API response wraps the data payload in a meta object containing source_attribution (which tables provided the data), confidence (a 0-100 score with completeness/multi-source/freshness breakdown), and request (id, endpoint, billed credits, billing method). The envelope is the canonical legal-defensibility surface and lets agents cite their work back to a buyer.

Which MCP clients work with this server?›

Anything that speaks the MCP Streamable HTTP transport: Claude.ai (custom connectors), Cursor (Settings > MCP), Cline (VS Code, via mcp.json), Continue (JetBrains/VS Code), ChatGPT (custom connector in developer settings), and any agent code that POSTs JSON-RPC 2.0 to the /mcp endpoint with a Bearer header.

Why is x402 not yet exposed inside MCP tool calls?›

Most MCP clients in 2026 don't yet implement the tool-call payment-challenge loop required to handle a 402 returned mid-tool-call. Until they do, the x402 path is reachable outside MCP via direct calls to /api/v1/agent/*. The MCP server itself uses Bearer-token subscription auth; native x402 inside MCP is a v1.1 deferred item.

References

Agent payments via x402 + USDC: per-call billing rail, network details, payment flow.
Free evaluation tier: 100 lookups per day, no auth required.
Field glossary & stability commitment: every field returned, with deprecation policy.
Full REST API reference: auth, scopes, pagination, errors.
/openapi.json: OpenAPI 3.1 spec covering every endpoint.
modelcontextprotocol.io: Model Context Protocol spec.
x402.org: x402 protocol spec.

MCP server for U.S. dental provider data

TL;DR for agents reading this page

Four tools, dozens of agent workflows

A 2-tool answer in a real Claude.ai conversation

1. User prompt

2. Agent calls get_territory_summary

3. Agent calls search_providers (Travis County subset)

4. Agent answer to the user

Tools (4 read-only)

Pick a billing rail

Bearer-token subscription

x402 per-call USDC

Per-call USDC pricing

Endpoint

Response Shape

Initialize

List tools

Call a tool

Tool response (envelope)

Input Validation

Rate Limits & Body Cap

Discovery Manifest

Connect a Client

Claude.ai (Pro / Team / Enterprise)

Cursor

Cline (VS Code)

Continue (JetBrains / VS Code)

ChatGPT

Custom agent code

Frequently asked questions

References

2. Agent calls `get_territory_summary`

3. Agent calls `search_providers` (Travis County subset)