MCP
One connection and one API key reach every service your key includes. Tools are named service_tool, so a tool name tells you which service does the work. Listing tools is free. Running a tool costs credits, exactly as the per-service door does.
https://api.hank.ai/mcp
Sign in to run calls
Read the whole capability map and every error shape on this page without an account. To run a call you need three things: a signed-in member, an API key that reaches the service, and credits left in the period. There is no anonymous demo and no shared test key, because every call bills the organization that owns the key. Sign in to see what each call costs.
One prefilled call for every service you reach
These are real calls, not a demo. Sign in and add an API key to run any of them.
| Service | What it answers | Tool | Runs as |
|---|---|---|---|
| codesets | What is CPT 27447 and is it valid for 2026? | codesets_get_code | one call |
| codesets | Which code covers a total knee replacement? | codesets_search_codes | one call |
| claimcleaner | What is wrong with this claim before I send it? | claimcleaner_clean_claim | one call |
| safeharbor | Remove the identifiers from this clinical sentence. | safeharbor_deidentify_text | one call |
| scholar | What is the 2026 MUE for CPT 27447? | scholar_ask | one call |
| krac | Where is my review job? | krac_get_job_status | one call |
| medicalnotes | Draft a note from this encounter. | medicalnotes_generate_note | background task |
| arse | Code this document and return the 835. | arse_submit_document | background task |
Sign in to open a card, edit the arguments and run it.
What is not here
This page runs one call and shows you one answer. Six parts of the protocol need a real client, because each one holds a conversation or a connection open.
- Follow-up questions inside a call
- A tool can pause and ask for more input before it finishes. This page has nowhere to put the second question, and no session to put it in.
- Tasks, the background lane
- Some tools accept the work now and answer later. Your client polls the task until it finishes. Billing lands when the task finishes, not when you submit it.
- Resource subscriptions
- resources/subscribe pushes an update when a resource changes. That needs a connection that stays open after the call returns.
- Sampling and elicitation
- The server asks your client to run a model call, or to ask the person a question. Only a real client can answer.
- Multi-turn prompt flows
- Prompts are conversation starters. They belong in a chat window, not in a single call form.
- Streaming partial results
- A long answer streams over SSE. This page waits for the whole answer, so you would never see the difference.
Run these with the Inspector
npx @modelcontextprotocol/inspector --transport http --server-url https://api.hank.ai/mcp
Try any tool your key reaches
The tool list comes from the live catalog, and the catalog is different for every key. Sign in and add an API key. This page then lists every tool that key reaches, builds a form from each tool's own input schema, and shows the cost before you run anything.
What is not here
This page runs one call and shows you one answer. Six parts of the protocol need a real client, because each one holds a conversation or a connection open.
- Follow-up questions inside a call
- A tool can pause and ask for more input before it finishes. This page has nowhere to put the second question, and no session to put it in.
- Tasks, the background lane
- Some tools accept the work now and answer later. Your client polls the task until it finishes. Billing lands when the task finishes, not when you submit it.
- Resource subscriptions
- resources/subscribe pushes an update when a resource changes. That needs a connection that stays open after the call returns.
- Sampling and elicitation
- The server asks your client to run a model call, or to ask the person a question. Only a real client can answer.
- Multi-turn prompt flows
- Prompts are conversation starters. They belong in a chat window, not in a single call form.
- Streaming partial results
- A long answer streams over SSE. This page waits for the whole answer, so you would never see the difference.
Run these with the Inspector
npx @modelcontextprotocol/inspector --transport http --server-url https://api.hank.ai/mcp
Capability map
This is the fleet, readable without an account. The access column fills in when you sign in.
| Service | Your access | Listing |
|---|---|---|
| arse Ingests inbound payer mail, EOBs and correspondence as fax, scan, PDF, or image, and never rejects a job. Vision models extract every patient, document, and claim, and emit gated X12 835 remittances for clean EOBs. Over REST and webhooks. | sign in to see | free |
| claimcleaner Validates CPT and ICD codes and modifiers against CMS billing edits, NCCI, MUE, LCD coverage, and fee schedules, then suggests corrections with a full audit trail. Sub-second per claim, over REST, MCP, and web. | sign in to see | free |
| codesets Unified U.S. medical-coding reference to look up, validate, and cross-walk CPT, HCPCS, ICD-10, NDC, and provider taxonomy, plus HCC risk scoring, claim groupers, NCCI edits, and fee schedules, all date-of-service aware. Available over REST, MCP, and CLI. | sign in to see | free |
| krac Turns clinical notes and PDFs into structured coded claims, CPT codes, modifiers, ICD-10 diagnoses, and review flags, with reflexive coding and bundling built in. Submit over the web app, REST API, or MCP; results return by webhook. | sign in to see | free |
| medicalnotes Submit a clinical record as text or PDF and HANK MedicalNotes summarizes the chart, writes a structured note of your chosen type, or classifies it by note type and date of service. Over the web app, REST API, MCP, or webhooks. | sign in to see | free |
| safeharbor HIPAA Safe Harbor de-identification for clinical notes and PDFs, detects the 18 identifiers and replaces each with a consistent, realistic fake instead of a redacted hole, so documents stay readable. Runs fully local, no PHI egress; over REST, MCP, and web. | sign in to see | free |
| scholar Sourced medical-coding answers from a licensed knowledge base, every claim cites its source, with authoritative CPT and ICD descriptors from HANK Codesets. Available as a browser chat, an OpenAI-compatible REST API, or MCP. | sign in to see | free |
tools/list, prompts/list and resources/list are gateway methods, not a service. They are free, and they keep working at the credit ceiling.
This table lists the services the console shows you. Your key decides what you actually reach, and the tool picker reads that from the live catalog, so it can list more than this table does.
When a call is refused
Every refusal is a JSON-RPC error. Read data.http_status first, then data.hank_error_code, then data.retry_after. Read the code, not the message text. The per-service doors at api.hank.ai/v1/<service>/mcp/ return the same two fields, so one error handler covers both.
Before any re-send, read data.metered. The gateway charges a metered call before it routes it, so an error can arrive after the charge: metered: true means the call was billed and data.event_id names the line on your usage page; metered: false means the refusal came first and nothing was billed. A client that re-sends without reading it can pay twice for one failure.
| JSON-RPC | HTTP | retry_after | What to do |
|---|---|---|---|
| -32010 | 401 | null | Your key was refused. Check that it is active, then send it again. A request with no key at all gets an HTTP 401 that carries the RFC 9728 WWW-Authenticate challenge. |
| -32011 | 402 | null | Your organization used this period's credits. Add credits or upgrade, then send the call again. Open billing. Free list calls still run. Exception: when data.headers carries X-Hank-Billing-Hold, your account is on a billing hold. Buying credits or upgrading does not lift it, and list calls are refused too. Contact [email protected]. |
| -32012 | 403 | null | This key may not reach that service. Check your plan, your organization's access settings and the scope of the key. |
| -32013 | 429 | seconds | Wait retry_after seconds, then send the same request. The meter follows the key lineage, so rotating a key does not reset it. |
| -32014 | 451 | null | Your organization must accept the Terms first. Read and accept the Terms. |
| -32015 | 503 | null | The gateway or the service behind it could not answer. This can arrive after the charge: read data.metered before you re-send. When it is true, the call was billed under data.event_id, so check your usage page first. When it is false, nothing was billed and a re-send is safe. If it keeps failing, check the status page. |
| -32602 | 400 | null | The tool name is not in your catalog, or an argument is wrong. Call tools/list and use a name from the answer. |
| -32020 | 400 | null | A routing header does not match the body. On tools/call the Mcp-Name header must equal params.name, and Mcp-Method must equal the method. |
Example, credit ceiling
{
"jsonrpc": "2.0",
"id": 7,
"error": {
"code": -32011,
"message": "Credit limit reached for the current period",
"data": {
"http_status": 402,
"retry_after": null,
"service": "codesets",
"metered": false
}
}
}
{
"jsonrpc": "2.0",
"id": 8,
"error": {
"code": -32013,
"message": "Edge rate limit exceeded",
"data": {
"hank_error_code": "RATE_LIMIT",
"http_status": 429,
"retry_after": 12,
"metered": false
}
}
}
What is not here
This page runs one call and shows you one answer. Six parts of the protocol need a real client, because each one holds a conversation or a connection open.
- Follow-up questions inside a call
- A tool can pause and ask for more input before it finishes. This page has nowhere to put the second question, and no session to put it in.
- Tasks, the background lane
- Some tools accept the work now and answer later. Your client polls the task until it finishes. Billing lands when the task finishes, not when you submit it.
- Resource subscriptions
- resources/subscribe pushes an update when a resource changes. That needs a connection that stays open after the call returns.
- Sampling and elicitation
- The server asks your client to run a model call, or to ask the person a question. Only a real client can answer.
- Multi-turn prompt flows
- Prompts are conversation starters. They belong in a chat window, not in a single call form.
- Streaming partial results
- A long answer streams over SSE. This page waits for the whole answer, so you would never see the difference.
Run these with the Inspector
npx @modelcontextprotocol/inspector --transport http --server-url https://api.hank.ai/mcp