# PayerPrice MCP Documentation

Connect an AI assistant to PayerPrice data using the Model Context Protocol (MCP).

## Server URL

`https://api.payerprice.com/api/v1/open/mcp`

The server uses Streamable HTTP. Your MCP client discovers permitted tools with tools/list and invokes them with tools/call.

## Authorization

Compatible clients use OAuth to connect to PayerPrice. Direct integrations can instead send an active API key in the Authorization: Bearer YOUR_API_KEY header. Your organization's tool access and API/MCP credits still apply.

## Client setup

### Claude Desktop

In Claude Desktop, open Customize → Connectors, select + → Add custom connector, and enter the PayerPrice server URL:

```
https://api.payerprice.com/api/v1/open/mcp
```

On Team or Enterprise plans, an organization owner must add the remote connector first. Then select Connect to sign in.

### Claude Code

To add this MCP to Claude Code, run this command in your terminal:

```
claude mcp add --transport http payerprice https://api.payerprice.com/api/v1/open/mcp
```

Run claude mcp list to verify the server, then use /mcp in Claude Code to sign in.

### Claude.ai

In Claude.ai, open Customize → Connectors, select + → Add custom connector, and enter the MCP server URL:

```
https://api.payerprice.com/api/v1/open/mcp
```

On Team or Enterprise plans, an organization owner must add the remote connector first. Then select Connect to sign in.

### Gemini Enterprise

Ask PayerPrice support for a Client ID and secret registered with https://vertexaisearch.cloud.google.com/oauth-redirect. In Google Cloud, create a Gemini Enterprise Custom MCP Server data store and enter:

```
MCP Server URL: https://api.payerprice.com/api/v1/open/mcp
Authorization URL: https://api.payerprice.com/oauth/authorize
Token URL: https://api.payerprice.com/oauth/token
Client ID: <provided by PayerPrice>
Client Secret: <provided by PayerPrice>
Scopes: payerprice:mcp:read
Enable PKCE Support: Yes (required)
```

Select Enable PKCE Support, click Verify Auth, and sign in to PayerPrice. Then continue creating the data store and enable the PayerPrice actions you want to use.

### Codex

Add PayerPrice as a Streamable HTTP MCP server from your terminal:

```
codex mcp add payerprice --url https://api.payerprice.com/api/v1/open/mcp
```

Then start OAuth authorization and sign in to PayerPrice:

```
codex mcp login payerprice
```

### Cursor

To add this MCP to Cursor, update your `~/.cursor/mcp.json`:

```
{
  "mcpServers": {
    "PayerPrice": {
      "url": "https://api.payerprice.com/api/v1/open/mcp"
    }
  }
}
```

Save the file and restart Cursor. Complete OAuth sign-in when prompted.

### VS Code

To add this MCP to VS Code, update your `.vscode/mcp.json`:

```
{
  "servers": {
    "PayerPrice": {
      "type": "http",
      "url": "https://api.payerprice.com/api/v1/open/mcp"
    }
  }
}
```

Start PayerPrice with MCP: List Servers, then complete OAuth sign-in in your browser.

## Tools

### search_market_percentile_negotiated_rates

Compute aggregate statistics (percentiles, min, max, mean) over commercial negotiated rates across all providers that match the given filters (state, specialty, payer, billing code, etc.). Use this to understand the distribution of rates in a market - e.g. 'what do BCBS and United typically pay cardiologists in Texas for CPT 99213?'. Returns aggregated numbers only. Use search_market_negotiated_rates for individual rows across a market or search_provider_fee_schedule for identified providers.

#### Parameters

