Xcircl

Verified U.S. regulated-care provider data for your app or AI. Source-linked, timestamped.

License: MIT npm @xcircl/sdk npm @xcircl/mcp-server Verified providers Tracked providers States covered Verticals live

Verify any US healthcare provider — query them in natural language or function calls, cross-checked against official sources: NPPES, the FDA, and where available LegitScript and state licensing boards. Use it as an MCP server for Claude/ChatGPT or a TypeScript SDK for your own product; the free tier works with no API key, and it's built for AI agents, clinic finders, and diligence teams.

GLP-1 / weight-management is the deepest vertical today (6,028 tracked · 869 verified). A US-wide provider identity layer (~9M providers across all specialties) is rolling out; medspa and pet veterinary follow. Verified compliance signals and cash prices unlock with a key.

Counts in the badges above are pulled live from /api/v1/coverage/ — the numbers update as the dataset grows.

30-second quickstart (no key, no install)

curl -sL "https://xcircl.com/api/v1/providers/?vertical=glp1&state=TX&limit=3"

{
  "tier": "free",
  "notice": "Free tier: identity fields only. Verified compliance signals, price and timestamps require a key — see /developers/pricing/.",
  "pagination": { "total": 15, "limit": 3, "offset": 0, "returned": 3 },
  "data": [
    {
      "entity_id": "ent_f47550b79f755d70b58b183a",
      "slug": "alegro-health-mckinney-tx",
      "vertical": "glp1",
      "name": "Alegro Health",
      "city": "McKinney",
      "state": "TX",
      "business_mode": "online",
      "latitude": 33.198119,
      "longitude": -96.708802,
      "npi": "1053066357"
    }
    // …
  ]
}

Real data, real API, zero setup. Compliance fields (FDA, licenses, prices) and commercial use → plans.

Use it from Claude (MCP server)

No clone, no build — npx pulls @xcircl/mcp-server from npm.

Claude Code:

claude mcp add xcircl -- npx -y @xcircl/mcp-server
# with a key (unlocks price + compliance fields):
claude mcp add xcircl -e XCIRCL_API_KEY=your-key -- npx -y @xcircl/mcp-server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "xcircl": {
      "command": "npx",
      "args": ["-y", "@xcircl/mcp-server"],
      "env": { "XCIRCL_API_KEY": "optional — omit for the free tier" }
    }
  }
}

Then just ask: “Find GLP-1 clinics in Houston and check their compliance.” The server exposes three tools:

Tool	What it does
search_providers	Filter by vertical / city / state / business mode
get_provider	One full record by entity_id or slug
check_compliance	LegitScript / state-license / FDA signals (paid fields — the tool still answers without a key and says how to unlock)

Use it from your code (TypeScript SDK)

npm install @xcircl/sdk

import { XcirclClient } from '@xcircl/sdk';

const xcircl = new XcirclClient();            // no key → free tier
// const xcircl = new XcirclClient({ apiKey: process.env.XCIRCL_API_KEY });

const { data, notice } = await xcircl.searchProviders({
  vertical: 'glp1',
  city: 'Houston',
  state: 'TX',
});

for (const p of data) console.log(p.name, p.city, p.npi);
if (notice) console.log(notice);              // what a key would add

Runnable examples live in the repo (clone it to run them; both work without any key):

git clone https://github.com/xcircl/healthcare-provider-mcp.git
cd healthcare-provider-mcp && npm install && npm run build
node examples/01-find-clinics.mjs Houston TX  # find clinics
node examples/02-ai-tool-use.mjs              # give Claude live xcircl tools (bring your own ANTHROPIC_API_KEY)

Where the data comes from

Every record is assembled from official, citable sources — and every paid signal carries its source and verification timestamp:

• NPPES — the CMS National Provider Identifier registry, for provider identity (name, location, NPI).
• FDA Data Dashboard — Drugs/Biologics warning-letter screens (compliance actions since 2019).
• State license boards — medical and pharmacy license records.
• LegitScript — certification status checks.
• Provider websites — published cash prices, with the source page and check date recorded.

This repository contains no data files — it is the open-source shell (MCP server + SDK + docs) around the xcircl API. The data lives, and the field tiering is enforced, server-side. The only demo data source is the live /api/v1/sample/ endpoint (~50 clean records in the paid schema).

Free vs paid fields

Field	Free (no key)	With a paid key
entity_id, slug, vertical, name	✅	✅
city, state, latitude, longitude	✅	✅
business_mode, npi	✅	✅
legitscript — certification signal	—	✅
license — state-license record	—	✅
fda — warning-letter screen	—	✅
price — published cash price	—	✅
source + verified_at on every signal	—	✅

Free tier: no key needed — identity fields, great for evaluation. Compliance fields (FDA, licenses, prices) and commercial use → plans at xcircl.com/developers/pricing.

• No key: fully usable, 100% real data, plus a one-line notice about paid fields — the free experience is a real demo, and the wall you hit is a field wall, never a "doesn't run" wall.
• Field tiering, rate limits and vertical binding are all enforced server-side by the key — this client contains zero gating logic.

Full field dictionary: docs/schema.md · recorded test runs against production: docs/verification.md.

Repository layout

packages/mcp-server/   MCP server (stdio) — search_providers / get_provider / check_compliance
packages/sdk-ts/       @xcircl/sdk — zero-dependency TypeScript client
examples/              runnable examples (find clinics, AI tool use)
docs/schema.md         field dictionary (free/paid tiering)

License

MIT — the shell is open; build on it freely.