Skip to main content

MCP Server

ClaimRev provides a Model Context Protocol (MCP) server that lets AI assistants such as Claude, ChatGPT, and Copilot work with ClaimRev directly: search payer data, and find and run the Sharp Insight reports that answer questions about your account.

How MCP works​

MCP is a standard way to give an AI assistant tools. You add an MCP server to your assistant once (a URL, plus credentials when the server needs them). From then on, when you ask a question, the assistant can see the server's tools, decide one is useful, call it, and use the answer in its reply.

A few things worth knowing:

  • The assistant only uses servers you add. An MCP server is not a website that AI search engines find on their own. Nothing calls ClaimRev's MCP server unless someone has configured their assistant to use it.
  • The assistant acts with your credentials. On the signed-in endpoint, every tool call carries your token (from your own sign-in, or your application's key file), so the assistant can see exactly what you could see through the API, and nothing more.
  • Tools are described in plain language. The assistant reads each tool's description to decide when to use it, so you ask questions normally ("which report shows our denial trends?") rather than naming tools.

Endpoints​

ClaimRev has two MCP endpoints. Both use the Streamable HTTP transport.

EndpointProduction URLSign-inTools
Publichttps://api.claimrev.com/mcpNonePayer search
Accounthttps://api.claimrev.com/mcp/accountRequired (ZITADEL bearer token), and AI connections enabled for the accountYour account's Sharp Insight reports: find and run them

The test environment uses the same paths on https://testapi.claimrev.com.

The public endpoint never shows account tools, even to a caller who sends a token. Account tools exist only on /mcp/account.

Public endpoint: payer tools​

The payer search tools do not require authentication, so there is no client id, key, or bearer token to configure.

Available tools​

search_claimrev_payers​

Searches ClaimRev's payer database for healthcare payers that support electronic transactions.

Parameters (all optional):

ParameterTypeDescription
payerNamestringPayer name, substring match (e.g. Aetna, Blue Cross)
payerNumberstringPayer number, substring match (e.g. 60054)
payerStatestringTwo-letter state code (e.g. TX, CA)
transactionTypeIdsint[]Filter by transaction type: 1 Professional, 2 Institutional, 3 Dental, 4 Eligibility, 6 Batch Claim Status, 7 Real-time Claim Status
payerTypeIdsint[]Filter by payer type

Response fields (one object per payer):

FieldDescription
inboundPayerNumberClaimRev payer ID. Use this for claim submission.
payerIdClaimRev internal payer record id
payerNamePrimary payer name
payerTypeIdPayer type id (the value payerTypeIds filters on)
payerTypeNamePayer type name (Commercial, Medicare, Blue, etc.)
supportsProfessionalSupports 837P professional claims
supportsInstitutionalSupports 837I institutional claims
supportsDentalSupports 837D dental claims
supportsEligibilitySupports 270/271 eligibility verification
supportsRtClaimStatusSupports real-time 276/277 claim status
supportsBatchClaimStatusSupports batch 276/277 claim status
enrollmentRequiredProvider enrollment is required before submitting
alternateNamesOther names this payer is known by. Useful for cross-referencing between systems.
sharpRevenuePayerIdThe outbound payer ID sent to the eligibility gateway (SharpRevenue). Only populated when eligibility is supported. Medicare payers typically route to CMS (payer 00472) regardless of the specific Medicare plan.

search_sharp_revenue_payers​

Searches the SharpRevenue master payer list used for eligibility routing. Payer IDs and names here differ from ClaimRev's.

Parameters:

ParameterTypeDescription
searchTextstringSearches both payer name and payer number. Leave empty to return all payers.

Response fields:

FieldDescription
payerIdSharpRevenue internal payer ID
payerNamePayer name (often different from the ClaimRev name)
payerNumberSharpRevenue payer number. This is the value that appears in sharpRevenuePayerId on ClaimRev payer results.
downDateIf set, the date the payer was reported down in SharpRevenue
removeGuarantorWhether the guarantor is stripped from eligibility requests for this payer
serviceTypeCodeAllowedListService type codes this payer accepts on eligibility requests

Connecting to the public endpoint​

Claude Code​

Run from your project directory:

claude mcp add --transport http claimrev-payers https://api.claimrev.com/mcp

Claude Desktop and claude.ai​

Open Settings → Connectors → Add custom connector and enter https://api.claimrev.com/mcp as the URL. No OAuth settings are needed.

Other MCP clients​

Any MCP-compatible client can connect using the Streamable HTTP transport at the endpoint above. Clients that only speak stdio can bridge to it with mcp-remote:

{
"mcpServers": {
"claimrev-payers": {
"command": "npx",
"args": ["mcp-remote", "https://api.claimrev.com/mcp"]
}
}
}

Common payer questions​

Find a payer by name​

"Find the ClaimRev payer ID for Aetna and tell me if it supports eligibility."

Cross-reference payer IDs between systems​

"I have payer ID 7450 in my system for Anthem Blue Cross. What's the matching ClaimRev payer ID?"

The assistant searches ClaimRev by name, finds BCBS Montana (00751), and shows the SharpRevenue ID (00098) used for eligibility routing.

Bulk payer mapping​

Paste a list of payer IDs and names and ask:

"Which of these payers support eligibility in ClaimRev, and what IDs should I use?"

The assistant cross-references both the ClaimRev and SharpRevenue payer lists, matching by name, ID, and alternate names.

Find eligibility routing​

"Where does eligibility for Medicare Railroad get routed?"

The assistant finds that Medicare Railroad (00882) routes to CMS (SharpRevenue 00472) via HETS, the same as all Medicare payers.

Account endpoint: Sharp Insight reports​

/mcp/account gives an assistant tools that work on your ClaimRev account. It has two tools: list_sharpinsight_reports finds the Sharp Insight report that answers a question, and run_sharpinsight_report runs it and returns the data.

AI connections (required)​

Everything /mcp/account returns is treated as protected health information (PHI). Reports can include patient names, claim numbers, service dates and other patient-level detail, and ClaimRev does not mask or filter data on this endpoint. So before any tool on it works, a practice admin must switch on AI connections for the account and accept this attestation:

Data our staff and automated agents retrieve through ClaimRev's AI connections may include protected health information. Every AI system we connect is either run by us on systems we control, or provided by a vendor that has signed a Business Associate Agreement with us that covers the accounts our staff and agents use. We authorize ClaimRev to send our account data to those systems.

That means every AI system you connect to /mcp/account must be one of these:

  • Run by you, on systems you control, for example a model you host yourself.
  • Provided by a vendor that has signed a Business Associate Agreement (BAA) with you, covering the accounts your staff and agents use. A consumer AI plan without a BAA does not qualify.

To enable it: a practice admin with the AI connections permission (practice_admin:ai-data-access) opens the portal, goes to Practice Admin, then AI Connections, reads the attestation, ticks I agree on behalf of the practice, and selects Enable AI connections. The same screen shows who enabled it, when, and which version of the wording they accepted, and has a Disable AI connections button. Turning it off takes effect within 30 seconds.

Only a signed-in practice admin can turn AI connections on: a key-file application cannot enable them, and ClaimRev staff cannot enable them while viewing the account as the customer, since the attestation has to come from the practice itself. Disabling has no such restriction.

What it covers:

  • One switch covers every tool on /mcp/account, now and later, for people who sign in from their assistant and for key-file agents alike.
  • It is per account. Enabling it on a parent account does not enable it on the parent's child accounts; each account decides for itself.

While it is off: the assistant can still list the tools, but every tool call returns an error the assistant can read out: "AI connections are not enabled for this ClaimRev account. A practice admin can enable them in the portal under Practice Admin, AI connections."

The public /mcp endpoint (payer search) is not affected.

Ways to connect​

There are two ways to connect:

  • Sign in from your assistant (recommended). Claude, Claude Desktop and Claude Code open a browser, you sign in with your ClaimRev login, and the assistant keeps itself signed in. Production only.
  • A key file and a token you supply. For scripts, other assistants, and the test environment.

What you need​

  1. AI connections enabled for the account by a practice admin. See AI connections. Without it, every tool call is refused.
  2. A role that includes Sharp Insight read access (sharpinsight:read). Without it, the endpoint answers 403.
  3. You get your default account. The assistant always sees the account you (or the application) sign in to. It cannot ask about a different account.
  4. For signing in from your assistant: a ClaimRev portal login that signs in with ZITADEL.
  5. For a key file: a ZITADEL client application with a key file, created in the portal under Practice Admin, then API Integrations, then Client Applications. See Client Applications and Setting the application's roles.

Signing in from your assistant​

SettingValue
Server URLhttps://api.claimrev.com/mcp/account
OAuth Client ID395403588760764418
OAuth Client SecretLeave empty
Callback port (Claude Code only)33418

The Client ID is public: it identifies the ClaimRev MCP sign-in, not you. Your own login and MFA protect the account.

Claude and Claude Desktop​

  1. Open Settings, then Connectors, then Add custom connector.
  2. Enter a name (for example ClaimRev) and the server URL.
  3. Open Advanced settings and enter the OAuth Client ID. Leave the secret empty.
  4. Click Add, then Connect. Sign in with your ClaimRev login in the window that opens.

Claude Code​

claude mcp add --transport http --client-id 395403588760764418 --callback-port 33418 \
claimrev-account https://api.claimrev.com/mcp/account

Then run /mcp, choose claimrev-account, and sign in through the browser that opens. Use --callback-port 33418 exactly: sign-in only returns to that port.

How it works​

The assistant follows the standard MCP sign-in. Its first call gets a 401 that points to the endpoint's metadata at https://api.claimrev.com/.well-known/oauth-protected-resource/mcp/account. That names ClaimRev's sign-in server, https://auth.claimrev.com, and the scopes to ask for. The assistant then signs you in with authorization code and PKCE, and uses the refresh token it receives (offline_access) to stay signed in. You do not handle tokens.

Connecting with a key file​

You get a token from ZITADEL first, then give it to your assistant as an HTTP header that it sends on every call:

HeaderValue
AuthorizationBearer <your access token>
x-auth-tenantzitadel

In production, /mcp/account recognises ZITADEL tokens without x-auth-tenant; sending it does no harm. The test environment (testapi.claimrev.com) still needs it.

Step by step:

  1. Get a token. Sign in with the application's key file exactly as described in Authentication: Signing in with a key file: build a signed assertion, post it to the ZITADEL token URL, and read access_token from the response. The script below does this for you.
  2. Give the token to your assistant as the headers above (examples below).
  3. Refresh it when it expires. Key-file tokens last about an hour (expires_in in the token response) and there is no refresh token. When the assistant starts getting 401, get a new token and update the header.

Getting a token with a script​

Save this as claimrev_token.py, then run python claimrev_token.py cr-xxxxxxxx-key.json. It prints an access token. It needs pip install pyjwt[crypto] requests.

import json, sys, time
import jwt, requests

# Production. For test, use https://auth-staging.claimrev.com and project 394262572515196931.
AUTHORITY = "https://auth.claimrev.com"
PROJECT_ID = "394259562464542723"

with open(sys.argv[1]) as f:
key = json.load(f)

now = int(time.time())
assertion = jwt.encode(
{"iss": key["userId"], "sub": key["userId"], "aud": AUTHORITY, "iat": now, "exp": now + 300},
key["key"],
algorithm="RS256",
headers={"kid": key["keyId"]},
)

response = requests.post(
f"{AUTHORITY}/oauth/v2/token",
data={
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": assertion,
"scope": f"openid urn:zitadel:iam:org:project:id:{PROJECT_ID}:aud",
},
)
response.raise_for_status()
print(response.json()["access_token"])

Treat the key file like a password: keep it out of source control, and never paste it or the token into a chat with an assistant.

Using the token in your assistant​

Claude Code​
TOKEN=$(python claimrev_token.py cr-xxxxxxxx-key.json)
claude mcp add --transport http claimrev-account https://api.claimrev.com/mcp/account \
--header "Authorization: Bearer $TOKEN" \
--header "x-auth-tenant: zitadel"

When the token expires, remove the server (claude mcp remove claimrev-account) and add it again with a fresh token.

Claude Desktop and other clients​

The custom connector screen in Claude Desktop and claude.ai has no field for custom headers, so connect through mcp-remote, which can add them. In the client's MCP configuration file:

{
"mcpServers": {
"claimrev-account": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.claimrev.com/mcp/account",
"--header", "Authorization:${CLAIMREV_AUTH}",
"--header", "x-auth-tenant:zitadel"
],
"env": {
"CLAIMREV_AUTH": "Bearer <paste your access token here>"
}
}
}
}

