Skip to main content
Glama
README.md
# @pipeworx/ca-medicaid-rates

California Medi-Cal (Medicaid) per-visit payment rates for federally qualified health centers (FQHC) and rural health clinics (RHC), one record per clinic location: the medical visit rate and the dental visit rate, each with the date it began, from the California Department of Health Care Services.

Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 2016+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

## Tools

- `ca_medicaid_clinic_rates(name?, provider_number?, county?, city?, zip?, program?, service?, limit?)` — per-clinic rates. Filter by clinic name fragment, 10-digit provider number, county, city or zip; narrow to FQHC or RHC and to the medical or dental rate. Returns each location's rates and begin dates, address, summary statistics (min, median, max, mean) over every location matched, and `data_as_of`. An unmatched filter returns the nearest clinic names or the list of valid counties instead of an empty result.
- `ca_medicaid_rates_edition()` — the edition served (month and publication date), location and provider-number counts, per-program and per-county counts with median rates, the range of rate begin dates, and what is not covered.

## Auth

Keyless.

## Data sources

- California Department of Health Care Services (DHCS), FQHC and RHC Current Rates, current monthly edition — public, no account. Data as of the publication date printed on the workbook (2026-02-24 for the February 2026 edition).

Things worth knowing:

- **Rates are per clinic location and service, not statewide per code.** Each location has its own rate. A location can carry a medical visit rate (revenue code 0521) and a dental visit rate (revenue code 0003), each with its own begin date. One published dental line carries procedure code T1015 beside revenue code 0003; the service is read from the revenue code and the procedure code is returned as published.
- **One current edition.** Only the newest monthly edition is served. `rate_begin` is each rate's own begin date (from 2003 to 2026-02 in the February 2026 edition), so it can be years before `data_as_of`.
- **A published rate of 0 is returned as 0**, flagged `published_zero`, and left out of the summary statistics (12 such rates in the February 2026 edition). The workbook does not say why.
- `special_processing_code` and `revenue_type_code` (FQ and RH read as FQHC and RHC; AD appears on two locations and is returned as a code) are the Department's own codes, passed through; the workbook does not define them.
- A few locations are outside California (four rows for two Iowa rural health clinics, county "UNKNOWN") and keep their own state.
- Legal names are abbreviated and cut off as published. Provider number, owner number, service location number and zip are strings.
- Organisations only: a clinic enrolled under a physician's own name (for example "<NAME> MD INC") or a bare personal name is dropped when the data is read and counted in `individual_rows_dropped` (63 source rows in the February 2026 edition).
- Medi-Cal fee-for-service prospective payment rates; managed-care plans may pay differently. Built to a request to cover more of Medicaid, not from measured demand for California.

## Stored data and refresh

The sheet is 4,244 rows, 2,332 locations after individuals are dropped (about 1.3 MB). The Department's site answers every automated client with a bot challenge, so nothing here fetches it. A person downloads the workbook in a browser and drops it in the inbox directory; `scripts/bake-index.mjs` reads that local file into `src/ca-rates-data.ts`, registered in `workers/gateway/src/pack-baked-indexes.json`; the deploy uploads the table to KV and the gateway injects it on the first call into this pack, so nothing is evaluated at module scope. The refresh runner is `human` in `scripts/baked-index-freshness.json`.

`node mcps/ca-medicaid-rates/scripts/bake-index.mjs [workbook.xlsx] [--force]` takes the newest `FQHC-and-RHC-Current-Rates-<Month>-<Year>.xlsx` in the inbox when no path is given, does nothing when that month is already baked, and refuses a changed title, a file-name month that disagrees with the sheet, a changed header, an unknown code, a non-numeric rate, a sheet under its row floor, an older edition than the one baked, or a legal name with no organisation word and no credential that nobody has judged (it lists the names to add to the reviewed lists in the script).

The publisher's edition cannot be checked automatically (the same challenge), so the source-edition check registers this pack as not checked, with the reason.

## Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "ca-medicaid-rates": {
      "url": "https://gateway.pipeworx.io/ca-medicaid-rates/mcp"
    }
  }
}
```

### What this endpoint actually serves

`tools/list` at `https://gateway.pipeworx.io/ca-medicaid-rates/mcp` returns the tools in the table
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
gateway-wide set. So the tool count you see is larger than this table: a
single-pack endpoint currently lists roughly 30 shared tools alongside the
pack's own. The connection's `initialize` response states its exact scope, and
is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a
scoped connection answer a question this pack does not cover — via
`ask_pipeworx`, which routes across the whole catalog — without you adding a
second MCP server. There is currently no way to mount a pack endpoint without
them; if the extra schemas cost you more context than the routing is worth,
connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed
directly, instead of just this one's:

```json
{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}
```

Both URLs reach the same gateway and the same 2016+ data sources. The
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
reaches all of them from either one.

## No MCP client? Call it over HTTP

```bash
curl -X POST https://gateway.pipeworx.io/v1/tools/ca_medicaid_clinic_rates \
  -H 'Content-Type: application/json' \
  -d '{"county":"Fresno","program":"FQHC","limit":5}'
```

No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/ca_medicaid_clinic_rates`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.

## Run it from npm

`@pipeworx/mcp-ca-medicaid-rates` is a local stdio bridge to the Pipeworx gateway: your MCP client
starts it with `npx`, and it forwards every call to the same
`https://gateway.pipeworx.io/ca-medicaid-rates/mcp` endpoint shown above. It needs network access;
there is no offline mode.

```json
{
  "mcpServers": {
    "ca-medicaid-rates": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-ca-medicaid-rates"]
    }
  }
}
```

Without a key it calls anonymously, capped at 50 calls a day. A free account
raises that to 200 a day: get a key at https://pipeworx.io/signup and add
`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
The key is sent as a Bearer token, the same way a hosted connection sends it,
so calls are metered and billed exactly as they are there.

It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
also list `ask_pipeworx` and the other gateway-wide tools.

Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
your Node version's documentation.

## Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English —
this works on the pack endpoint above as well as on the full gateway:

```
ask_pipeworx({ question: "your question about Ca Medicaid Rates data" })
```

The gateway picks the right tool and fills the arguments automatically.

## More

- [Docs and guides](https://pipeworx.io/docs)
- [pipeworx.io](https://pipeworx.io)

## License

MIT