Backwork

Backwork MCP 服务

适用于 Backwork API 的官方 Model Context Protocol（MCP）服务。它可让 AI 助手受控地访问 Medicare 和付款方医疗政策、医疗编码智能、事先授权检查、理赔验证、合规审查、药品目录证据和 Webhook 操作。

有两种连接方式：

	托管远程服务	本地 stdio
端点	https://backworkhealth.com/mcp（Streamable HTTP）	npx -y @backwork/mcp
身份验证	在浏览器中使用 OAuth，无需复制密钥	BACKWORK_API_KEY=bwk_live_...
适用场景	客户端支持带 OAuth 的远程 MCP	客户端只运行本地命令，或你希望在自己的机器上运行服务

托管端点仅接受 OAuth。请勿将 Backwork API 密钥作为 bearer token 发送到 https://backworkhealth.com/mcp。OAuth 授权范围为只读（backwork:mcp read），因此托管服务仅提供读取操作：不支持 Webhook 管理和合规确认。若要使用这些功能，请使用带有写入权限实时密钥的本地 stdio。

调用会消耗你所在组织的请求额度，与其他 /api/v1 调用相同。bwk_test_ 密钥仅适用于沙盒（https://backworkhealth.com/api/sandbox/v1），支持政策搜索、编码查询、事先授权检查和承保评估；要使用该密钥，请将 BACKWORK_API_BASE 设置为该 URL。

Claude Code

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

添加 --scope user，即可在每个项目中使用。然后运行 claude，打开 /mcp，选择 backwork，并完成浏览器登录和 Backwork 同意页面。运行 claude mcp get backwork 进行检查。

如果需要显式指定 OAuth 发现信息，请以 JSON 形式添加相同的服务：

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

本地 stdio：

claude mcp add backwork -e BACKWORK_API_KEY=bwk_live_YOUR_API_KEY -- npx -y @backwork/mcp

Claude Desktop

托管远程服务：打开 Settings > Connectors > Add custom connector，将其命名为 Backwork，然后输入 https://backworkhealth.com/mcp。连接时，Claude Desktop 会启动 OAuth 登录。

本地 stdio：将以下内容添加到 claude_desktop_config.json（Settings > Developer > Edit Config），然后重启 Claude Desktop：

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

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）。首次连接时，Cursor 会打开 OAuth 登录：

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

本地 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"}'

或者将其添加到工作区中的 .vscode/mcp.json。服务启动时，VS Code 会提示你登录：

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

本地 stdio：密钥只需提示输入一次，并由 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 会在开发者模式下将托管服务作为自定义 MCP 连接接入。三个工具会返回一个小卡片，ChatGPT 会将其内嵌显示在回答上方。

1. 在 ChatGPT 中，打开 设置 → 安全和登录，然后开启 开发者模式。你的套餐或工作区管理员可能需要允许此功能。
2. 前往 chatgpt.com/plugins，然后选择 + 按钮。
3. 将其命名为 Backwork，添加简短说明，并在 连接 下输入 https://backworkhealth.com/mcp。选择 OAuth 进行身份验证。
4. 选择 创建。ChatGPT 会打开 Backwork 的登录页面；批准只读的 backwork:mcp read 授权。
5. 检查已发现的工具，然后开始新聊天，从工具菜单中添加 Backwork，并提出类似 “CPT 76942 在德克萨斯州是否有承保？是否需要事先授权？” 的问题。

服务更新后，前往 chatgpt.com/plugins 打开该连接，并选择 刷新，让 ChatGPT 获取新的工具和组件元数据。

工具	卡片	显示内容
backwork_coverage_lookup	承保结果	每项列出这些代码的政策：付款方（Medicare 政策显示为 CMS）、标题和编号、生效日期；每个代码对应一行，其中包含其处置状态徽章和来源标签；以及一个 打开政策 链接，指向 Backwork 上的政策页面（Medicare LCD、Article 和 NCD），或在其他政策中指向其源文档
backwork_prior_auth_research	事先授权清单	判定结果和置信度、需要事先授权的代码、需收集的文档、已知缺漏以及编号引文。已启动的研究任务会显示为待处理，直到你再次提问
backwork_policy_research	政策研究	按操作分类：compare 会按列并排显示各 Medicare 承包商（MAC）的代码，每列对应一个管辖区，每个单元格显示处置状态和政策，并在每列中显示承保数量；search 会列出匹配的政策及其付款方、编号、生效日期、简短摘要和链接；get 会显示单项政策的摘要、各部分的标准摘录及其代码；criteria 会列出匹配的标准摘录及其对应政策；changes 会列出近期变更；jurisdictions 会列出各 MAC 及其所属州