Write the header values without a space after the colon, as shown; some clients split arguments on spaces. Restart the client after replacing an expired token.

Available tools​

list_sharpinsight_reports​

Lists the Sharp Insight reports for the signed-in account, so the assistant can pick the one that answers your question. It returns no report data (use run_sharpinsight_report for that), and it takes no parameters.

Response:

FieldDescription
accountLevelThe account's Sharp Insight level: Off, Included or Premium
reportsOne entry per report, below

Each report:

FieldDescription
reportKeyThe report's identifier
nameReport name as shown in the portal
categoryThe Sharp Insight group it belongs to, for example Denials
descriptionThe question the report answers
requiredLevelIncluded or Premium
availableWhether the account's level includes this report. The assistant is told not to suggest unavailable reports.
inputsWhat the report takes, such as a date range or payer, and whether each is required
routesThe API route(s) and HTTP method that run the report
assistantCanRunWhether run_sharpinsight_report can run this report for your account
assistantReasonWhy not, when assistantCanRun is false: needs a higher Sharp Insight level, configuration, not a report, or not available to assistants yet
assistantInputsThe inputs run_sharpinsight_report takes for this report (name, whether required, description). Pass these, not inputs, which describes the portal API and can differ

run_sharpinsight_report​

Runs one Sharp Insight report for the signed-in account and returns its data. The assistant is told to call list_sharpinsight_reports first, to choose the report and see what it takes.

