Backwork

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.

Quick start

The fastest way in is the hosted server with Claude Code:

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

There are two ways to connect:

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.

Setup for each client is in Connect your client. Agent-oriented install notes are in llms-install.md.

How it works

flowchart LR

client[MCP client] -->|stdio or Streamable HTTP| server[Backwork MCP server] server -->|API key or OAuth bearer| api[Backwork API /api/v1]

The server exposes eight workflow-level tools rather than one tool per endpoint. Each tool calls the Backwork API only through the operation catalog in src/api-operations.ts, returns readable text plus structuredContent, and cites the policy sources it used. Which tools and actions you see depends on how you connect (see Production availability).

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.

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.

Connect your client

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 Code plugin

The backwork plugin bundles the hosted MCP server with four research skills: prior authorization, coverage checks, policy changes, and denial appeal prep. Install it from this repository's plugin marketplace:

/plugin marketplace add tylergibbs1/backwork-mcp

/plugin install backwork@backwork

Then run /mcp, select plugin:backwork:backwork, and finish the OAuth sign-in. New accounts start with 100 free credits. See plugins/backwork/README.md for the skills and the /backwork:pa and /backwork:coverage commands.

The marketplace manifest is .claude-plugin/marketplace.json. npm test checks the manifests and every SKILL.md. CI also runs claude plugin validate --strict on the marketplace and the plugin.

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

ChatGPT

ChatGPT connects to the hosted server as a custom MCP connection in developer mode. Three tools return a small card that ChatGPT renders inline above its answer.

1. In ChatGPT, open Settings → Security and login and turn on Developer mode. Your plan or workspace admin may need to allow it.
2. Go to chatgpt.com/plugins and select the + button.
3. Name it Backwork, add a short description, and under Connection enter https://backworkhealth.com/mcp. Choose OAuth for authentication.
4. Select Create. ChatGPT opens Backwork's sign-in page; approve the read-only backwork:mcp read grant.
5. Check the discovered tools, then start a new chat, add Backwork from the tools menu, and ask something like *"Is CPT 76942 covered in Texas, and does it need prior auth?"*

After a server update, open the connection at chatgpt.com/plugins and select Refresh so ChatGPT picks up new tool and component metadata.

ChatGPT loads a tool's card for every call of that tool. A result with nothing to show, such as a search with no matches or an error, collapses the card to zero height and asks ChatGPT to close it, so no empty card is left in the conversation.

A code that a policy lists only because its title names the drug is labelled Inferred from policy title, in the card and in the text. Confirm it against the document before relying on it.

The cards follow ChatGPT's light or dark theme, load nothing from the network (their CSP allows no domains), and open links through the host. They are MCP Apps resources (text/html;profile=mcp-app), so other MCP Apps hosts can render them too. Clients without UI support ignore the _meta keys that link tools to cards and get the same markdown text as before; structuredContent.widget carries the card's data.

Claude.ai skills

The same four skills work in claude.ai. They need the Backwork connector to call tools.

1. Add the connector: Settings > Connectors > Add custom connector, name it Backwork, and enter https://backworkhealth.com/mcp. Finish the OAuth sign-in.
2. Build one zip per skill. The zips go to dist/claude-skills/, which git ignores:

   node scripts/build-claude-skills.mjs

Each zip holds the skill folder at its root, for example coverage-check.zip contains coverage-check/SKILL.md. The build fails if a SKILL.md breaks the claude.ai rules (name matches its folder, description 2