MCP Server

The Verity MCP server lets AI clients query coverage policies, look up codes, validate claims, and check prior authorization requirements in real time.

Current setup

For Claude Code, use the hosted Streamable HTTP MCP endpoint with OAuth. This does not require copying a Verity API key into Claude Code:

claude mcp remove verity 2>/dev/null || true
claude mcp add --transport http --scope user verity https://mcp.verity.backworkai.com/mcp

Then start Claude Code and authenticate the server:

claude

Inside Claude Code, run:

/mcp

Select verity, complete the browser login, approve the Verity consent screen, and return to Claude Code.

Codex currently uses the local stdio server with a Verity API key:

export VERITY_API_KEY=vrt_live_YOUR_API_KEY
codex mcp add verity --env VERITY_API_KEY=$VERITY_API_KEY -- npx -y @backwork/verity-mcp

Use the local stdio setup when your MCP client does not support remote Streamable HTTP yet, or when you want to run the server entirely on your machine.

Codex

Use local stdio with a Verity API key:

export VERITY_API_KEY=vrt_live_YOUR_API_KEY
codex mcp add verity --env VERITY_API_KEY=$VERITY_API_KEY -- npx -y @backwork/verity-mcp

The hosted Verity MCP endpoint requires OAuth. Do not use a Verity API key as a bearer token against https://mcp.verity.backworkai.com/mcp. If you operate a private self-hosted HTTP server in API-key or dual-auth mode, Codex can connect to that private URL with --bearer-token-env-var.

Claude Code

For hosted Streamable HTTP, use OAuth:

claude mcp remove verity 2>/dev/null || true
claude mcp add --transport http --scope user verity https://mcp.verity.backworkai.com/mcp

Then run claude, open /mcp, and authenticate verity. Claude Code discovers the OAuth protected-resource metadata, opens your browser, sends you through Verity login, and stores the OAuth token after you approve the consent screen.

Verify the server is configured:

claude mcp list
claude mcp get verity

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

claude mcp remove verity 2>/dev/null || true
claude mcp add-json verity '{
  "type": "http",
  "url": "https://mcp.verity.backworkai.com/mcp",
  "oauth": {
    "authServerMetadataUrl": "https://verity.backworkai.com/.well-known/oauth-authorization-server",
    "scopes": "verity:mcp read"
  }
}'

authServerMetadataUrl requires Claude Code v2.1.64 or newer. Keep scopes pinned so Claude Code requests only the Verity MCP read scope even if metadata discovery changes.

For older Claude Code clients that cannot complete remote OAuth, use local stdio:

claude mcp add verity -e VERITY_API_KEY=vrt_live_YOUR_API_KEY -- npx -y @backwork/verity-mcp

Cursor, VS Code, Windsurf, and other clients

For clients that only support stdio:

{
  "mcpServers": {
    "verity": {
      "command": "npx",
      "args": ["-y", "@backwork/verity-mcp"],
      "env": {
        "VERITY_API_KEY": "vrt_live_YOUR_API_KEY"
      }
    }
  }
}

The hosted Verity MCP endpoint requires OAuth. For clients that only support static remote URLs and bearer headers, run a private self-hosted MCP server in API-key or dual-auth mode, then set the bearer header using the client's documented secret or environment mechanism. If the client only accepts static JSON, replace the placeholder directly:

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

Self-hosting

Run the MCP server over Streamable HTTP:

git clone https://github.com/backworkai/verity_mcp.git
cd verity_mcp
npm install
npm run build
npm run start:http

Defaults:

HTTP mode requires Authorization: Bearer <Verity API key> by default. For a private single-tenant deployment that supplies the API key from the server environment, set:

VERITY_MCP_ALLOW_ENV_KEY=true VERITY_API_KEY=vrt_live_YOUR_API_KEY npm run start:http

Only use VERITY_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 VERITY_MCP_ALLOWED_HOSTS/VERITY_MCP_PUBLIC_HOST, and set VERITY_MCP_ALLOWED_ORIGINS only to exact browser origins that may connect.

OAuth deployment configuration

For the hosted Verity OAuth flow, the web app must issue tokens for the MCP resource:

