ConnectWise CPQ

connectwise-cpq-mcp

ConnectWise CPQ (Sell) 向けの MCP サーバーです — 見積もり、明細、顧客、条件、タブ、テンプレート、税コード、定期収益、ユーザーに対応します。

分割 v2 SDK（@modelcontextprotocol/server / /node / /client ^2.0.0-beta.5）を使用し、MCP 2026-07-28 仕様に基づいて構築されています。2 つの世代に対応したサービス提供により、createMcpHandler({ legacy: 'stateless' }) の背後にある共通の McpServerFactory が、2025 年世代の initialize ハンドシェイククライアント（現在の WYRE ゲートウェイ）と最新の 2026-07-28 エンベロープクライアントの両方に応答します。呼び出し元を問わず、同一かつ決定的な 25 個のツールを提供します。GHCR コンテナーのみで提供されます（MCPB バンドルはありません）。

ツール（25 個、フラット）

読み取り：cpq_test_connection、cpq_search_quotes、cpq_get_quote、cpq_get_quote_versions、 cpq_search_quote_items、cpq_get_quote_item、cpq_list_quote_customers、 cpq_search_quote_tabs、cpq_list_quote_terms、cpq_list_templates、cpq_list_tax_codes、 cpq_list_recurring_revenues、cpq_list_users。

書き込み：cpq_create_quote_from_template、cpq_update_quote（⚠ 影響大）、 cpq_create_quote_item、cpq_update_quote_item、cpq_update_quote_customer、 cpq_create_quote_term、cpq_update_quote_term、および ⚠ 破壊的 — 取り消し不可の 削除：cpq_delete_quote_item、cpq_delete_quote_term、cpq_delete_quote_customer、 cpq_delete_quote_version、cpq_delete_quote。

見積もりの作成はコピーのみ（/api/quotes/copyById）です。CPQ API には、新規作成、公開／電子署名、注文の移行、PDF、製品カタログのエンドポイントはありません（これらには connectwise-psa を併用してください）。

認証情報

CPQ には API ユーザーと CPQ 2022.2 以降が必要です。以下の 3 項目すべてが必須です。

環境変数（env モード）	ゲートウェイヘッダー（AUTH_MODE=gateway）	確認場所
CPQ_ACCESS_KEY	X-CPQ-Access-Key	Sell URL：...home?accesskey=<this>
CPQ_PUBLIC_KEY	X-CPQ-Public-Key	Settings → Organization Settings → API Keys
CPQ_PRIVATE_KEY	X-CPQ-Private-Key	キー作成時に一度だけ表示

ゲートウェイモードでは、いずれかのヘッダーがないリクエストには、MCP ハンドラーの実行前に 401（JSON-RPC エラー -32001）が返されます。環境変数の認証情報にはフォールバックしません。

ローカル設定には .env.example をコピーしてください。このファイルでは CONDUIT_S2S_SECRET を空のままにしてください。

変数	必須	説明
CPQ_ACCESS_KEY、CPQ_PUBLIC_KEY、CPQ_PRIVATE_KEY	stdio および AUTH_MODE=env の場合	ConnectWise CPQ API ユーザーのキーです。ゲートウェイの Compose サービスでは設定されません。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose のデフォルト）または env。ゲートウェイモードでは、各 /mcp リクエストに 3 つの X-CPQ-* ヘッダーが必要で、CPQ_* にはフォールバックしません。env は S2S 認証の成功後にのみこれらの変数を使用します。
CONDUIT_S2S_SECRET	HTTP の場合は必須	サービス間シークレットです。空の場合、または既知のプレースホルダー（changeme、replace-with-a-real-secret、その他の公開されているサンプル値）の場合、HTTP サーバーはエラーをログに記録して、ゼロ以外の終了コードで終了します。Compose はこの値がないと起動しません。実際の値をコミットしないでください。openssl rand -hex 32 で生成してください。
MCP_ALLOW_INSECURE_DEV	いいえ	ローカル開発で CONDUIT_S2S_SECRET なしに HTTP を起動する場合に限り、値を正確に 1 に設定してください。プロセスは警告をログに記録し、X-Gateway-S2S を強制しません。MCP_HTTP_HOST が 0.0.0.0 のような、より広範囲のアドレスであっても、リスナーは 127.0.0.1 に固定されます。プレースホルダーのシークレットは引き続き拒否されます。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http の場合のバインドアドレスです。デフォルトは 127.0.0.1 です。CONDUIT_S2S_SECRET が設定されている場合に有効です。コンテナーイメージでは 0.0.0.0 に設定されます。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。

/health と /healthz は認証なしで利用でき、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。検証処理は src/s2s-verify.ts の verifyS2sHeader です。ヘッダー値は t=<unix seconds>,v1=<hex> で、CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> そのものに対する HMAC-SHA256 の結果を 64 文字の小文字の16進数で指定します。タイムスタンプはサーバーの時刻から300秒以内でなければなりません。ヘッダーがないか無効な場合、ベンダーの認証情報を読み込む前に 401 を返します。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H 'X-CPQ-Access-Key: your-access-key' \
  -H 'X-CPQ-Public-Key: your-public-key' \
  -H 'X-CPQ-Private-Key: your-private-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway では、この3つの X-CPQ-* ヘッダーがそのリクエストの唯一の認証情報ソースです。AUTH_MODE=env では、署名付きリクエストのヘッダーがない場合、環境変数の CPQ_ACCESS_KEY、CPQ_PUBLIC_KEY、CPQ_PRIVATE_KEY が使われます。

