Connect an agent over MCP

HANK PPMan exposes its payer-policy retrieval over the Model Context Protocol, so any MCP-capable agent can search payer medical & billing policies and pull the full stored document text, without scraping bot-walled payer sites. REST API docs →

MCP endpoint https://api.hank.ai/v1/ppman/mcp/

Step 1: get an access token

This server is token-gated. Generate or copy a Hank access token in the console, then drop it into one of the configs below in place of YOUR_TOKEN.

Open console.hank.ai →

Step 2: add the server to your agent

Clients that send an auth header · recommended, token stays out of the URL

Claude Code (CLI)

Run in your terminal:

terminal

claude mcp add --transport http hank-ppman https://api.hank.ai/v1/ppman/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN"

Claude Desktop · claude_desktop_config.json

Desktop has no header field, so bridge it with mcp-remote so the token rides in a header, not the URL:

claude_desktop_config.json

{
  "mcpServers": {
    "hank-ppman": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.hank.ai/v1/ppman/mcp/",
        "--header", "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Cursor · ~/.cursor/mcp.json (or .cursor/mcp.json)

Cursor speaks HTTP MCP with a headers block:

mcp.json

{
  "mcpServers": {
    "hank-ppman": {
      "url": "https://api.hank.ai/v1/ppman/mcp/",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

ChatGPT / OpenAI API · Agents SDK / Responses API

MCP tool block (Responses API shape):

tools[] entry

{
  "type": "mcp",
  "server_label": "hank-ppman",
  "server_url": "https://api.hank.ai/v1/ppman/mcp/",
  "headers": { "Authorization": "Bearer YOUR_TOKEN" }
}

Generic MCP client

Bare entry for any agent that takes a URL and a headers block:

config entry

{
  "hank-ppman": {
    "url": "https://api.hank.ai/v1/ppman/mcp/",
    "headers": { "Authorization": "Bearer YOUR_TOKEN" }
  }
}

URL-only connectors · the token goes IN the URL

⚠ These clients only accept a URL (no header field), so the token must ride in the URL. URL tokens can land in server logs and browser history. Prefer a header-based client above when you can, and rotate the token if it leaks.

ChatGPT · Apps / Developer mode (web + desktop)

Settings → Apps → Advanced → enable Developer mode → "Create app" → paste this URL, Authentication = "No authentication":

MCP server URL

https://api.hank.ai/v1/ppman/mcp/?token=YOUR_TOKEN

Claude.ai / Claude Desktop · "Add custom connector"

Settings → Connectors → Add custom connector → paste this URL (use when you are not bridging with mcp-remote):

MCP server URL

https://api.hank.ai/v1/ppman/mcp/?token=YOUR_TOKEN

Available tools

Once connected, your agent can call:

lookup

Search payer medical/billing policy DOCUMENTS by a clinical or billing topic (hybrid semantic + keyword). Optionally scope to one payer. Returns documents with snippets and their extracted billing rules.

fetch_document

Fetch HANK's stored copy of a policy document — the full scraped policy text plus extracted billing rules — by source_id from a lookup result (no need to re-fetch the payer's bot-walled site).

payer_suggest

Resolve a partial payer name to candidate payers ({id, name}) — use to find the exact payer string to pass to lookup's `payer` argument.

topic_suggest

Suggest clinical/billing TOPICS that HANK actually has indexed policy documents for (grounded — never invents a topic). Discover what you can ask lookup about, or disambiguate a vague topic.

policy_changes

Policy CHANGE history for a payer (brand family) — dated rows of detected changes (effective date, type, severity, summary), optionally since a date. Answers 'how has <payer>'s policy changed over time'. Metered.

resolve_payer

Resolve partial insurance-identity FIELDS (company, plan, EDI payer id, NAIC, phone, state, BlueCard prefix — never a full member id) to the true top-level payer + corporate chain + applicable policies + PT-rate link. The RCM 'find my payer' use case. Metered.

applicable_policies

Which policies APPLY to a payer (+ optional state / line_of_business / procedure code) — the authority set (CMS/MAC inheritance) narrowed deterministically, each with a typed basis + rationale. confirmed_by='deterministic' if the LLM was unreachable. Metered.