MCP Server

The Backwork MCP server lets AI clients query coverage policies, look up codes, validate claims, and check prior authorization requirements in real time.

Current setup

For Claude Code, use the hosted Streamable HTTP MCP endpoint with OAuth. This does not require copying a Backwork API key into Claude Code:

claude mcp remove backwork 2>/dev/null || true
claude mcp add --transport http --scope user backwork https://backworkhealth.com/mcp

Then start Claude Code and authenticate the server:

claude

Inside Claude Code, run:

/mcp

Select backwork, complete the browser login, approve the Backwork consent screen, and return to Claude Code.

Codex currently uses the local stdio server with a Backwork API key:

export BACKWORK_API_KEY=bwk_live_YOUR_API_KEY
codex mcp add backwork --env BACKWORK_API_KEY=$BACKWORK_API_KEY -- npx -y @backwork/mcp

Use the local stdio setup when your MCP client does not support remote Streamable HTTP yet, or when you want to run the server entirely on your machine.

Codex

Use local stdio with a Backwork API key:

export BACKWORK_API_KEY=bwk_live_YOUR_API_KEY
codex mcp add backwork --env BACKWORK_API_KEY=$BACKWORK_API_KEY -- npx -y @backwork/mcp

The hosted Backwork MCP endpoint requires OAuth. Do not use a Backwork API key as a bearer token against https://backworkhealth.com/mcp. If you operate a private self-hosted HTTP server in API-key or dual-auth mode, Codex can connect to that private URL with --bearer-token-env-var.

Claude Code

For hosted Streamable HTTP, use OAuth:

claude mcp remove backwork 2>/dev/null || true
claude mcp add --transport http --scope user backwork https://backworkhealth.com/mcp

Then run claude, open /mcp, and authenticate backwork. Claude Code discovers the OAuth protected-resource metadata, opens your browser, sends you through Backwork login, and stores the OAuth token after you approve the consent screen.

Verify the server is configured:

claude mcp list
claude mcp get backwork

If OAuth discovery needs to be pinned explicitly, add the same server as JSON:

claude mcp remove backwork 2>/dev/null || true
claude mcp add-json backwork '{
  "type": "http",
  "url": "https://backworkhealth.com/mcp",
  "oauth": {
    "authServerMetadataUrl": "https://backworkhealth.com/.well-known/oauth-authorization-server",
    "scopes": "backwork:mcp read"
  }
}'

authServerMetadataUrl requires Claude Code v2.1.64 or newer. Keep scopes pinned so Claude Code requests only the Backwork MCP read scope even if metadata discovery changes.

For older Claude Code clients that cannot complete remote OAuth, use local stdio:

claude mcp add backwork -e BACKWORK_API_KEY=bwk_live_YOUR_API_KEY -- npx -y @backwork/mcp

Cursor, VS Code, Windsurf, and other clients

For clients that only support stdio:

{
  "mcpServers": {
    "backwork": {
      "command": "npx",
      "args": ["-y", "@backwork/mcp"],
      "env": {
        "BACKWORK_API_KEY": "bwk_live_YOUR_API_KEY"
      }
    }
  }
}

The hosted Backwork MCP endpoint requires OAuth. For clients that only support static remote URLs and bearer headers, run a private self-hosted MCP server in API-key or dual-auth mode, then set the bearer header using the client's documented secret or environment mechanism. If the client only accepts static JSON, replace the placeholder directly:

{
  "mcpServers": {
    "backwork": {
      "url": "https://your-private-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer bwk_live_YOUR_API_KEY"
      }
    }
  }
}

Self-hosting

Run the MCP server over Streamable HTTP:

git clone https://github.com/tylergibbs1/backwork-mcp.git
cd backwork-mcp
npm install
npm run build
npm run start:http

Defaults:

HTTP mode requires Authorization: Bearer <Backwork API key> by default. For a private single-tenant deployment that supplies the API key from the server environment, set:

BACKWORK_MCP_ALLOW_ENV_KEY=true BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm run start:http

Only use BACKWORK_MCP_ALLOW_ENV_KEY=true on loopback or private-network deployments protected by network access control. Public deployments should require a bearer token per request, set BACKWORK_MCP_ALLOWED_HOSTS/BACKWORK_MCP_PUBLIC_HOST, and set BACKWORK_MCP_ALLOWED_ORIGINS only to exact browser origins that may connect.

OAuth deployment configuration

For the hosted Backwork OAuth flow, the web app must issue tokens for the MCP resource:

BACKWORK_OAUTH_ISSUER=https://backworkhealth.com
BACKWORK_OAUTH_SIGNING_SECRET=<generate with: openssl rand -base64 48>
BACKWORK_MCP_RESOURCE=https://backworkhealth.com/mcp

Production OAuth discovery fails closed unless BACKWORK_OAUTH_SIGNING_SECRET is at least 32 characters and one of these durable state stores is configured for one-time consent and authorization-code storage:

# Upstash Redis
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...

# or Vercel KV
KV_REST_API_URL=...
KV_REST_API_TOKEN=...

The MCP server must advertise Backwork as its authorization server and validate Backwork access tokens:

BACKWORK_MCP_AUTH_MODE=oauth
BACKWORK_MCP_PUBLIC_HOST=backworkhealth.com
BACKWORK_MCP_PUBLIC_URL=https://backworkhealth.com
BACKWORK_MCP_ALLOWED_HOSTS=backworkhealth.com,mcp.backworkhealth.com,backwork-mcp.vercel.app
BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS=https://backworkhealth.com
BACKWORK_MCP_OAUTH_RESOURCE=https://backworkhealth.com/mcp
BACKWORK_MCP_OAUTH_SCOPES="backwork:mcp read"
BACKWORK_MCP_OAUTH_REQUIRED_SCOPES=backwork:mcp
BACKWORK_MCP_OAUTH_INTROSPECTION_URL=https://backworkhealth.com/api/oauth/introspect
BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE=https://backworkhealth.com/mcp

Hosted endpoint

The hosted MCP server exposes:

Hosted MCP requests authenticate with Backwork OAuth access tokens for Claude Code and other OAuth-capable clients. The hosted endpoint does not accept Backwork API keys as bearer tokens; use local stdio or a private self-hosted HTTP deployment for API-key auth.

Usage, billing, and attribution

MCP usage counts as Backwork API usage. Each MCP tool call can make one or more downstream Backwork API requests, and those requests consume the same plan usage, monthly API call budget, and rate-limit budget as direct API calls.

Attribution depends on how the MCP client authenticates:

In the Backwork dashboard, MCP traffic appears with source mcp. Organization admins can review usage by credential, member, source, and MCP tool. Non-admin members see aggregate organization usage without member or OAuth-principal details.

The official MCP server annotates downstream requests automatically. Self-hosted deployments should use the official server build or preserve its Backwork request headers so usage can be attributed to the correct MCP tool.

Available tools

Tool names use the backwork_ prefix for discoverability when this server is installed alongside other MCP servers. The default tool surface is workflow-level rather than a 1:1 wrapper around every API endpoint, so common agent tasks need fewer tool calls.

All tools return readable text plus structuredContent with a message field and, when available, Backwork API data and meta. Every tool accepts optional response_format: "markdown" or response_format: "json".

Example prompts

Is ultrasound guidance (76942) covered in Texas, and does it need prior auth?

What changed in Medicare CGM coverage policies in the last 30 days?

Compare coverage for J0585 (Botox) across JM and JH jurisdictions.

Validate denial risk for 99213 with diagnosis E11.9 for Medicare in Texas.

Environment variables

Troubleshooting Claude Code OAuth

If Claude Code does not open the browser, run /mcp, select backwork, and choose the authenticate action. If it gives you a URL instead of opening a browser, copy that URL into your browser.

If the browser redirect back to Claude Code fails after consent, copy the full callback URL from the browser address bar and paste it into the Claude Code prompt.

If Claude Code keeps using an old token, open /mcp, select backwork, clear authentication, then authenticate again. You can also remove and re-add the server with:

claude mcp remove backwork
claude mcp add --transport http --scope user backwork https://backworkhealth.com/mcp

If discovery returns 503, the Backwork web app is intentionally refusing to advertise OAuth because production signing or Redis/KV state storage is missing.

If tool calls authenticate but fail with invalid_token or invalid_target, check that BACKWORK_MCP_RESOURCE, BACKWORK_MCP_OAUTH_RESOURCE, and BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE all use:

https://backworkhealth.com/mcp

When to use MCP vs Agent Tools API

Use the MCP server when:

• A developer or analyst is chatting with an AI assistant and needs ad-hoc coverage lookups
• You want Backwork access inside Claude, Codex, Cursor, VS Code, or another MCP-compatible client
• The use case is exploratory — research, policy review, or answering one-off questions

Use the Agent Tools API when:

• You're building a production application with an embedded agent
• You need audit logging of every tool invocation
• PHI must be explicitly rejected at the API layer
• Your workflow requires human review checkpoints and approval flows
• You need per-tool scope controls beyond a single API key

Last updated on