backwork-mcp

# Backwork MCP Server

[![npm](https://img.shields.io/npm/v/@backwork/mcp)](https://www.npmjs.com/package/@backwork/mcp)

Official Model Context Protocol (MCP) server for the [Backwork API](https://backworkhealth.com). 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

```bash
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:

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

Local stdio:

```bash
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:

```json
{
  "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:

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

Local stdio:

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

## VS Code

```bash
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:

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

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

```json
{
  "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

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

## Use in 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](https://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](https://chatgpt.com/plugins) and select **Refresh** so ChatGPT picks up new tool and component metadata.

| Tool | Card | What it shows |
| --- | --- | --- |
| `backwork_coverage_lookup` | Coverage result | Each policy that lists the codes: payer (`CMS` for Medicare policies), title and number, effective date, a row per code with its disposition badge and source label, and an **Open policy** link to the policy's Backwork page (Medicare LCDs, Articles, and NCDs) or, for other policies, its source document |
| `backwork_prior_auth_research` | Prior-auth checklist | The determination and confidence, codes that require prior auth, documentation to gather, known gaps, and numbered citations. A started research task shows as pending until you ask again |
| `backwork_policy_research` (`action: "compare"`) | Policy comparison | The codes side by side across Medicare contractors (MACs), one column per jurisdiction, with each cell's disposition and policy, and a coverage count per column |

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](https://modelcontextprotocol.io/docs/extensions/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.

## 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](#self-hosting)) and send the key as a bearer header:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.