- `filters.states` **(required)**: string[] - Required. Two-letter US state codes that providers must be located in (e.g. ['CA', 'MA', 'TX']).
- `filters.zipCodes`: string[] - Five-digit US ZIP codes to further restrict provider location (e.g. ['02451', '90210']).
- `filters.taxonomyCodes` **(required)**: string[] - Required. NUCC provider taxonomy codes that identify specialty (e.g. ['207Q00000X'] for Family Medicine). Narrow to at least one specialty.
- `filters.entityTypes`: 'individual' | 'group'[] - Entity type to filter providers by: 'individual' (solo practitioner) or 'group' (organization/group practice). Omit to include both.
- `filters.payers` **(required)**: string[] - Required. Insurance payer identifiers (e.g. ['BCBS', 'United', 'Aetna']). Many BCBS affiliates are state-specific - see the 'search-rates-options-payers' resource for the full list.
- `filters.billingCodeAndTypes`: object[] - Exact billing codes and their code system (e.g. [{ code: '99213', type: 'CPT' }]).
- `filters.billingClasses`: 'professional' | 'institutional'[] - Rate source: 'professional' (physician/practitioner billing) or 'institutional' (facility/hospital billing).
- `filters.serviceCodes`: string[] - CMS Place of Service codes as two-character strings (e.g. '11' for office, '22' for outpatient hospital, '02' for telehealth).
- `filters.billingCodeModifiers`: string[] - CPT/HCPCS modifiers to narrow results (e.g. '25', '59', 'LT').
- `filters.negotiatedTypes`: string[] - How the rate is expressed (e.g. 'negotiated', 'fee schedule', 'per diem', 'percentage', 'derived'). See the 'search-rates-options-negotiated-types' resource for all values.
- `filters.yearMonths`: object[] - Specific year/month periods to filter by, e.g. [{ year: 2024, month: 10 }]. Leave empty to use the most recently available data.
- `filters.planNames`: string[] - Normalized insurance plan types to filter by (e.g. ['HMO', 'PPO', 'EPO']).
- `filters.networks`: string[] - Individual (un-normalized) network names to filter rates by, exactly as reported in the payer transparency file (e.g. ['Choice Plus', 'Navigate']).
- `metrics.aggregations` **(required)**: string[] - Statistical aggregates to compute over the rates that match the filters above (e.g. ['percentile_50', 'percentile_75', 'percentile_90']). See the 'search-rates-options-aggregations' resource for all supported values.
- `metrics.comparedTo`: string - Optional Medicare comparison baseline for the benchmark values.
- `groupBy` **(required)**: string[] - Dimensions to group results by, e.g. ['payer', 'billingCode'] returns one row per (payer, code) combination. Network output semantics are endpoint-specific: market benchmarks return one group per network, while provider rates return a deduplicated network array. Include at least 'payer' and 'billingCode' in most cases - without them, rates are pooled across payers/codes and are usually not interpretable.

### search_market_negotiated_rates

Retrieve a bounded page of individual provider negotiated-rate rows for a state, specialty, payer, and billing code. Use for provider-level market comparisons or row-level evidence. Use search_market_percentile_negotiated_rates for typical rates, averages, medians, or percentiles. The limit.offset page size cannot exceed 100. aggregatedColumns collapses listed fields within rows; it is not a group-by setting.

#### Parameters

- `filters.states` **(required)**: string[] - US state codes (e.g., CA, MA, TX) to search for.
- `filters.zipCodes`: string[] - 5-digit US ZIP codes to filter results by provider location (e.g., 02451, 90210).
- `filters.taxonomyCodes` **(required)**: string[] - Provider taxonomy codes to search for.
- `filters.entityTypes`: 'individual' | 'group'[] - Provider entity types to search for.
- `filters.payers` **(required)**: string[] - Insurance payer names (e.g., BCBS, United, Aetna) to search.
- `filters.billingCodeAndTypes`: object[] - Specific billing codes to search for.
- `filters.billingClasses`: 'professional' | 'institutional'[] - Professional vs institutional.
- `filters.serviceCodes`: string[] - Place of service codes (e.g., 11 for office, 21 for hospital) to search for.
- `filters.billingCodeModifiers`: string[] - CPT modifiers to search for.
- `filters.negotiatedTypes`: string[] - Rate negotiation types to search for.
- `filters.yearMonths`: object[] - Time periods to search for. Omit or use an empty array [] to include all time periods (no filter).
- `filters.planNames`: string[] - Normalized plan names to filter by (e.g., 'HMO', 'PPO', 'EPO'). These filter rates to specific insurance plan types.
- `filters.networks`: string[] - Individual (un-normalized) network names to filter rates by, exactly as reported in the payer transparency file (e.g., 'Choice Plus', 'Navigate').
- `aggregatedColumns`: string[] - Fields to collapse into delimited output lists, not group-by dimensions. Payer is always a separate result dimension and is not valid here. Defaults to serviceCode and billingCodeModifier. Include network only when network output is needed because it resolves network_names_arr.
- `rateAggregation`: string - Method used to aggregate negotiated rates.
- `sortInfo`: object[] - Server-side sorting applied before pagination.
- `limit`: object - Pagination limit with offset.
- `limit.start`: number
- `limit.offset` **(required)**: number

### search_provider_fee_schedule

Retrieve the commercial negotiated rates (fee schedule) for specific providers identified by NPI, TIN, or CCN, for the payers and billing codes you specify. Use this when you want each provider's own rates - e.g. 'what rates has Mayo Clinic negotiated with Aetna for office visits?'. Use search_market_negotiated_rates for individual rates across a market or search_market_percentile_negotiated_rates for market statistics.

#### Parameters