VERITY_OAUTH_ISSUER=https://verity.backworkai.com
VERITY_OAUTH_SIGNING_SECRET=<generate with: openssl rand -base64 48>
VERITY_MCP_RESOURCE=https://mcp.verity.backworkai.com/mcp

Production OAuth discovery fails closed unless VERITY_OAUTH_SIGNING_SECRET is at least 32 characters and one of these durable state stores is configured for one-time consent and authorization-code storage:

# Upstash Redis
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...

# or Vercel KV
KV_REST_API_URL=...
KV_REST_API_TOKEN=...

The MCP server must advertise Verity as its authorization server and validate Verity access tokens:

VERITY_MCP_AUTH_MODE=oauth
VERITY_MCP_PUBLIC_HOST=mcp.verity.backworkai.com
VERITY_MCP_PUBLIC_URL=https://mcp.verity.backworkai.com
VERITY_MCP_ALLOWED_HOSTS=mcp.verity.backworkai.com,verity-mcp.vercel.app
VERITY_MCP_OAUTH_AUTHORIZATION_SERVERS=https://verity.backworkai.com
VERITY_MCP_OAUTH_RESOURCE=https://mcp.verity.backworkai.com/mcp
VERITY_MCP_OAUTH_SCOPES="verity:mcp read"
VERITY_MCP_OAUTH_REQUIRED_SCOPES=verity:mcp
VERITY_MCP_OAUTH_INTROSPECTION_URL=https://verity.backworkai.com/api/oauth/introspect
VERITY_MCP_OAUTH_EXPECTED_AUDIENCE=https://mcp.verity.backworkai.com/mcp

Hosted endpoint

The hosted MCP server exposes:

Hosted MCP requests authenticate with Verity OAuth access tokens for Claude Code and other OAuth-capable clients. The hosted endpoint does not accept Verity API keys as bearer tokens; use local stdio or a private self-hosted HTTP deployment for API-key auth.

Usage, billing, and attribution

MCP usage counts as Verity API usage. Each MCP tool call can make one or more downstream Verity API requests, and those requests consume the same plan usage, monthly API call budget, and rate-limit budget as direct API calls.

Attribution depends on how the MCP client authenticates:

In the Verity dashboard, MCP traffic appears with source mcp. Organization admins can review usage by credential, member, source, and MCP tool. Non-admin members see aggregate organization usage without member or OAuth-principal details.

The official MCP server annotates downstream requests automatically. Self-hosted deployments should use the official server build or preserve its Verity request headers so usage can be attributed to the correct MCP tool.

Available tools

Tool names use the verity_ prefix for discoverability when this server is installed alongside other MCP servers. The default tool surface is workflow-level rather than a 1:1 wrapper around every API endpoint, so common agent tasks need fewer tool calls.

All tools return readable text plus structuredContent with a message field and, when available, Verity API data and meta. Every tool accepts optional response_format: "markdown" or response_format: "json".

Example prompts

Is ultrasound guidance (76942) covered in Texas, and does it need prior auth?

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

Compare coverage for J0585 (Botox) across JM and JH jurisdictions.

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

Environment variables

Troubleshooting Claude Code OAuth

If Claude Code does not open the browser, run /mcp, select verity, 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.

If Claude Code keeps using an old token, open /mcp, select verity, clear authentication, then authenticate again. You can also remove and re-add the server with:

claude mcp remove verity
claude mcp add --transport http --scope user verity https://mcp.verity.backworkai.com/mcp

If discovery returns 503, the Verity 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 VERITY_MCP_RESOURCE, VERITY_MCP_OAUTH_RESOURCE, and VERITY_MCP_OAUTH_EXPECTED_AUDIENCE all use:

https://mcp.verity.backworkai.com/mcp

When to use MCP vs Agent Tools API

Use the MCP server when:

• A developer or analyst is chatting with an AI assistant and needs ad-hoc coverage lookups
• You want Verity access inside Claude, Codex, Cursor, VS Code, or another MCP-compatible client
• The use case is exploratory — research, policy review, or answering one-off questions

Use the Agent Tools API when:

• You're building a production application with an embedded agent
• You need audit logging of every tool invocation
• PHI must be explicitly rejected at the API layer
• Your workflow requires human review checkpoints and approval flows
• You need per-tool scope controls beyond a single API key

Last updated on