実行

export NODE_AUTH_TOKEN=$(gh auth token)   # GitHub Packages auth for @wyre-ai/*
npm install
npm run build
node dist/index.js                        # stdio (default)
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http node dist/index.js
node scripts/smoke-dual-era.mjs           # proves both protocol eras serve the same tools

シークレットなしのローカル HTTP は、開発用途に限られます。127.0.0.1 にバインドし（ループバック以外の MCP_HTTP_HOST は上書きされ、その旨がログに記録されます）、警告をログに出力します。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 node dist/index.js

ローカル開発に関する注意： @wyre-technology/node-connectwise-cpq は ^1.0.0 として宣言されていますが、 まだ公開されていません。SDK の最初のリリースが公開されるまでは、新規クローンからの npm ci は失敗します。 代わりに、ローカルでビルドした SDK の tarball をインストールしてください。 npm install /path/to/wyre-ai-node-connectwise-cpq-0.0.0-semantically-released.tgz （その後も package.json は ^1.0.0 のままにしてください）。

Docker（フリートの規定により linux/amd64）：

イメージはコンテナ内で 0.0.0.0（MCP_HTTP_HOST）をリッスンし、デフォルトで AUTH_MODE=gateway に設定されます。ポートをループバックに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、CPQ の認証情報は各リクエストのヘッダーで渡され、環境変数からは読み込まれません。

docker build --platform linux/amd64 --build-arg GITHUB_TOKEN=$(gh auth token) \
  -t connectwise-cpq-mcp .
docker run \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  connectwise-cpq-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合に起動を拒否し、AUTH_MODE のデフォルトを gateway に設定し、127.0.0.1:8080:8080 を公開します。また、CPQ_ACCESS_KEY、CPQ_PUBLIC_KEY、CPQ_PRIVATE_KEY は注入しません。

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
GITHUB_TOKEN=$(gh auth token) docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、CPQ_* 変数が使われます。

docker run \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e CPQ_ACCESS_KEY=... \
  -e CPQ_PUBLIC_KEY=... \
  -e CPQ_PRIVATE_KEY=... \
  -p 127.0.0.1:8080:8080 \
  connectwise-cpq-mcp

MCP Apps の見積カード

cpq_get_quote は、見積ヘッダー、ステータスバッジ、明細の概要、合計金額を表示する読み取り専用の MCP Apps カード （ui://connectwise-cpq/quote-card.html）を提供します。このカードはあくまで機能を追加するものです。MCP Apps に対応していないホストには完全な QuoteView JSON が返され（_card フィールドは追加情報であり、置き換えではありません）、カードのビルドに失敗しても JSON は変更されません。npm run build:ui で埋め込み UI を再ビルドします（出力先は src/generated/quote-card-html.ts で、コミット対象です）。配信時のブランド設定には MCP_BRAND_* 環境変数を使います。

情報要求と破壊的操作への同意

接続されたクライアントが情報要求に対応している場合、サーバーは操作の前に確認を求めます。フィルターなしの見積もり検索では日付範囲を、曖昧な名前ではテンプレートを、項目の追加時にはタブを選択するよう求め、削除の前には毎回確認を行います。情報要求は SDK v2 の MRTR 境界を介して行われます。ハンドラーは input_required の結果（埋め込みの elicitation/create リクエスト）を返し、2026-07-28 のクライアントはそれを満たして再試行します。また、SDK のレガシーシムは、2025-era のステートフル接続（stdio）について、サーバー側でこれを満たします。すべての情報要求は MRTR に安全です。情報要求の時点より前にベンダーへの変更処理が実行されることはないため、クライアントが元のリクエストを再試行しても書き込みが重複することはありません。

フォーム情報要求機能を宣言していない呼び出し元（WYRE Conduit ゲートウェイの接続方法であるステートレスなレガシー HTTP リクエストを含む）には、確認を求めることができません。その場合の動作は、リスクに応じて異なります。

• 任意の情報要求は、適切にフォールバックします（design.md §4）。フィルターなしの検索ではデフォルトの 90 日間にフォールバックしてその旨を伝え、曖昧なテンプレート／タブ選択では候補を列挙したエラーを返します。
• 破壊的なツールはフェイルクローズします。応答できないクライアントは同意していないため、5 つの cpq_delete_* ツールは実行を拒否し、必要な対応を示すエラーを返します。非対話型の呼び出し元は、各破壊的ツールの入力スキーマで宣言されている "confirm_destructive_action": true を呼び出しごとに指定して、明示的に同意します。この引数が参照されるのは、プロンプトを表示できない場合に限られます。対話型ユーザーに表示されるはずの確認を省略することは決してありません。

ここに反映されているベンダー固有の動作

• Authorization ヘッダーがない場合、CPQ は 500 を返します（401 ではありません）。リクエストを送る前に、クライアント側で認証情報を検証します。
• 実際の 401 レスポンス本文には、ベンダーの誤記（"...has occured during basic auth validation"）が含まれます。
• すべてのリクエストに Content-Type: application/json; version=1.0 を指定します（メディアタイプによるバージョン管理）。
• リストのレスポンスは JSON 配列そのものです。ページが短ければページネーションは終了します。
• 条件の日付は日付のみで、角括弧で囲む必要があります：createDate >= [2026-07-01]。
• PATCH の本文は RFC 6902 JSON Patch 配列です。

ライセンス

Apache-2.0 © WYRE Technology