每次调用工具时，ChatGPT 都会加载该工具的卡片。没有可显示内容的结果（例如搜索没有匹配项或发生错误）会将卡片折叠至零高度，并提示 ChatGPT 关闭卡片，因此对话中不会留下空卡片。

如果某项政策仅因标题中提到了某种药物而列出某个代码，卡片和文本中都会将其标注为 根据政策标题推断。在依赖此信息之前，请先对照文档确认。

这些卡片会遵循 ChatGPT 的浅色或深色主题，不会从网络加载任何内容（其 CSP 不允许任何域名），并通过宿主打开链接。它们是 MCP Apps 资源（text/html;profile=mcp-app），因此其他 MCP Apps 宿主也能渲染它们。不支持 UI 的客户端会忽略将工具与卡片关联的 _meta 键，并获取与之前相同的 Markdown 文本；卡片数据包含在 structuredContent.widget 中。

其他 MCP 客户端

可以运行本地命令的客户端可使用 Claude Desktop 的 stdio 配置。支持使用 OAuth 连接远程 URL 的客户端可直接使用 https://backworkhealth.com/mcp。

对于仅支持带静态标头的远程 URL 的客户端，请以 API 密钥或双重身份验证模式部署专用的可自托管服务（参见自托管），并将密钥作为 bearer 标头发送：

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

自托管

运行 Streamable HTTP 服务：

git clone https://github.com/tylergibbs1/backwork-mcp.git
cd backwork-mcp
npm install
npm run build
npm run start:http

默认值：

设置	默认值	覆盖方式
传输方式	stdio	--http 或 BACKWORK_MCP_TRANSPORT=http
主机	127.0.0.1	--host 或 BACKWORK_MCP_HOST
端口	3000	--port 或 BACKWORK_MCP_PORT 或 PORT
MCP 路径	/mcp	--path 或 BACKWORK_MCP_PATH
允许的主机	loopback/专用主机、VERCEL_URL 或已配置的公共主机	BACKWORK_MCP_ALLOWED_HOSTS 或 BACKWORK_MCP_PUBLIC_HOST

HTTP 模式要求每个请求都携带 Authorization: Bearer。默认情况下，此 bearer 是 Backwork API 密钥。对于托管的远程 MCP 部署，请启用 OAuth 受保护资源发现，以便兼容 Claude 的客户端通过您的授权服务器进行用户身份验证：

BACKWORK_MCP_AUTH_MODE=oauth \
BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS=https://backworkhealth.com \
BACKWORK_MCP_OAUTH_SCOPES="backwork:mcp read" \
npm run start:http

服务会在 /.well-known/oauth-protected-resource 发布 OAuth 受保护资源元数据，并在 WWW-Authenticate 挑战中包含该 URL。如果您的 Backwork API 可直接接受 OAuth 访问令牌，则无需进行额外映射；MCP 服务会将 OAuth bearer 传递到下游。如果您的授权服务器在令牌内省中提供 Backwork API 密钥，请设置 BACKWORK_MCP_OAUTH_INTROSPECTION_URL 和 BACKWORK_MCP_OAUTH_API_KEY_CLAIM，以验证访问令牌并将其映射为下游 Backwork 凭据。

对于由服务环境提供密钥的私有单租户部署，请设置：

BACKWORK_MCP_ALLOW_ENV_KEY=true BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm run start:http

仅在受网络访问控制保护的 loopback 或专用网络部署中使用 BACKWORK_MCP_ALLOW_ENV_KEY=true。公共部署应要求每个请求都携带 bearer 令牌，设置 BACKWORK_MCP_ALLOWED_HOSTS/BACKWORK_MCP_PUBLIC_HOST，并且仅将 BACKWORK_MCP_ALLOWED_ORIGINS 设置为允许连接的确切浏览器来源。

Vercel 托管

此仓库可以部署为仅提供 API 的 Vercel 项目。生产项目使用：

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.com/api/oauth/introspect
BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE=https://backworkhealth.com/mcp

Vercel 函数公开以下路径：

