Verity MCP Server

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

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, run /mcp, select verity, complete the browser login, and approve the Verity consent screen.

Codex currently uses the same hosted endpoint with a Verity API key:

export VERITY_API_KEY=vrt_live_YOUR_API_KEY
codex mcp add verity --url https://mcp.verity.backworkai.com/mcp --bearer-token-env-var VERITY_API_KEY

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

Codex supports Streamable HTTP MCP servers and can source the bearer token from an environment variable:

export VERITY_API_KEY=vrt_live_YOUR_API_KEY
codex mcp add verity --url https://mcp.verity.backworkai.com/mcp --bearer-token-env-var VERITY_API_KEY

For local stdio:

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

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": {
    "scopes": "verity:mcp read"
  }
}'

For older clients or API-key fallback:

export VERITY_API_KEY=vrt_live_YOUR_API_KEY
claude mcp add --transport http verity https://mcp.verity.backworkai.com/mcp --header "Authorization: Bearer $VERITY_API_KEY"

Claude stores HTTP headers in its MCP config. Use a scoped Verity key and rotate it if you later remove this server.

For 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 MCP Clients

For clients that only support stdio commands:

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

For clients that support remote URLs and headers, 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://mcp.verity.backworkai.com/mcp",
      "headers": {
        "Authorization": "Bearer vrt_live_YOUR_API_KEY"
      }
    }
  }
}

Self-Hosting

Run a Streamable HTTP server:

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 per request. By default this bearer is a Verity API key for backward compatibility. For hosted remote MCP deployments, enable OAuth protected-resource discovery so Claude-compatible clients can authenticate users through your authorization server:

VERITY_MCP_AUTH_MODE=oauth \
VERITY_MCP_OAUTH_AUTHORIZATION_SERVERS=https://verity.backworkai.com \
VERITY_MCP_OAUTH_SCOPES="verity: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 Verity 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 Verity API key in token introspection, set VERITY_MCP_OAUTH_INTROSPECTION_URL and VERITY_MCP_OAUTH_API_KEY_CLAIM to validate the access token and map it to the downstream Verity credential.

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

Vercel Hosting

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

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

The Vercel functions expose:

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

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 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
VERITY_API_KEY=vrt_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 verity_ 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 Verity 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.

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 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 Verity source data is updated.

Release

The package publishes to npm as @backwork/verity-mcp.

The npm package is available under the Backwork scope as @backwork/verity-mcp.

1. Configure npm Trusted Publishing for backworkai/verity_mcp, workflow release.yml, environment npm, package @backwork/verity-mcp.

2. Update package.json and package-lock.json to the new version.

3. Push a matching tag, for example v1.1.1.

4. The release workflow installs with npm ci, runs the build/smoke test, verifies npm pack --dry-run, and publishes with npm provenance.

Environment Variables

Troubleshooting

Missing API Key

For stdio, set VERITY_API_KEY in the MCP client configuration. For HTTP API-key mode, send Authorization: Bearer <key>. For HTTP OAuth mode, configure VERITY_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 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

Rate Limits

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

Support

• Documentation: https://verity.backworkai.com/docs

• Issues: https://github.com/backworkai/verity_mcp/issues

• Email: support@verity.backworkai.com

License

MIT