@backwork/mcp

Backwork MCP Server

Official Model Context Protocol (MCP) server for the Backwork API. It gives AI assistants controlled access to Medicare and payer medical policies, medical code intelligence, prior authorization checks, claim validation, compliance review, drug formulary evidence, and webhook operations.

There are two ways to connect:

	Hosted remote	Local stdio
Endpoint	https://backworkhealth.com/mcp (Streamable HTTP)	npx -y @backwork/mcp
Auth	OAuth in the browser, no key to copy	BACKWORK_API_KEY=bwk_live_...
Use when	Your client supports remote MCP with OAuth	Your client only runs local commands, or you want the server on your machine

The hosted endpoint only accepts OAuth. Do not send a Backwork API key as a bearer token to https://backworkhealth.com/mcp. The OAuth grant is read-only (backwork:mcp read), so the hosted server offers only read actions: no webhook management and no compliance acknowledgements. Use local stdio with a write-scoped live key for those.

Calls draw on your organization's request credits, like any other /api/v1 call. A bwk_test_ key works only on the sandbox (https://backworkhealth.com/api/sandbox/v1), which covers policy search, code lookup, prior-auth check and coverage evaluation; to use it, set BACKWORK_API_BASE to that URL.

Claude Code

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

Add --scope user to make it available in every project. Then run claude, open /mcp, select backwork, and finish the browser login and Backwork consent screen. Check it with claude mcp get backwork.

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

claude mcp add-json backwork '{
  "type": "http",
  "url": "https://backworkhealth.com/mcp",
  "oauth": {
    "scopes": "backwork:mcp read"
  }
}'

Local stdio:

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

Claude Desktop

Hosted remote: open Settings > Connectors > Add custom connector, name it Backwork, and enter https://backworkhealth.com/mcp. Claude Desktop runs the OAuth login when you connect.

Local stdio: add this to claude_desktop_config.json (Settings > Developer > Edit Config) and restart Claude Desktop:

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

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor opens the OAuth login the first time it connects:

{
  "mcpServers": {
    "backwork": {
      "url": "https://backworkhealth.com/mcp"
    }
  }
}

Local stdio:

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

VS Code

code --add-mcp '{"name":"backwork","type":"http","url":"https://backworkhealth.com/mcp"}'

Or add it to .vscode/mcp.json in a workspace. VS Code asks you to sign in when the server starts:

{
  "servers": {
    "backwork": {
      "type": "http",
      "url": "https://backworkhealth.com/mcp"
    }
  }
}

Local stdio, with the key prompted for once and stored by VS Code:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "backwork-api-key",
      "description": "Backwork API key",
      "password": true
    }
  ],
  "servers": {
    "backwork": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@backwork/mcp"],
      "env": {
        "BACKWORK_API_KEY": "${input:backwork-api-key}"
      }
    }
  }
}

Codex

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

Other MCP Clients

Clients that run local commands can use the stdio config shown for Claude Desktop. Clients that support remote URLs with OAuth can use https://backworkhealth.com/mcp directly.

For clients that support only remote URLs with static headers, deploy a private self-hosted server in API-key or dual-auth mode (see Self-Hosting) and send the key as a bearer header:

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

Self-Hosting

Run a Streamable HTTP server:

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

Defaults:

Setting	Default	Override
Transport	stdio	--http or BACKWORK_MCP_TRANSPORT=http
Host	127.0.0.1	--host or BACKWORK_MCP_HOST
Port	3000	--port or BACKWORK_MCP_PORT or PORT
MCP path	/mcp	--path or BACKWORK_MCP_PATH
Allowed hosts	loopback/private hosts, VERCEL_URL, or configured public host	BACKWORK_MCP_ALLOWED_HOSTS or BACKWORK_MCP_PUBLIC_HOST

HTTP mode requires Authorization: Bearer per request. By default this bearer is a Backwork API key. For hosted remote MCP deployments, enable OAuth protected-resource discovery so Claude-compatible clients can authenticate users through your authorization server:

BACKWORK_MCP_AUTH_MODE=oauth \
BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS=https://backworkhealth.com \
BACKWORK_MCP_OAUTH_SCOPES="backwork:mcp read" \
npm run start:http

The server publishes OAuth Protected Resource Metadata at /.well-known/oauth-protected-resource and includes that URL in WWW-Authenticate challenges. If your Backwork API accepts OAuth access tokens directly, no extra mapping is needed; the MCP server forwards the OAuth bearer downstream. If your authorization server exposes a Backwork API key in token introspection, set BACKWORK_MCP_OAUTH_INTROSPECTION_URL and BACKWORK_MCP_OAUTH_API_KEY_CLAIM to validate the access token and map it to the downstream Backwork credential.

For a private single-tenant deployment where the server environment supplies the key, 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.

Vercel Hosting

This repo can deploy as an API-only Vercel project. The production project uses:

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

The Vercel functions expose:

Path	Purpose
/mcp	Streamable HTTP MCP endpoint
/health	Lightweight MCP server health check
/.well-known/oauth-protected-resource	OAuth protected-resource metadata when OAuth is configured
/	Basic endpoint metadata

The Backwork web app that issues OAuth tokens must also be configured:

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 Redis or Vercel KV is configured for one-time consent and authorization-code storage.

Health check:

curl http://localhost:3000/health

Local Development

npm install
npm run build
BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm start

Useful commands:

npm run start:http
node build/src/index.js --help

Requires Node.js 18 or newer.

Available Tools

Tool names use the backwork_ prefix for discoverability when this server is installed alongside other MCP servers. The default surface is intentionally workflow-level rather than a 1:1 API wrapper, so agents see fewer choices and common tasks require fewer tool calls.

All tools include title, description, inputSchema, outputSchema, and MCP annotations. Successful calls return readable text plus structuredContent with message, and when available, raw Backwork API data and meta. Tool-level failures return isError: true. For tools that combine read and write actions, annotations are conservative at the tool level.

Sources and currency

When the Backwork API response cites policy documents, structuredContent.provenance carries what an agent needs to cite them, and the text output ends with a short --- Sources --- block:

Field	Meaning
source_urls	Distinct source document URLs
authorities	Issuing authorities, for example CMS or a payer name
retrieved_at	Oldest time Backwork fetched any cited source
as_of	Latest effective date among the cited sources
sources[]	policy_id, source_url, authority, retrieved_at, as_of per source

Values are copied from the API response (source_url, effective_date, last_verified_at, the policy type, and the payer). A value the API did not return is null. The shape matches the provenance block on Backwork agent tool results, which is passed through unchanged.

Production availability

Which actions a server offers depends on two things:

• Availability. The Backwork OpenAPI document can mark an operation x-backwork-availability: unavailable-in-production. Against the production API (https://backworkhealth.com) the server withholds those actions. None is marked today: production serves every /api/v1 operation these tools call to an organization's live key.
• Access. Operations that need write scope (x-backwork-required-scopes) are withheld from a read-only OAuth grant. On the hosted server this hides backwork_webhook_management and the acknowledge and bulk_acknowledge actions of backwork_compliance_review. A Backwork API key is offered every action, and the API enforces the key's own scopes.

A tool with no offered action is hidden. A partly offered tool drops the withheld actions from its action input and names them in its description. A server pointed at another Backwork deployment with BACKWORK_API_BASE ignores availability markers, and BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS=true does the same against production. Neither lifts the write-scope rule.

Primary tool	Purpose
backwork_coverage_lookup	Look up procedure codes and combine code details, policy evidence, prior authorization, claim risk, jurisdiction comparison, and spending evidence
backwork_policy_research	Search policies, fetch one policy, search extracted criteria, review policy changes, or map MAC jurisdictions
backwork_claim_validation	Validate claim coverage, documentation requirements, denial risk, and optional policy-specific criteria
backwork_prior_auth_research	Check Medicare prior authorization, start payer website research, or poll an async research task
backwork_drug_formulary_research	Search commercial pharmacy-benefit evidence from CVS Caremark, Express Scripts, and UnitedHealthcare / Optum Rx
backwork_compliance_review	Review compliance stats, list unreviewed policy changes, or acknowledge changes
backwork_webhook_management	List, create, update, delete, or test webhook endpoints. Backwork sends one event, compliance.acknowledged; policy-change webhooks are not sent. Needs a write-scoped API key
backwork_system_health	Check Backwork API health and dependency status

Response Format

Every tool accepts:

{
  "response_format": "markdown"
}

Use "markdown" for readable output or "json" to make the text content mirror the returned structuredContent.

Example Prompts

Is CPT 76942 covered in Texas, and does it require prior authorization?

Compare coverage for J0585 across JM and JH.

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

Search formulary evidence for Ozempic across commercial PBMs.

Testing and Evaluations

Run the build and MCP metadata smoke test:

npm test

The smoke test starts the built stdio server with a dummy key, verifies the 8 workflow tools, checks titles, schemas, annotations, output schemas, response_format, and verifies local validation failures are reported with isError: true. The test/ suite covers production availability, the hosted server's OAuth-only, read-only tool set, provenance, description quality and a lexical tool-selection check (no model calls), and the registry manifest.

API contract

Every Backwork endpoint this server calls is listed in src/api-operations.ts, with the request fields it sends and the response fields it reads. Tools can only call the API through that catalog. Each entry also mirrors the operation's availability marker and required scope. npm test checks the catalog against the vendored openapi/backwork-openapi.json, and asks the server's own exposure rule which tool actions it would offer on production, for a read-only OAuth grant and for an API key. An action offered for an operation that production does not serve, marks unavailable, or (for the OAuth grant) guards with write scope fails.

CI runs npm run contract:live, which runs the same checks against https://backworkhealth.com/openapi.json and fails when the vendored copy differs from it anywhere except descriptions, summaries and examples.

When the Backwork API changes, refresh the vendored copy and review the diff:

npm run openapi:update
npm run contract:check

The evals/ directory includes a tool-discoverability evaluation and a read-only data evaluation built from fixed source-backed policy/code records. Refresh the read-only answers intentionally when Backwork source data is updated.

MCP Registry

server.json describes this server for the official MCP registry as io.github.tylergibbs1/backwork-mcp: the hosted Streamable HTTP remote at https://backworkhealth.com/mcp (OAuth, discovered from the protected-resource metadata) and the @backwork/mcp npm package over stdio. package.json carries the matching mcpName that the registry uses to verify npm ownership. npm test validates server.json against the registry schema and checks that its versions match package.json.

Release

Releases publish @backwork/mcp to npm with Trusted Publishing (GitHub OIDC, no npm token) and then publish server.json to the MCP registry.

• npm version minor (or patch/major). The version script copies the new version into server.json and SERVER_VERSION in src/index.ts.
• Merge that change to main.
• Push a matching tag from main, for example git tag v2.1.0 && git push origin v2.1.0.

The Release workflow then:

• Fails unless the tag equals v + the package.json version.
• Runs npm ci, npm test (build, smoke tests, unit tests, OpenAPI contract), and npm pack --dry-run.
• Publishes to npm with provenance, in the npm environment. A version already on npm is skipped, so a failed run can be re-run.
• Waits for the version to appear on npm, then runs mcp-publisher login github-oidc and mcp-publisher publish.

One-time npm setup: on npmjs.com, open @backwork/mcp > Settings > Trusted publishing, choose GitHub Actions, and enter user tylergibbs1, repository backwork-mcp, workflow release.yml, environment npm.

Environment Variables

Variable	Required	Description
BACKWORK_API_KEY	Stdio yes; HTTP no	Backwork API key. In HTTP mode, prefer Authorization: Bearer per request.
BACKWORK_API_BASE	No	Override the API base URL.
BACKWORK_MCP_TRANSPORT	No	stdio or http.
BACKWORK_MCP_HOST	No	HTTP bind host. Defaults to 127.0.0.1.
BACKWORK_MCP_PORT	No	HTTP bind port.
BACKWORK_MCP_PATH	No	HTTP MCP path.
BACKWORK_MCP_ALLOWED_ORIGINS	No	Comma-separated allowed HTTP origins. Loopback origins are allowed for loopback requests.
BACKWORK_MCP_ALLOW_ORIGIN	No	Backward-compatible alias for BACKWORK_MCP_ALLOWED_ORIGINS.
BACKWORK_MCP_ALLOWED_HOSTS	No	Comma-separated allowed HTTP Host headers for public deployments.
BACKWORK_MCP_ALLOW_HOST	No	Backward-compatible alias for BACKWORK_MCP_ALLOWED_HOSTS.
BACKWORK_MCP_PUBLIC_HOST	No	Primary public host allowed for HTTP requests.
BACKWORK_MCP_PUBLIC_URL	No	Canonical public origin for OAuth metadata, e.g. https://backworkhealth.com.
BACKWORK_MCP_ALLOW_ENV_KEY	No	Allow private HTTP requests without bearer auth to use BACKWORK_API_KEY.
BACKWORK_MCP_AUTH_MODE	No	HTTP bearer mode: api-key, oauth, or dual. Defaults to dual when OAuth authorization servers are configured, otherwise api-key.
BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS	OAuth	Comma-separated OAuth issuer / authorization server URLs advertised in protected-resource metadata.
BACKWORK_MCP_OAUTH_RESOURCE	No	Override the RFC 8707 resource identifier. Defaults to the public MCP URL.
BACKWORK_MCP_OAUTH_SCOPES	No	Space- or comma-separated scopes advertised to clients. Defaults to backwork:mcp.
BACKWORK_MCP_OAUTH_REQUIRED_SCOPES	No	Space- or comma-separated scopes required after token introspection.
BACKWORK_MCP_OAUTH_INTROSPECTION_URL	No	RFC 7662 token introspection endpoint used to validate OAuth access tokens.
BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_ID	No	Client ID for introspection basic auth.
BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_SECRET	No	Client secret for introspection basic auth.
BACKWORK_MCP_OAUTH_INTROSPECTION_TOKEN	No	Bearer token for introspection when basic auth is not used.
BACKWORK_MCP_OAUTH_API_KEY_CLAIM	No	Dot-path claim from introspection response to use as the downstream Backwork credential. If omitted, the OAuth access token is forwarded.
BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE	No	Comma-separated allowed aud values when introspection responses include an audience.
BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS	No	true offers tools and actions the production API marks unavailable. Write-scope actions stay hidden from read-only OAuth grants.

Troubleshooting

Missing API Key

For stdio, set BACKWORK_API_KEY in the MCP client configuration. For HTTP API-key mode, send Authorization: Bearer <key>. For HTTP OAuth mode, configure BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS and send Authorization: Bearer <access_token>.

401 From HTTP MCP

The remote server did not receive a bearer token. Configure your MCP client to authenticate with OAuth or send an Authorization header. OAuth-enabled deployments include resource_metadata in the WWW-Authenticate header to point clients at /.well-known/oauth-protected-resource.

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.

This server does not hold OAuth tokens. It validates each request's access token by introspection and forwards it (or the mapped API key) to the Backwork API. Refreshing an expired access token is the MCP client's job: when introspection reports a token inactive, the server answers 401 with error="invalid_token", and the client can use its refresh token with the Backwork authorization server.

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

Rate Limits

Wait for the reset window or use a higher-capacity API plan.

Support

• Documentation: https://backworkhealth.com/docs
• Issues: https://github.com/tylergibbs1/backwork-mcp/issues
• Email: [e-mail]

License

MIT. See LICENSE.