路径	用途
/mcp	Streamable HTTP MCP 端点
/health	MCP 服务轻量级运行状况检查
/.well-known/oauth-protected-resource	配置 OAuth 时使用的 OAuth 受保护资源元数据
/	基本端点元数据

颁发 OAuth 令牌的 Backwork Web 应用也必须进行配置：

BACKWORK_OAUTH_ISSUER=https://backworkhealth.com
BACKWORK_OAUTH_SIGNING_SECRET=<generate with: openssl rand -base64 48>
BACKWORK_MCP_RESOURCE=https://backworkhealth.com/mcp

除非 BACKWORK_OAUTH_SIGNING_SECRET 至少有 32 个字符，且已配置 Redis 或 Vercel KV 用于存储一次性授权同意和授权码，否则生产环境中的 OAuth 发现会以失败关闭。

运行状况检查：

curl http://localhost:3000/health

本地开发

npm install
npm run build
BACKWORK_API_KEY=bwk_live_YOUR_API_KEY npm start

常用命令：

npm run start:http
node build/src/index.js --help

需要 Node.js 18.14.1 或更高版本。

可用工具

工具名称使用 backwork_ 前缀，便于此服务与其他 MCP 服务一起安装时进行发现。默认提供的工具界面有意采用工作流级别，而非一对一的 API 封装，因此 Agent 看到的选项更少，常见任务所需的工具调用也更少。

所有工具都包含 title、description、inputSchema、outputSchema 和 MCP 注释。每个工具都会声明自己的注释；如果标记为只读的工具提供了写入范围操作，或标记为非破坏性的工具提供了 DELETE，服务将拒绝启动。成功调用会返回易读文本，以及包含 message 的 structuredContent；如果可用，还会包含 Backwork API 的 data 和 meta。

data 和 meta 是投影数据：它们仅携带 src/api-operations.ts 为相应操作列出的响应字段（reads 和 metaReads）。请求 ID、响应时间戳、记录时间戳、研究任务的费用和轮询 URL、幂等键及模型名称都会被剔除。政策生效日期和最近审核日期、来源抓取时间以及来源审计抽样时间会保留。API 调用失败时，服务会记录请求 ID。

工具级失败会返回 isError: true。计费和速率限制失败会以直白的方式说明，绝不会重复 API 提示、套餐名称或定价链接：组织套餐不包含该功能、请求额度已用完，或受到速率限制并说明何时可以重试。test/output-guard.test.mjs 会针对固定响应和这些错误运行每项工具操作，并在出现追加销售措辞、跟踪 ID、时间戳、费用或模型字段时失败。

来源与时效性

当 Backwork API 响应引用政策文档时，structuredContent.provenance 会提供 Agent 引用这些文档所需的信息，文本输出末尾会附上一段简短的 --- Sources ---：

字段	含义
source_urls	不重复的源文档 URL
authorities	发布机构，例如 CMS 或付款方名称
retrieved_at	所有引用来源都有已知获取时间时，取最早的获取时间；否则为 null
as_of	引用来源中的最晚生效日期
sources[]	每个来源对应的 policy_id、source_url、authority、retrieved_at、as_of

这些值来自 API 响应。source_check.source_url 和 source_check.last_fetched_at 优先于旧版来源元数据。明确标记为未知的获取时间仍为 null；只有在不存在来源检查块时，才会将旧版 retrieved_at、last_verified_at 或 crawled_at 作为备用值。如果其他引用来源的获取时间未知，已知的获取时间仍会保留在 sources[] 中。此结构与 Backwork Agent 工具结果中的 provenance 块一致。

政策证据还会保留 API 的 source_check：来源 URL、上次获取时间、获取内容的 SHA-256，以及 source_accuracy 审计样本。每项审计都会报告测量的字段、样本日期和样本量、样本记录中匹配记录所占比例、95% Wilson 区间以及方法。**这些样本衡量的是某个来源中的记录，而不是对单项政策或覆盖决定的确定性。**缺失的审计仍为 null。卡片会显示获取日期和可展开的来源样本审计信息。

对于明确注明适用范围的政策，还会保留可选字段 applicability_scope、applicability_markets、applicability_evidence 和 applicability_note。适用于多个市场的文档和已编入索引的单一市场文档都会列在发布方的州级索引中；此类发现证据并不能确定成员的计划或产品是否包含相应保障。没有州、业务线或已编入索引的市场信息的 document_scoped 政策，适用性未知。卡片和文本会显示 API 的备注，卡片还会提供发布方索引链接和带页码的来源原文引述。缺少这些字段的旧版响应会保持原有结构。

