# MCP Server
URL: https://backworkhealth.com/docs/mcp

Connect Claude, Cursor, VS Code, Codex, or any MCP client to Backwork through the hosted MCP server. Nothing to install.

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:

```text
https://backworkhealth.com/mcp
```

<Callout type="info">
  **MCP or Agent Tools API?** The MCP server is for people working in an AI client. The [Agent Tools API](/docs/agent-tools) is for agents built into your own application, with audit logging, PHI rejection, per-tool scopes, and human review routing.
</Callout>

## Before you start [#before-you-start]

You need a Backwork account in an organization. [Sign up free](https://backworkhealth.com/sign-up); 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](#usage-and-credits).

## Add the hosted server [#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.

<Tabs items="[&#x22;Claude Code&#x22;, &#x22;Claude Desktop&#x22;, &#x22;Cursor&#x22;, &#x22;VS Code&#x22;, &#x22;Codex&#x22;]">
  <Tab value="Claude Code">
    ```bash
    claude mcp add --transport http backwork https://backworkhealth.com/mcp
    ```

    Start `claude`, run `/mcp`, select `backwork`, and choose **Authenticate**. Add `--scope user` to make the server available in every project.

    Check it with `claude mcp get backwork`.
  </Tab>

  <Tab value="Claude Desktop">
    Open **Settings → Connectors**, choose **Add custom connector**, and enter:

    * **Name:** `Backwork`
    * **Remote MCP server URL:** `https://backworkhealth.com/mcp`

    Then choose **Connect** and sign in. The same connector works in Claude on the web.
  </Tab>

  <Tab value="Cursor">
    Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

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

    Open **Cursor Settings → MCP** and choose **Connect** next to `backwork` to sign in.
  </Tab>

  <Tab value="VS Code">
    Add the server to `.vscode/mcp.json` in your workspace, or run **MCP: Add Server** from the Command Palette:

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

    VS Code opens the browser sign-in the first time the server starts.
  </Tab>

  <Tab value="Codex">
    ```bash
    codex mcp add backwork --url https://backworkhealth.com/mcp
    codex mcp login backwork
    ```

    `codex mcp login` opens the browser. Add `--no-browser` to get a URL to paste instead.
  </Tab>
</Tabs>

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 [#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](/docs/authentication#api-key-scopes).

The hosted server does not accept API keys as bearer tokens. For API-key auth, use the [local server](#local-npm) or a [self-hosted](#self-hosting) one.

### Token lifetimes and refresh [#token-lifetimes-and-refresh]

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

| Token         | Lifetime                                            |
| ------------- | --------------------------------------------------- |
| Access token  | 1 hour                                              |
| Refresh token | 7 days unused, and 30 days at most from the consent |

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

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

```bash
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 [#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](/docs/pricing) and counts against its [per-minute limit](/docs/rate-limits), 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](https://backworkhealth.com/api-usage).

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

| Auth                                  | Attributed to                                              |
| ------------------------------------- | ---------------------------------------------------------- |
| Hosted server (OAuth)                 | The signed-in user, the OAuth client, and the organization |
| Local or self-hosted server (API key) | The API key, its owner, and the organization               |

## Available tools [#available-tools]

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

| Tool                               | What it does                                                                                                                                |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `backwork_coverage_lookup`         | Looks up procedure codes and combines code details, policy evidence, prior authorization, claim risk, jurisdiction comparison, and spending |
| `backwork_policy_research`         | Searches policies, fetches one policy, searches extracted criteria, reviews policy changes, or maps MAC jurisdictions                       |
| `backwork_claim_validation`        | Checks claim coverage, documentation requirements, denial risk, and policy-specific criteria                                                |
| `backwork_prior_auth_research`     | Checks Medicare prior authorization, starts payer website research, or polls a research task                                                |
| `backwork_drug_formulary_research` | Searches pharmacy-benefit evidence from CVS Caremark, Express Scripts, and UnitedHealthcare / Optum Rx                                      |
| `backwork_compliance_review`       | Shows compliance stats, lists unreviewed policy changes, or acknowledges changes                                                            |
| `backwork_webhook_management`      | Lists, creates, updates, deletes, or tests webhook endpoints                                                                                |
| `backwork_system_health`           | Checks API health                                                                                                                           |

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](/docs/code-sources).

## Example prompts [#example-prompts]

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

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

```text
Compare coverage for J0585 across the JM and JH jurisdictions.
```

## Local (npm) [#local-npm]

The local server ([`@backwork/mcp`](https://www.npmjs.com/package/@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](https://backworkhealth.com/api-usage):

```json
{
  "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 [#self-hosting]

You can also build the server from [its repository](https://github.com/tylergibbs1/backwork-mcp). It needs Node.js 18 or later.

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

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

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

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

```bash
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 [#environment-variables]

| Variable                       | Required  | Description                                                                               |
| ------------------------------ | --------- | ----------------------------------------------------------------------------------------- |
| `BACKWORK_API_KEY`             | For stdio | Backwork API key. In HTTP mode, prefer the `Authorization` header.                        |
| `BACKWORK_API_BASE`            | No        | API base URL. Defaults to `https://backworkhealth.com/api/v1`.                            |
| `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_ALLOWED_HOSTS`   | No        | Comma-separated allowed HTTP `Host` headers for public deployments.                       |
| `BACKWORK_MCP_PUBLIC_HOST`     | No        | Primary public host allowed for HTTP requests.                                            |
| `BACKWORK_MCP_ALLOW_ENV_KEY`   | No        | Let private HTTP requests without a bearer token use `BACKWORK_API_KEY`.                  |
| `BACKWORK_MCP_AUTH_MODE`       | No        | HTTP bearer mode: `api-key`, `oauth`, or `dual`.                                          |

## Hosted endpoints [#hosted-endpoints]

| URL                                                                 | Purpose                             |
| ------------------------------------------------------------------- | ----------------------------------- |
| `https://backworkhealth.com/mcp`                                    | Streamable HTTP MCP endpoint        |
| `https://backworkhealth.com/mcp/health`                             | Server health check                 |
| `https://backworkhealth.com/.well-known/oauth-protected-resource`   | OAuth protected-resource metadata   |
| `https://backworkhealth.com/.well-known/oauth-authorization-server` | OAuth authorization-server metadata |

## Troubleshooting [#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](#what-the-sign-in-grants).
* **A tool fails with `402`.** Your organization is out of request credits. Buy more in [API usage and keys](https://backworkhealth.com/api-usage).

## When to use MCP or the Agent Tools API [#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 &#x2A;*[Agent Tools API](/docs/agent-tools)** 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.