Results can include patient-level data, such as patient names, claim numbers and service dates, and are not masked on this endpoint. They are for the signed-in account only: the account always comes from your sign-in, never from a parameter.

Parameters:

ParameterTypeDescription
reportKeystringRequired. A reportKey from list_sharpinsight_reports, or one of the detail views below
startDate, endDatestringThe date range, yyyy-MM-dd. Most reports need both
payerIdintClaimRev payer record id
payerNumber, payerNamestringPayer filters
providerNpi, billingProviderNpi, renderingProviderNpistringProvider filters
groupCodestringCARC group code, for example CO (CARC Trends)
topNintHow many top rows a ranking report returns
minClaimCountintSmallest pattern size (Denial Pattern Suggestions)
claimIdstringThe claim to compare (claim_similarity)
page, pageSizeintPaging (payment_event_details). pageSize is at most 100; a larger value returns 100 rows.
procedureCodestringProcedure code (diagnosis_ordering.drilldown, payment_event_details)
diagnosisOrderstring[]Diagnosis codes in billed order (diagnosis_ordering.drilldown)
carcCodesstring[]CARC codes to match, for example CO45 (payment_event_details)
revenueCodestringRevenue code (payment_event_details)
sortField, sortDirectionstring, intSort column, and 1 ascending or -1 descending (payment_event_details)

