Backwork

Backwork MCP Server

Backwork API 用の公式 Model Context Protocol（MCP）サーバーです。AI アシスタントから、Medicare および支払者の医療ポリシー、医療コードのインテリジェンス、事前承認チェック、請求検証、コンプライアンスレビュー、医薬品フォーミュラリーの根拠、Webhook 操作に、制御された方法でアクセスできます。

接続方法は 2 通りあります。

	ホスト型リモート	ローカル stdio
エンドポイント	https://backworkhealth.com/mcp（Streamable HTTP）	npx -y @backwork/mcp
認証	ブラウザーでの OAuth、コピーするキーは不要	BACKWORK_API_KEY=bwk_live_...
利用する場合	クライアントが OAuth によるリモート MCP に対応している場合	クライアントがローカルコマンドのみを実行する場合、またはサーバーを自分のマシンで実行したい場合

ホスト型エンドポイントが受け付けるのは OAuth のみです。Backwork API キーをベアラートークンとして 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（1 つのプロジェクト）に追加します。初回の接続時に 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 接続として接続します。3 つのツールは小さなカードを返し、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、Articles、NCD）のリンク、またはその他のポリシーでは出典文書への ポリシーを開く リンク
backwork_prior_auth_research	事前承認チェックリスト	判定と信頼度、事前承認が必要なコード、収集すべき書類、既知の不足情報、番号付きの引用。調査タスクを開始すると、再度質問するまで保留中として表示されます
backwork_policy_research	ポリシー調査	アクションごとに、compare は Medicare の各契約事業者（MAC）におけるコードを横並びで表示します。管轄区域ごとに 1 列となり、各セルに適用範囲の判断とポリシーが表示され、列ごとの適用件数も表示されます。search は一致したポリシーを、支払者、番号、発効日、簡単な概要、リンクとともに一覧表示します。get は 1 つのポリシーの概要、各セクションの基準抜粋、対象コードを表示します。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 キーまたはデュアル認証モードでプライベートなセルフホストサーバーをデプロイし（セルフホスティングを参照）、キーをベアラーヘッダーとして送信します。