- `providers` **(required)**: object - Providers to return rates for. Provide at least one of npis, tins, or ccns. Use search_providers first if you only know the provider's name.
- `providers.npis`: number[] - NPIs (10-digit numbers) whose negotiated rates to retrieve.
- `providers.tins`: number[] - TINs (9-digit numbers) whose negotiated rates to retrieve.
- `providers.ccns`: string[] - CCNs (CMS Certification Numbers, 6 characters) whose negotiated rates to retrieve.
- `payers` **(required)**: string[] - Required. Insurance payer identifiers (e.g. ['BCBS', 'United', 'Aetna']). See the 'search-rates-options-payers' resource for the full list, including state-specific BCBS affiliates.
- `billingCodeAndTypes`: object[] - Exact billing codes and their code system (e.g. [{ code: '99213', type: 'CPT' }]).
- `billingClasses`: 'professional' | 'institutional'[] - Rate source: 'professional' (physician/practitioner billing) or 'institutional' (facility/hospital billing).
- `serviceCodes`: string[] - CMS Place of Service codes as two-character strings (e.g. '11' for office, '22' for outpatient hospital, '02' for telehealth).
- `billingCodeModifiers`: string[] - CPT/HCPCS modifiers to narrow results (e.g. '25', '59', 'LT').
- `negotiatedTypes`: string[] - How the rate is expressed (e.g. 'negotiated', 'fee schedule', 'per diem', 'percentage', 'derived'). See the 'search-rates-options-negotiated-types' resource for all values.
- `yearMonths`: object[] - Specific year/month periods to filter by, e.g. [{ year: 2024, month: 10 }]. Leave empty to use the most recently available data.
- `planNames`: string[] - Normalized insurance plan types to filter by (e.g. ['HMO', 'PPO', 'EPO']).
- `networks`: string[] - Individual (un-normalized) network names to filter rates by, exactly as reported in the payer transparency file (e.g. ['Choice Plus', 'Navigate']).
- `groupBy` **(required)**: string[] - Dimensions to group provider-rate results by. Network and planName are returned as deduplicated arrays instead of splitting otherwise identical rate rows. Include at least 'payer' and 'billingCode' in most cases - without them, rates are pooled across payers/codes and are usually not interpretable.

### search_providers

Look up healthcare providers by name (e.g. 'Mayo Clinic'), specialty (via taxonomyCodes), or state, and return their identifying details: NPI/TIN/CCN, name, states, taxonomy codes, entity type, and in-network payers. Commonly used as the first step before search_provider_fee_schedule - find the provider(s) here, then pass the returned NPI/TIN/CCN values to fetch their negotiated rates.

#### Parameters

- `providerName`: string - Name of an individual provider, group, hospital, or clinic (e.g. 'Dr. John Smith' or 'Mayo Clinic'). Do not put specialties (e.g. 'Cardiology', 'Pediatrics') here - use taxonomyCodes for that.
- `types`: 'npi' | 'tin' | 'ccn'[] - Which identifier types to return results for:
            * 'npi' - National Provider Identifier, covers both individuals and organizations.
            * 'tin' - Tax Identification Number, used for organizations/group practices.
            * 'ccn' - CMS Certification Number, used for Medicare-certified hospitals and facilities.
            Omit to return matches of all three types.
- `states`: string[] - Two-letter US state codes to filter providers by (e.g. ['CA', 'MA']). Omit to search across all states.
- `taxonomyCodes`: string[] - Provider taxonomy codes (NUCC) that identify a specialty, e.g. '208000000X' for Pediatrics. Required when searching by specialty rather than by a specific provider name or identifier.
- `limit`: number - Maximum number of providers to return per identifier type. Defaults to the top 10 most relevant matches per type.

### search_medicare_rates

Look up Medicare's published fee schedules and reference rates. Pick one medicareType: 'Physician FFS' (fee-for-service physician rates by HCPCS code and locality), 'Drug ASP' (quarterly Average Sale Price for Part B drug codes), 'MS-DRG weight' (inpatient DRG relative weights), or 'Anesthesia' (national anesthesia conversion factors by year/month). Useful as a government-rate baseline when comparing against commercial negotiated rates returned by the other tools.

#### Parameters

- `medicareType` **(required)**: 'Physician FFS' | 'Drug ASP' | 'MS-DRG weight' | 'Anesthesia' - Required. Which Medicare dataset to query: 'Physician FFS' (Physician Fee Schedule rates by HCPCS code and locality), 'Drug ASP' (Average Sale Price for Part B drug codes), 'MS-DRG weight' (inpatient DRG relative weights), or 'Anesthesia' (national anesthesia conversion factors).
- `codes`: string[] - Billing codes to look up - HCPCS/CPT for Physician FFS, HCPCS for Drug ASP, MS-DRG numbers for MS-DRG weight. Not applicable to Anesthesia (omit for that type).
- `years`: number[] - Four-digit years to filter by (e.g. [2024, 2025]). Omit to get the most recent available year. History reaches back to 2002 for Physician FFS, 2005 for Drug ASP and FY2008 for MS-DRG weights.
- `states`: string[] - Two-letter state codes (e.g. 'CA', 'TX'), or 'national' for the Physician FFS national locality. Only applies to 'Physician FFS'; ignored for other medicareType values.
- `month`: number - Month as 1-12. Only applies to 'Drug ASP' (pricing is quarterly but indexed by month).
- `limit`: number - Maximum number of rows to return (1-100). Defaults to 100.

Human-readable documentation: https://api.payerprice.com/mcp/doc