MCP Server

The Backwork MCP server lets an AI client search coverage policies, look up codes, validate claims, and check prior-authorization requirements.

The hosted server needs no install. Add its URL to your client and sign in with your Backwork account:

https://backworkhealth.com/mcp

Before you start

You need a Backwork account in an organization. Sign up free; your organization starts with 100 free starter credits. MCP tool calls spend the organization's request credits, like direct API calls. See Usage and credits.

Add the hosted server

The server uses Streamable HTTP and OAuth. The first time your client connects, it opens a browser. Sign in to Backwork, review the consent screen, and approve. You do not copy an API key into the client.

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

Use https://backworkhealth.com/mcp, not the mcp.backworkhealth.com host behind it: OAuth tokens are issued for the backworkhealth.com/mcp resource.

What the sign-in grants

The client registers itself and uses PKCE (S256); your client handles both. It requests the scopes backwork:mcp read, and the consent screen shows the access as Read only.

• Tools and actions that read data work.
• Actions that change data need the write scope, which the hosted sign-in does not grant. These are acknowledge and bulk_acknowledge in backwork_compliance_review, and every action of backwork_webhook_management, which also needs the Scale pack. For those, call the API with a key that has write; see Authentication.

The hosted server does not accept API keys as bearer tokens. For API-key auth, use the local server or a self-hosted one.

Token lifetimes and refresh

The token endpoint (https://backworkhealth.com/api/oauth/token) supports the authorization_code and refresh_token grants.

MCP clients refresh tokens for you. If you write your own client:

curl -X POST https://backworkhealth.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d client_id="$CLIENT_ID" \
  -d refresh_token="$REFRESH_TOKEN"

• Each refresh returns a new access token and a new refresh token. The old refresh token stops working. Store the new one.
• If a refresh token is used a second time, Backwork revokes every token from that consent. The user must approve the client again.
• Only the client that got the refresh token can use it.
• scope is optional. It can ask for fewer scopes than the user approved, never more.
• resource, if sent, must be the resource the user approved.
• Each refresh checks that the user is still a member of the organization. If not, Backwork revokes the tokens.
• After 30 days the refresh token expires, even if the client used it. The user approves the client again.

A refused refresh returns HTTP 400 with invalid_grant, invalid_scope, or invalid_target: get a new consent. A 503 with server_error means Backwork could not check the membership: retry later with the same refresh token.

To disconnect, send the refresh token to the RFC 7009 revocation endpoint. This revokes all tokens from that consent:

curl -X POST https://backworkhealth.com/api/oauth/revoke \
  -d client_id="$CLIENT_ID" \
  -d token="$REFRESH_TOKEN"

An access token issued before a revocation works until it expires, at most 1 hour.

Usage and credits

Each MCP tool call makes one or more requests to the Backwork API as you, so it spends your organization's request credits and counts against its per-minute limit, at the same cost per endpoint as a direct call. backwork_coverage_lookup, for example, can combine a code lookup, a prior-auth check, a claim check, and a jurisdiction comparison in one tool call.

When the credits run out, tool calls fail with 402 BILLING_CREDITS_EXHAUSTED until the balance covers them. An organization admin manages the plan and usage in API usage and keys.

MCP requests appear in the usage data with source mcp and the tool name, attributed to:

Available tools

Tool names start with backwork_. Each tool covers a workflow rather than a single endpoint, so common tasks take fewer calls.

Every tool returns readable text plus structuredContent with a message and, when available, the API's data and meta. Every tool accepts response_format: "markdown" (default) or "json".

If a tool's description lists actions as not available on the production API yet, those actions return an error without calling the API and spend no credits. Do not retry them.

Codes in tool results carry a source. Confirm an inferred_title_match code against the policy document; see Code sources.

Example prompts

Does CPT 76942 need prior authorization in Texas? Cite the policies.

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

Compare coverage for J0585 across the JM and JH jurisdictions.

Local (npm)

The local server (@backwork/mcp on npm, published with provenance) runs over stdio on your machine and authenticates with a live API key from API usage and keys:

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

The same command works with claude mcp add backwork -e BACKWORK_API_KEY=... -- npx -y @backwork/mcp and codex mcp add backwork --env BACKWORK_API_KEY=... -- npx -y @backwork/mcp. A key from API usage and keys has the read scope, so the same write actions as above are refused.

Self-hosting

You can also build the server from its repository. It needs Node.js 18 or later.

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

For stdio, point your client at the build:

{
  "mcpServers": {
    "backwork": {
      "command": "node",
      "args": ["/path/to/backwork-mcp/build/src/index.js"],
      "env": { "BACKWORK_API_KEY": "bwk_live_YOUR_API_KEY" }
    }
  }
}

For Streamable HTTP, run npm run start:http. HTTP mode requires Authorization: Bearer <Backwork API key> on each request by default.

For a private single-tenant deployment that takes the key from its environment:

BACKWORK_MCP_ALLOW_ENV_KEY=true BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm run start:http

Use BACKWORK_MCP_ALLOW_ENV_KEY=true only on loopback or private networks with network access control. A public deployment should require a bearer token on every request, set BACKWORK_MCP_ALLOWED_HOSTS or BACKWORK_MCP_PUBLIC_HOST, and set BACKWORK_MCP_ALLOWED_ORIGINS only to the exact browser origins that may connect.

Keep the server's X-Backwork-Client and X-Backwork-MCP-Tool request headers so usage is attributed to the right tool.

Environment variables

Hosted endpoints

Troubleshooting

• The browser does not open. In Claude Code, run /mcp, select backwork, and choose Authenticate; copy the URL it shows into your browser. In Codex, run codex mcp login backwork --no-browser.
• The redirect back to the client fails after consent. Copy the full callback URL from the browser's address bar and paste it into the client's prompt.
• invalid_grant on refresh. The grant was revoked or expired. Sign in again.
• The client keeps using an old token. Clear the server's authentication in the client (in Claude Code: /mcp, select backwork, clear authentication) and sign in again.
• A tool fails with a scope error. The action needs write; see What the sign-in grants.
• A tool fails with 402. Your organization is out of request credits. Buy more in API usage and keys.

When to use MCP or the Agent Tools API

Use the MCP server when:

• a person is working in an AI client and needs coverage lookups;
• you want Backwork inside Claude, Codex, Cursor, VS Code, or another MCP client;
• the work is exploratory: research, policy review, or one-off questions.

Use the Agent Tools API when:

• you are building an application with an embedded agent;
• you need an audit record of every tool call;
• PHI must be rejected at the API;
• your workflow needs human review and approval steps;
• you need per-tool scopes.

Last updated on