适用性证据仅限于文档 SHA-256、最多 16 条 HTTPS 发布方索引条目，以及最多 16 条属于三种受支持类型（non_medicare_disclaimer、commercial_policy_header、member_type_branch）的陈述。引述长度上限为 4,000 个字符，索引 URL 长度上限为 2,048 个字符，页码必须为正整数。未知字段会被丢弃；格式错误的证据会变为 null。市场代码和备注也有长度限制。MCP 会保留 API 的置信度和人工审核输出；索引条目不会提高置信度，也不会解决授权问题。

代码匹配结果会将 grounding 与提取时使用的 source 分开保留：

grounding	含义
grounded	在 Backwork 保留的来源文本中找到
not_grounded	文档处理流水线读取过，但未在保留的来源文本中找到
no_source_text	没有可供检查的保留文本
not_checked	未检查来源依据，包括根据政策标题推断的代码

文本和卡片会标注这些检查结果，但不会将有来源依据的代码视为覆盖保障。省略 grounding 的旧版响应仍视为未知；无法识别的未来取值会予以保留并标注。

生产环境可用性

服务提供哪些操作取决于以下两点：

• 可用性。 Backwork OpenAPI 文档可以将某个操作标记为 x-backwork-availability: unavailable-in-production。对于生产 API（https://backworkhealth.com），服务会屏蔽这些操作。目前没有操作带有此标记：生产环境会向组织的有效密钥提供这些工具调用的所有 /api/v1 操作。
• 访问权限。 需要 write 范围（x-backwork-required-scopes）的操作不会提供给只读 OAuth 授权。在托管服务上，这会隐藏 backwork_webhook_management，以及 backwork_compliance_review 的 acknowledge 和 bulk_acknowledge 操作。只读连接也不会获得 backwork_system_health 诊断信息、backwork_claim_validation 上的 idempotency_key 输入，或带有确认输入（diff_id、diff_ids、notes）的 backwork_compliance_review，其结果中也不会包含差异 ID。Backwork API 密钥（stdio，或使用 bwk_ bearer 的 HTTP）可使用所有工具和操作，API 会强制执行该密钥自身的范围。除非 OAuth 授权的范围包含 write，否则该授权按只读处理。

没有可用操作的工具会被隐藏。部分操作可用的工具会从其 action 输入中移除被屏蔽的操作；描述中也会列出在生产环境中不可用的操作。指向其他 Backwork 部署的服务（通过 BACKWORK_API_BASE 指定）会忽略可用性标记；在生产环境中设置 BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS=true 也会忽略这些标记。这两种方式都不会取消写入范围规则。

主要工具	用途
backwork_coverage_lookup	查询医疗程序代码，并汇总代码详情、保单证据、事先授权、理赔风险、司法管辖区比较和支出证据。使用 payer 时，代码详情仅列出该付款方的保单，并说明省略了多少其他付款方的保单
backwork_policy_research	搜索保单、获取单份保单、搜索提取的标准、审查保单变更、映射 MAC 司法管辖区，或比较不同 MAC 对相同代码的覆盖情况
backwork_claim_validation	验证理赔覆盖范围、文档要求、拒赔风险和可选的保单专属标准
backwork_prior_auth_research	根据 Backwork 的保单（Medicare 或指定付款方的保单）检查事先授权，或启动并轮询一个搜索付款方公开网站的后台任务
backwork_drug_formulary_research	搜索来自 CVS Caremark、Express Scripts 和 UnitedHealthcare / Optum Rx 的商业药房福利证据
backwork_compliance_review	查看合规统计信息并列出尚未审阅的保单变更；使用 API 密钥时，还可确认变更
backwork_webhook_management	列出、创建、更新、删除或测试 webhook 端点。Backwork 会发送一种事件 compliance.acknowledged；不会发送保单变更 webhook。需要具有写入范围的 API 密钥
backwork_system_health	检查 Backwork API 的运行状况和依赖项状态。仅限 API 密钥连接

响应格式

每个工具都接受：

{
  "response_format": "markdown"
}

使用 "markdown" 获取易读输出，或使用 "json" 使文本内容与返回的 structuredContent 保持一致。

示例提示词

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.

测试与评估

运行构建和 MCP 元数据冒烟测试：

npm test