Each report takes only some of these, exactly the ones listed in its assistantInputs in the directory (not inputs, which describes the portal API and can differ). A parameter the chosen report does not take is refused with a message naming what it does take.

Detail views, beyond the reports in the directory:

reportKeyWhat it returnsInputs
mips_penalty_impact.detailThe per-claim rows behind MIPS Payment ImpactstartDate, endDate
regulatory_penalties.detailThe per-claim rows behind Regulatory PenaltiesstartDate, endDate
diagnosis_ordering.drilldownThe claims behind one diagnosis orderingstartDate, endDate, payerName, procedureCode, diagnosisOrder
payment_event_detailsERA service lines, a page at a timeoptional startDate, endDate, payerName, payerNumber, procedureCode, carcCodes, revenueCode, billingProviderNpi, renderingProviderNpi, page (default 1), pageSize (default 25, at most 100), sortField, sortDirection

claim_similarity is an ordinary report in the directory, but it takes no dates: pass claimId (a claim on your account) and optionally topN (default 10).

Response: structuredContent is { "reportKey": ..., "result": ... }, where result is the same JSON the report's API route returns. The same JSON is also sent as text.

Size: results are never cut short. The tool declares anthropic/maxResultSizeChars of 200,000 so Claude Code accepts large results. A result over 200,000 characters is refused with its size: run the report for a shorter date range, or use the portal or the report's CSV export for the full set.

