MCP サーバー

Zelnum は https://mcp.zelnum.com/mcp で公開 MCP サーバーを提供しています。MCP 対応のクライアント — Claude、Cursor、IDE 内のエージェント — であれば、連携コードを書かずに、製品の一覧取得、1 件の検出の見積もり、実行、結果の読み取りまで行えます。URL は全顧客で共通です。ご自身の API Key で接続し、料金はご自身の残高から引かれます。

接続先

項目	値
URL	`https://mcp.zelnum.com/mcp`
トランスポート	Streamable HTTP
認証情報	`Authorization: Bearer YOUR_KEY_HERE`

認証情報は REST 呼び出しで使うものと同じ API Key です。コンソールの API Center で作成・再生成・失効できます。

クライアントの接続

3 ステップで完了します。インストールは不要です。

1. キーを作成します。 コンソールの API Center で API Key を作成します — REST 呼び出しで使うものと同じキーです。Authentication を参照してください。

2. サーバーを追加します。 標準の mcpServers を読む Cursor などのクライアントは、このエントリをそのまま使えます:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Claude ではカスタムコネクタのダイアログに同じ 2 つの値を入力します — URL と、キーを載せた Authorization ヘッダーです。

3. 接続を確認します。 エージェントに、リアルタイムで検査できる製品を挙げてもらってください。接続できていれば list_products を呼んで回答します。このツールは読み取り専用で無料なので、確認に費用はかかりません。代わりに 401 が返る場合は、キーの欠落・失効、またはプラットフォームが受け付けていないことを意味します。

ツール

ツール	動作	課金
`list_products`	有効な製品の一覧（ID・slug・series）。読み取り専用。	いいえ
`get_balance`	この接続が認証されているアカウントの残高。読み取り専用。	いいえ
`quote_realtime_check`	1 件の検出に対する正式な見積もり価格。エージェントが信頼すべき唯一の価格ソースです。	無料
`check_realtime`	最大 10 製品に対してリアルタイム検出を 1 件実行します。	はい
`create_bulk_task`	非同期の一括タスクにインライン配列を送信します。	はい
`get_task_status`	一括タスクの進捗と課金カウンター。	いいえ
`get_task_result`	完了したタスクの結果メタデータと認証済みダウンロードリンク。	いいえ

こう話しかけられます

上はエージェントが呼ぶツール、下はあなたが入力する文です。どれも既存のツールが処理します — 特別な言い回しはありません。

こう言う	起きること
リアルタイムで検査できる製品はどれですか？	`list_products` を呼び、使うべき ID を返します。無料。
残高はいくらですか？	接続に使ったキーの `get_balance` を呼びます。無料。
`+14155550123` を WhatsApp で検査するといくらですか？	`quote_realtime_check` を呼び、価格を表示します。無料で、課金は発生しません。
その価格で進めてください。	見積もりの製品に対して `check_realtime` を呼び、見積もり額を課金します。
この 200 件の番号を WhatsApp で検査して、終わったら教えてください。	`create_bulk_task` を呼び、その後 `get_task_status` を問い合わせて進捗を報告します。
そのタスクは終わりましたか？ダウンロードリンクを送ってください。	`get_task_result` を呼び、認証済みリンクを返します。

身につけておきたい 2 つの習慣:

まず価格を尋ねる。 課金対象のツールは課金前に必ず見積もりを返すので、いくらかかるかの確認は常に無料です。実際にお金が動くのは確認のステップだけです。
番号が E.164 でない場合は country を指定する。 +14155550123 は国を伴っていますが、0812345678 は伴いません。ゲートウェイは推測を拒否します。

課金の確認

課金対象のツールは最初の呼び出しでは一切請求しません。confirmed を付けずに呼び出すと、代わりに確認用ペイロード — 製品、件数、見積もり金額 — と、その入力内容に署名した quote_token を返します。同じ呼び出しを次の内容で繰り返して確定します:

confirmed を true に設定
そのペイロードの quote_token
quoted_total — 提示された金額と完全に同じ値
同じ識別子、製品、country フィールド

エージェントが冪等キーを自分で用意することはありません。ゲートウェイが署名済み見積もりから導出するため、承認済みの同じ見積もりは、再試行・再接続・ゲートウェイの再起動をまたいでも同じキーを保ちます。別の課金には新しい見積もりが必要です。タイムアウトで結果が不明な場合は、パラメータを変えずに同一の呼び出しを繰り返してください。

識別子の扱い

識別子のルールは REST 契約と同じです。エージェント側の検証を通るものは、そのまま API が受け付けます:

country を省略 — 識別子は + 始まりの E.164 形式の番号でなければなりません。
country を指定 — 大文字 2 文字の ISO コードを渡し、識別子は国内番号または E.164 形式の番号になります。
0812345678 のように複数の国に該当する曖昧な国内番号から国を推測することは決してありません。country を省略できるのは、番号自体が完全な E.164 形式のときだけです。
電話番号製品の一括タスクでは country の明示が必須です。

資金のガードレール

エージェントと残高の間には 4 つのガードレールがあります:

署名済み見積もり。 プラットフォームは最新の価格を読み、アカウント・正確な入力・製品・価格スナップショットを束ねた暗号化済みの見積もりを返します。入力の変更、見積もりの失効、価格の変動は、請求が発生する前に拒否されます。
決定論的な冪等性。 冪等キーはモデルではなく署名済み見積もりから得られるため、どのような文言のリクエストでも 1 回の承認が 2 回の課金になることはありません。
キー単位の上限。 1 日あたりの課金上限と残高の下限は API Key ごとに適用され、各予約は上流呼び出しの前に直列化されるため、並行して動くエージェントがこれをすり抜けることはできません。
フェイルクローズ。 残高を読めない場合や壊れた形式で返ってきた場合、課金対象の呼び出しは無防備に実行されるのではなく拒否されます。

エラーと制限

認証情報が欠落または不正な形式の場合は、リクエストがプラットフォームに届く前に HTTP 401 で拒否されます。
プラットフォームが受け付けないキーは、上流のステータスとボディを伴うツールエラーとして返るため、エージェントは盲目的に再試行せずそのまま報告します。
レート制限・エラーコード・結果のダウンロードは REST とまったく同じ挙動です。ゲートウェイが覚えるべき第二の契約を追加することはありません。

次のステップ

Authentication — 接続に使うキーを作成します。
Realtime check — check_realtime の背後にあるエンドポイント。
Bulk workflow — create_bulk_task の背後にある非同期経路。
Error codes — プラットフォームが返すエラーコード。