冒烟测试会使用虚拟密钥启动构建后的 stdio 服务，验证 8 个工作流工具，检查标题、架构、注释、输出架构和 response_format，并验证本地校验失败时会以 isError: true 报告。HTTP 冒烟测试还会完成经过身份验证的 MCP 初始化，列出具有读取授权的工具，并使用无效参数调用一个工具。test/ 套件涵盖生产环境可用性、托管服务仅支持 OAuth 的只读工具集、来源信息、描述质量和词法工具选择检查（不调用模型）、注册表清单，以及 ChatGPT 卡片：工具列表中的模板、资源和 MIME 类型、每张卡片的 structuredContent 与其架构的匹配情况、面向不支持 UI 的客户端的 Markdown，以及在模拟浏览器中渲染每张卡片页面时，对每个带卡片工具的每个操作进行测试；页面必须显示卡片，或收缩至零高度。

发布前，运行 npm run verify:package。它会将打包后的 tarball 安装到临时使用方环境中，不使用仓库覆盖配置或锁文件，然后在当前运行时和 Node 18.20.8 上运行两种传输方式。CI 会运行相同的检查。可在 -- 后传入其他确切的 Node 版本。

API 合约

此服务调用的每个 Backwork 端点都列在 src/api-operations.ts 中，其中包含发送的请求字段和读取的响应字段。工具只能通过该目录调用 API。每个条目还会同步该操作的可用性标记和必需的作用域。npm test 会将该目录与 vendored 的 openapi/backwork-openapi.json 进行检查，并询问服务自身的暴露规则：对于生产环境、只读 OAuth 授权和 API 密钥，它会提供哪些工具操作。如果某个操作对应的工具操作被提供，但生产环境不提供该操作、将其标记为不可用，或（对于 OAuth 授权）要求 write 作用域，则检查会失败。

CI 会运行 npm run contract:live，针对 https://backworkhealth.com/openapi.json 运行相同的检查；如果 vendored 副本与其存在任何差异（描述、摘要和示例除外），检查就会失败。

Backwork API 变更时，请刷新 vendored 副本并检查差异：

npm run openapi:update
npm run contract:check

evals/ 目录包含一项工具可发现性评估，以及一项只读数据评估，二者基于固定的、有源数据依据的策略/代码记录构建。Backwork 源数据更新时，请有意刷新只读答案。

SDK 迁移后续工作

2.1.4 版本将 v1 SDK 1.32.1、Zod 及其生产依赖打包在已提交的锁文件中。这会将已修补的 Hono Node 适配器 1.19.15 一并带入使用方安装，并保留对 Node 18 的支持（最低版本为 18.14.1）。npm 只会采用使用方根目录 package.json 中的覆盖配置，因此本包中的覆盖配置无法提供此保证。使用 npm ci 重现发布依赖树，并在更新锁文件后重新运行包验证。官方 v2 迁移指南要求进行单独的兼容性变更：

1. 将支持的 Node.js 运行时从 18 提升至至少 20，包括托管部署和发布工作流。
2. 将单体 SDK 导入替换为 @modelcontextprotocol/server、用于 Node HTTP 传输的 @modelcontextprotocol/node，以及用于客户端和测试的 @modelcontextprotocol/client；必要时使用 @modelcontextprotocol/core 中的公开协议架构。
3. 将声明的 Zod 版本范围升级至至少 4.2，并将工具输入/输出架构封装为 Standard Schema 对象，同时保留字段描述和结构化输出校验。
4. 在发布该迁移前，验证工具发现、stdio、无状态 HTTP 生命周期、OAuth 发现和作用域、小组件、输出最小化，以及实时 OpenAPI 合约。

MCP Registry

server.json 将此服务描述为 官方 MCP registry 中的 io.github.tylergibbs1/backwork-mcp：托管的 Streamable HTTP 远程服务（位于 https://backworkhealth.com/mcp，使用 OAuth，从受保护资源元数据中发现）以及通过 stdio 提供的 @backwork/mcp npm 包。package.json 包含匹配的 mcpName，供 registry 用于验证 npm 所有权。npm test 会根据 registry schema 验证 server.json，并检查其中的版本是否与 package.json 一致。

Release

发布流程会通过 Trusted Publishing（GitHub OIDC，无需 npm token）将 @backwork/mcp 发布到 npm，然后将 server.json 发布到 MCP registry。