Rate limit: 30 report runs a minute per caller (each person, or each key-file application). Past that, runs are refused until the next minute. A caller the server cannot identify at all is refused outright rather than given a shared budget; this should not happen in normal use.

What it does not run:

  • CSV and PDF exports. They are files, and the report itself returns the same data.
  • Writing a new Monthly Summary AI analysis, which uses ClaimRev's AI. monthly_summary_analysis returns an analysis already generated in the portal, and says so when there is none; when the cached analysis has gone stale (the summary figures changed since it was written), the response says so instead of regenerating it.
  • Rule suggestions from ClaimRev's AI.
  • Contracted rates, which are configuration, not a report.

Hide patient data: while hide patient data is on for your login, every run is refused rather than masked.

Common report questions​

"Which Sharp Insight report shows why our claims are being denied?"

"Is there a report that compares how fast each payer pays us?"

"What reports does our plan include, and which would need Premium?"

The assistant calls list_sharpinsight_reports, reads the descriptions, and names the matching report, what it needs (for example a date range), and whether your plan includes it.

"Run the denial trends report for September and tell me which payer's denials grew most."

"Which reversals last quarter were never reissued?"

The assistant picks the report from the directory (CARC Trends, Reversals & Corrections), runs it with run_sharpinsight_report for the dates you named, and answers from the data.

Troubleshooting​

SymptomLikely cause
401Signed in from your assistant: sign in again (in Claude Code, /mcp, then the server, then Authenticate). Key file: the token expired; get a new one. In the test environment, also check x-auth-tenant: zitadel.
Sign-in window says the redirect URI is invalidClaude Code was added without --callback-port 33418. Remove the server and add it again with the command above.
Signed in, but every call is refused, or you are asked to sign in again and againYour ClaimRev login is not set up for ZITADEL sign-in, or its email is not verified. Ask your ClaimRev contact.
403Your role (or the application's) has no sharpinsight:read. Ask your practice admin, or add it under Manage roles for a key-file application.
The tool is missingYou connected to /mcp instead of /mcp/account. The public endpoint never lists account tools.
Every report shows available: falseThe account's Sharp Insight level is Off. Ask your ClaimRev contact.
Every tool call says AI connections are not enabledA practice admin has not enabled AI connections for this account. See AI connections.
A run says the report needs a higher Sharp Insight levelThe account's level does not include that report. Ask your ClaimRev contact.
A run says the result is too largeThe result is over 200,000 characters. Ask for a shorter date range, or use the portal or the CSV export.
A run says there are too many report runsMore than 30 runs in a minute from the same caller. Wait a minute.
A run says the caller could not be identifiedSign in again from your assistant, or for a key file get a fresh token.
A run says reports are withheld while patient data is hiddenHide patient data is on for your login. Turn it off in the portal, then sign in again from your assistant.