{
  "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
許可されたホスト	ループバック／プライベートホスト、VERCEL_URL、または設定済みのパブリックホスト	BACKWORK_MCP_ALLOWED_HOSTS または BACKWORK_MCP_PUBLIC_HOST

HTTP モードでは、各リクエストに Authorization: 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 保護リソースメタデータを公開し、その URL を WWW-Authenticate チャレンジに含めます。Backwork API が OAuth アクセストークンを直接受け付ける場合、追加のマッピングは不要です。MCP サーバーは OAuth ベアラーをそのまま下流に転送します。認可サーバーがトークンイントロスペクションで 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

BACKWORK_MCP_ALLOW_ENV_KEY=true は、ネットワークアクセス制御で保護されたループバックまたはプライベートネットワークのデプロイでのみ使用してください。パブリックデプロイでは、各リクエストにベアラートークンを必須とし、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 以降が必要です。

利用可能なツール

ツール名には、このサーバーをほかの MCP サーバーと並べてインストールしたときに見つけやすくするため、backwork_ プレフィックスが付いています。デフォルトのインターフェースは意図的に 1 対 1 の API ラッパーではなく、ワークフローレベルにしています。これにより、エージェントに表示される選択肢が減り、一般的なタスクに必要なツール呼び出しも少なくなります。

すべてのツールには、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 にはエージェントが引用に必要な情報が含まれ、テキスト出力の末尾には短い --- 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 エージェントのツール結果に含まれる 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、HTTPS を使用する発行元インデックスの掲載情報（最大 16 件）、およびサポートされている 3 種類（non_medicare_disclaimer、commercial_policy_header、member_type_branch）の記述（最大 16 件）に限定されます。引用は最大 4,000 文字、インデックス URL は最大 2,048 文字で、ページ番号は正の整数である必要があります。不明なフィールドは破棄され、不正な形式の根拠情報は null になります。市場コードと注記にも上限が設けられています。MCP は API の信頼度と手動レビューの出力を保持しますが、インデックスの掲載情報によって信頼度が上がったり、承認の要否が解決されたりすることはありません。

コード一致では、抽出元の source とは別に grounding が保持されます。

grounding	意味
grounded	Backwork が保持する情報源テキスト内で見つかった
not_grounded	文書パイプラインで読み取られたが、保持されている情報源テキスト内では見つからなかった
no_source_text	確認に使用できる保持済みテキストがなかった
not_checked	ポリシーのタイトルから推定されたコードなど、グラウンディングが確認されていない

テキストとカードでは、グラウンディングされたコードを補償の保証として扱わずに、これらの確認結果を表示します。grounding を含まない旧式のレスポンスでは、状態は不明のままです。認識されない将来の値は保持され、ラベルが付けられます。

本番環境での利用可否

サーバーが提供するアクションは、次の 2 つによって決まります。

• 利用可否。 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 入力も利用できません。また、backwork_compliance_review では確認用の入力（diff_id、diff_ids、notes）がなく、結果にも差分 ID が含まれません。Backwork API キー（stdio、または bwk_ ベアラーを使用した HTTP）では、すべてのツールとアクションが提供され、API がキー固有のスコープを適用します。OAuth グラントのスコープに write が含まれていない場合、そのグラントは読み取り専用として扱われます。

提供されるアクションがないツールは非表示になります。一部のアクションだけが提供されるツールでは、非提供のアクションが action 入力から除かれます。本番環境では利用できないアクションも、その説明に明記されます。BACKWORK_API_BASE を指定して別の Backwork デプロイメントに接続したサーバーでは、利用可否マーカーは無視されます。BACKWORK_MCP_EXPOSE_UNAVAILABLE_TOOLS=true を設定した場合も、本番環境で同様に無視されます。どちらの場合も、書き込みスコープのルールは適用されます。

主要ツール	目的
backwork_coverage_lookup	手技コードを検索し、コードの詳細、ポリシーの根拠、事前承認、請求リスク、管轄区域の比較、支出の根拠を組み合わせます。payer を指定すると、コードの詳細にはその支払者のポリシーのみが一覧表示され、対象外となった他の支払者のポリシー数も示されます
backwork_policy_research	ポリシーを検索する、ポリシーを 1 件取得する、抽出された基準を検索する、ポリシーの変更を確認する、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 の 1 種類です。ポリシー変更の Webhook は送信されません。書き込みスコープを持つ API キーが必要です
backwork_system_health	Backwork API のヘルスと依存関係の状態を確認します。API キー接続のみで利用できます

応答形式

すべてのツールで、次の値を指定できます。

{
  "response_format": "markdown"
}

読みやすい出力には "markdown" を、テキストコンテンツを返された structuredContent に合わせるには "json" を使用します。

プロンプトの例

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 カードを対象とします。ChatGPT カードについては、ツール一覧内のテンプレート、リソースと MIME タイプ、各カードのstructuredContentとスキーマとの照合、UI のないクライアント向けの Markdown、さらにカード付きの各ツールのすべてのアクションについて、スタブブラウザーで各カードページをレンダリングし、カードが表示されるか高さがゼロに折りたたまれることを確認します。

公開前に、npm run verify:packageを実行します。このコマンドは、リポジトリのオーバーライドやロックファイルを使わずに、パッケージ化した tarball を一時的なコンシューマーにインストールし、現在のランタイムと Node 18.20.8 の両方で、2 つのトランスポートを実行します。CI でも同じチェックを実行します。追加の正確な Node バージョンは、--の後に指定できます。

API コントラクト

このサーバーが呼び出すすべての Backwork エンドポイントは、送信するリクエストフィールドと読み取るレスポンスフィールドとともに、src/api-operations.tsに記載されています。ツールは、このカタログを介してのみ API を呼び出せます。各エントリには、操作の利用可能性マーカーと必要なスコープも反映されています。npm testでは、カタログをベンダー管理下のopenapi/backwork-openapi.jsonと照合し、本番環境、読み取り専用の OAuth 権限、API キーのそれぞれに対して、サーバー独自の公開ルールがどのツールアクションを提示するかを確認します。本番環境で提供されない操作、利用不可とマークされた操作、または（OAuth 権限の場合）writeスコープで保護された操作に対してアクションが提示されると、失敗します。

CI ではnpm run contract:liveを実行します。このコマンドは、https://backworkhealth.com/openapi.jsonを使って同じチェックを実行し、説明、概要、例以外の箇所でベンダー管理下のコピーと異なる場合は失敗します。

Backwork API に変更があった場合は、ベンダー管理下のコピーを更新し、差分を確認してください：

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 がオーバーライドを適用するのはコンシューマーのルートパッケージだけなので、このパッケージ内のオーバーライドではその保証を提供できません。リリース時の依存関係ツリーを再現するには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 レジストリ に io.github.tylergibbs1/backwork-mcp として登録するための情報を記述します。対象は、ホスト型の Streamable HTTP リモート（https://backworkhealth.com/mcp、保護リソースのメタデータから検出される OAuth）と、stdio 経由の @backwork/mcp npm パッケージです。package.json には、レジストリが npm の所有権を確認するために使用する、一致する mcpName が含まれています。npm test は server.json がレジストリのスキーマに準拠していることを検証し、バージョンが package.json と一致していることを確認します。

リリース

リリースでは、Trusted Publishing（GitHub OIDC、npm トークン不要）を使用して @backwork/mcp を npm に公開し、その後 server.json を MCP レジストリに公開します。

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	不要	ベアラー認証なしのプライベート HTTP リクエストで BACKWORK_API_KEY を使用できるようにします。
BACKWORK_MCP_AUTH_MODE	不要	HTTP ベアラーモードです：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	不要	基本認証を使用しない場合にイントロスペクションで使用するベアラートークンです。
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

リモートサーバーがベアラートークンを受信していません。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 のウェブアプリは、本番環境の署名または Redis/KV 状態ストレージが不足しているため、意図的に OAuth の提示を拒否しています。

ツール呼び出しの認証は成功するものの、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 サーバーと、事前承認、適用範囲の確認、ポリシーの変更、否認への異議申し立ての準備に関する4つのリサーチスキルが含まれています。このリポジトリのプラグインマーケットプレイスからインストールします。

/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 のスキル

同じ4つのスキルを claude.ai でも使用できます。ツールを呼び出すには Backwork コネクターが必要です。

1. コネクターを追加します。Settings > Connectors > Add custom connector を開き、名前に Backwork を設定して、https://backworkhealth.com/mcp を入力します。OAuth サインインを完了します。

2. スキルごとに zip を1つ作成します。zip は git の対象外である dist/claude-skills/ に出力されます。

   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 プランが必要です。各ユーザーが自分用のコピーをアップロードします。