1. 执行 npm version minor（或 patch/major）。version 脚本会将新版本复制到 server.json 和 src/index.ts 中的 SERVER_VERSION。
2. 将此变更合并到 main。
3. 从 main 推送匹配的标签，例如 git tag v2.1.0 && git push origin v2.1.0。

随后，Release 工作流会：

1. 如果标签不等于 v + package.json 中的版本，则失败。
2. 运行 npm ci、npm test（构建、冒烟测试、单元测试、OpenAPI 合约）、npm run verify:package（干净的使用方环境和 Node 18 传输方式）以及 npm pack --dry-run。
3. 在 npm 环境中将包连同来源证明发布到 npm。如果该版本已发布到 npm，则会跳过，因此失败的运行可以重新执行。
4. 等待该版本出现在 npm 上，然后运行 mcp-publisher login github-oidc 和 mcp-publisher publish。

一次性 npm 设置：在 npmjs.com 上，打开 @backwork/mcp > Settings > Trusted publishing，选择 GitHub Actions，然后填写用户 tylergibbs1、仓库 backwork-mcp、工作流 release.yml 和环境 npm。

环境变量

变量	必填	说明
BACKWORK_API_KEY	Stdio 必填；HTTP 非必填	Backwork API 密钥。在 HTTP 模式下，建议在每个请求中使用 Authorization: Bearer。
BACKWORK_API_BASE	否	覆盖 API 基础 URL。
BACKWORK_MCP_TRANSPORT	否	stdio 或 http。
BACKWORK_MCP_HOST	否	HTTP 绑定主机。默认为 127.0.0.1。
BACKWORK_MCP_PORT	否	HTTP 绑定端口。
BACKWORK_MCP_PATH	否	HTTP MCP 路径。
BACKWORK_MCP_ALLOWED_ORIGINS	否	以逗号分隔的允许使用的 HTTP 来源。对于环回请求，允许环回来源。
BACKWORK_MCP_ALLOW_ORIGIN	否	BACKWORK_MCP_ALLOWED_ORIGINS 的向后兼容别名。
BACKWORK_MCP_ALLOWED_HOSTS	否	面向公网部署时，以逗号分隔的允许使用的 HTTP Host 标头。
BACKWORK_MCP_ALLOW_HOST	否	BACKWORK_MCP_ALLOWED_HOSTS 的向后兼容别名。
BACKWORK_MCP_PUBLIC_HOST	否	允许用于 HTTP 请求的主要公网主机。
BACKWORK_MCP_PUBLIC_URL	否	OAuth 元数据使用的规范公网来源，例如 https://backworkhealth.com。
BACKWORK_MCP_ALLOW_ENV_KEY	否	允许未携带 bearer 身份验证的私有 HTTP 请求使用 BACKWORK_API_KEY。
BACKWORK_MCP_AUTH_MODE	否	HTTP bearer 模式：api-key、oauth 或 dual。配置了 OAuth 授权服务器时默认为 dual，否则默认为 api-key。
BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS	OAuth	以逗号分隔的 OAuth 颁发者／授权服务器 URL，会在受保护资源元数据中公布。
BACKWORK_MCP_OAUTH_RESOURCE	否	覆盖 RFC 8707 资源标识符。默认为公开 MCP URL。
BACKWORK_MCP_OAUTH_SCOPES	否	向客户端公布的以空格或逗号分隔的范围。默认为 backwork:mcp。
BACKWORK_MCP_OAUTH_REQUIRED_SCOPES	否	令牌内省后必须具备的以空格或逗号分隔的范围。
BACKWORK_MCP_OAUTH_INTROSPECTION_URL	否	用于验证 OAuth 访问令牌的 RFC 7662 令牌内省端点。
BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_ID	否	用于内省基本身份验证的客户端 ID。
BACKWORK_MCP_OAUTH_INTROSPECTION_CLIENT_SECRET	否	用于内省基本身份验证的客户端密钥。
BACKWORK_MCP_OAUTH_INTROSPECTION_TOKEN	否	未使用基本身份验证时用于内省的 bearer 令牌。
BACKWORK_MCP_OAUTH_API_KEY_CLAIM	否	内省响应中用作下游 Backwork 凭据的点路径声明。若省略，则转发 OAuth 访问令牌。
BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE	否	内省响应包含受众时，以逗号分隔的允许使用的 aud 值。
BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS	否	true 会提供生产 API 标记为不可用的工具和操作。只读 OAuth 授权仍会隐藏需要写入范围的操作。

故障排除

缺少 API 密钥

对于 stdio，请在 MCP 客户端配置中设置 BACKWORK_API_KEY。对于 HTTP API 密钥模式，请发送 Authorization: Bearer <key>。对于 HTTP OAuth 模式，请配置 BACKWORK_MCP_OAUTH_AUTHORIZATION_SERVERS 并发送 Authorization: Bearer <access_token>。

HTTP MCP 返回 401

远程服务未收到 bearer 令牌。请将 MCP 客户端配置为使用 OAuth 进行身份验证，或发送 Authorization 标头。启用了 OAuth 的部署会在 WWW-Authenticate 标头中包含 resource_metadata，以引导客户端访问 /.well-known/oauth-protected-resource。

Claude Code OAuth

如果 Claude Code 未打开浏览器，请运行 /mcp，选择 backwork，然后选择身份验证操作。如果它提供 URL 而不是打开浏览器，请将该 URL 复制到浏览器中。

如果同意后浏览器重定向回 Claude Code 失败，请从浏览器地址栏复制完整的回调 URL，并将其粘贴到 Claude Code 提示中。

此服务不会保留 OAuth 令牌。它会通过内省验证每个请求的访问令牌，并将其（或映射后的 API 密钥）转发给 Backwork API。刷新已过期访问令牌是 MCP 客户端的职责：当内省报告令牌未激活时，服务会返回 401 和 error="invalid_token"，客户端可使用其刷新令牌向 Backwork 授权服务器刷新令牌。

如果 Claude Code 一直使用旧令牌，请打开 /mcp，选择 backwork，清除身份验证，然后重新进行身份验证。也可以通过以下命令移除并重新添加服务：

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

如果发现服务返回 503，则表示 Backwork Web 应用有意拒绝公布 OAuth，因为生产环境的签名或 Redis/KV 状态存储缺失。

如果工具调用通过身份验证，但失败并显示 invalid_token 或 invalid_target，请检查 BACKWORK_MCP_RESOURCE、BACKWORK_MCP_OAUTH_RESOURCE 和 BACKWORK_MCP_OAUTH_EXPECTED_AUDIENCE 是否都使用：

https://backworkhealth.com/mcp

速率限制

等待重置窗口结束，或使用容量更高的 API 方案。

支持

• 文档：https://backworkhealth.com/docs
• 问题反馈：https://github.com/tylergibbs1/backwork-mcp/issues
• 邮箱：[email protected]

许可证

MIT。请参阅 LICENSE。

Claude Code 插件

backwork 插件将托管的 MCP 服务与四项研究技能打包在一起：事先授权、保障范围核查、政策变更和拒赔申诉准备。请从此仓库的插件市场安装：

/plugin marketplace add tylergibbs1/backwork-mcp
/plugin install backwork@backwork

然后运行 /mcp，选择 plugin:backwork:backwork，并完成 OAuth 登录。新账户可获得 100 个免费积分。有关这些技能以及 /backwork:pa 和 /backwork:coverage 命令，请参阅 plugins/backwork/README.md。

市场清单位于 .claude-plugin/marketplace.json。npm test 会检查清单和所有 SKILL.md。CI 还会对市场和插件运行 claude plugin validate --strict。

Claude.ai 技能

同样的四项技能也可在 claude.ai 中使用。它们需要 Backwork 连接器才能调用工具。

1. 添加连接器：依次选择 Settings > Connectors > Add custom connector，将其命名为 Backwork，并输入 https://backworkhealth.com/mcp。完成 OAuth 登录。

2. 为每项技能分别构建一个 zip 文件。zip 文件会放在 dist/claude-skills/ 中，该目录已被 git 忽略：

   node scripts/build-claude-skills.mjs
   

   每个 zip 文件都在根目录下包含技能文件夹，例如 coverage-check.zip 中包含 coverage-check/SKILL.md。如果 SKILL.md 不符合 claude.ai 规则（名称与其文件夹名称一致，描述不超过 200 个字符），构建将失败。

3. 上传每个 zip 文件：打开 Customize > Skills（旧版本中为 Settings > Capabilities > Skills），点击 Add，然后选择 zip 文件。自定义技能需要启用了代码执行功能的 Pro、Max、Team 或 Enterprise 方案。每位用户都需要上传自己的副本。