smartroutes

SmartRoutes MCP サーバー

SmartRoutes のルート最適化と配車のツールを、Claude Desktop、Claude Code、Cursor、Windsurf などの AI アシスタントや、その他の Model Context Protocol クライアントに公開し、ライブデータを使って操作できます。

概要

MCP サーバーは、AI ツールをお使いの SmartRoutes アカウントのライブデータに接続します。まだスケジュールされていない注文の確認、ルート計画の確認、最適化の開始などを、実際のデータを使ってチャット上で行えます。

SmartRoutes REST API と同じ操作を、エージェントが直接呼び出せるわかりやすいツールとして公開します。すべての操作は API キーによって単一のアカウントに限定されます。

利用可能なツール

ツール	種類	説明
list_orders	読み取り	デポの注文（ステータス、顧客、注文番号、最終更新日時で絞り込み可能。ページネーション対応）
get_order	読み取り	個別の注文の詳細情報
add_order	書き込み	新しい注文を作成（集荷、配達、または発送）
check_booking_availability	読み取り	時間枠と住所に対応できるかどうか
optimise_plan_for_date	書き込み	指定日のルート最適化を開始
get_optimisation_status	読み取り	最適化ジョブが完了するまで状態を確認
get_plan	読み取り	プラン ID ごとのプラン全体の集計とルート概要
get_route	読み取り	個別ルートの停車地点ごとの詳細
list_vehicles	読み取り	シフト、積載量、スキルを含む車両一覧
get_vehicle	読み取り	個別の車両の詳細情報
list_customers	読み取り	デポの顧客一覧

各ツールには、AI クライアントが読み取りと書き込みを区別できるよう注釈が付いています。9 つの読み取りツールには読み取り専用の注釈が付いています。add_order と optimise_plan_for_date には書き込みの注釈が付いており、さらに optimise_plan_for_date には破壊的操作の注釈が付いています。これは、自動配車によってプランがドライバーに公開され、顧客に通知されるためです。破壊的操作を制御するクライアントでは、実行前に確認を求められます。

読み取り専用モード

これらの注釈は、クライアントが尊重するかどうかを選べるヒントです。書き込みを不可能にするには、次のヘッダーを追加します。

x-access-scope: read-only

これにより、サーバーが公開するのは9つの読み取りツールだけになります。add_order と optimise_plan_for_date はツール一覧に表示されず、呼び出すこともできません。そのため、アシスタントが誤って実行する心配はありません。テスト中や、情報の参照のみを許可したい場合に便利です。

すべてのツールを使う場合は、このヘッダーを省略します。それ以外の値は無視されずに 400 が返されるため、入力ミスによって書き込みアクセスが意図せず有効になることはありません。

{
  "mcpServers": {
    "smartroutes-readonly": {
      "type": "http",
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>",
        "x-access-scope": "read-only"
      }
    }
  }
}

両方の設定を並べて登録し、会話ごとに選択できます。リクエストヘッダーを設定できるクライアントであれば、どれでも利用できます。

セットアップ

1. API キーを取得する

MCP サーバーでは、既存の SmartRoutes API キーを使用します。REST API ですでにお使いのものと同じキーです。別途 MCP 用の認証情報やサインイン手順は不要で、期限切れや更新が必要なトークンもありません。

API キーを生成するには、SmartRoutes アカウントにログインし、「Settings > Integrations > SmartRoutes Open API」に移動して、「Generate API Key」ボタンをクリックします。

このキーは秘密情報として扱ってください。アカウントのデータへのアクセス権が付与されます。

2. 送信方法を選択する

2つのヘッダーが使用でき、どちらも同じAPIキーの値を使うため、互換性があります。

ヘッダー	使用する場面
Authorization: Bearer <your-api-key>	どこでも使用できます。認証情報フィールドが Authorization のみのホスト型プラットフォームでは、こちらを使用してください。Mistral Studioやほとんどのコネクターディレクトリが該当します。
x-access-key: <your-api-key>	同様に有効で、変更せずに使用できます。ヘッダー名を自分で指定できる場合に使用してください。Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、自作スクリプトなどが該当します。

知っておくとよい点：

• スキーム名の大文字と小文字は区別されません。Bearer、bearer、BEARER はすべて使用できます。キー自体は大文字と小文字が区別されるため、正確にコピーしてください。
• Basic と Digest はサポートされていません。 設定するツールでユーザー名／パスワード形式の認証情報しか選べない場合は、自分でキーをBase64エンコードせず、お問い合わせください。キーは拒否されます。
• 送信するのは2つのうちどちらか1つです。両方が異なる値で指定されている場合、アシスタントが誤ったアカウントを参照する可能性があるため、どちらかを選ぶのではなくリクエストが拒否されます。両方を同じ値で送信するのは問題ありません。

3. AI ツールを接続する

各クライアント向けのすぐにコピーできる設定ファイルは examples/ にあります。キーを入力すれば使えます。

クイックスタート（Claude Code）

このリポジトリには、設定済みの .mcp.json が含まれています。<your-api-key> を置き換えるだけです。

{
  "mcpServers": {
    "smartroutes": {
      "type": "http",
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

Claude Codeは、プロジェクトを開くとこのファイルを自動的に検出します。

Claude Desktop

Settings → Connectors → Add custom connector に移動して、SmartRoutesのカスタムコネクターを追加します。

ここで次の詳細を追加できます。

• Name： SmartRoutes（または任意の名前）
• URL： https://mcp.smartroutes.io/mcp

同じダイアログのAdvanced settings / Request headersで、認証ヘッダーを追加します。

• Key： x-access-key
• Value： 実際のAPIキー

または、次の内容をClaude Desktopの設定ファイル（claude_desktop_config.json）に追加できます。

{
  "mcpServers": {
    "smartroutes": {
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

Mistral Studio

SmartRoutesをコネクターとして登録します。

• URL: https://mcp.smartroutes.io/mcp
• ヘッダー名: Authorization
• ヘッダー値: Bearer <your-api-key>

MistralのConnectors Debuggerでは、サーバーを登録する前に検証できます。認証情報は Authorization ヘッダーとして入力するため、上記のBearer形式を使用します。Debuggerはパブリックプレビュー中のため、フィールド名が変更される場合があります。重要なのはURLとヘッダー値です。

Cursor

Cursorの設定で、MCP サーバーを追加します。

• 名前: smartroutes
• タイプ: Streamable HTTP
• URL: https://mcp.smartroutes.io/mcp
• ヘッダー: x-access-key: <your-api-key>

Windsurf

WindsurfのMCP設定（mcp_config.json）に追加します。

{
  "mcpServers": {
    "smartroutes": {
      "serverUrl": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

任意のMCPクライアント（汎用）

このサーバーはStreamable HTTPトランスポートを使用します。どちらのヘッダーも使用できます。

POST https://mcp.smartroutes.io/mcp
Authorization: Bearer <your-api-key>

POST https://mcp.smartroutes.io/mcp
x-access-key: <your-api-key>

Streamable HTTPに対応する任意のMCPクライアントが接続できます。レガシーSSEクライアントは自動的に処理されます。

4. ローカル開発

ローカルで実行中のサーバーに接続する場合、エンドポイントは次のとおりです（ローカルアプリがリッスンしている任意のポートを使用してください）。

http://localhost:3000/mcp-api

ローカルでのパスは /mcp-api です。mcp.smartroutes.io の短い /mcp は、同じエンドポイントを指す公開エイリアスです。どちらのヘッダーも、本番環境と同様にローカルで使用できます。

会話の例

接続後は、アシスタントに次のような質問をできます。

• 「明日の注文のうち、まだルートに割り当てられていないものはどれですか？」
• 「利用可能な車両とそのシフトを表示してください。」
• 「金曜日の午後2時から4時の間に、12 Main Stへの配達を組み込めますか？」
• 「未処理の注文すべてを対象に、明日のルートを最適化してください。まだ配車せず、下書きだけにしてください。」
• 「その最適化の状況はどうなっていますか？」
• 「2026-07-01の計画と、ルート3の停車地点を表示してください。」
• 「5 King StにあるACME宛ての10 kgの配達を追加してください。」

API キーの管理

MCP キーは、SmartRoutes API キーそのものです。

操作	説明
使用	REST API と同じキーを使用します。Authorization: Bearer または x-access-key として送信され、1 つのデポに限定されます。
無効化	SmartRoutes アカウントでキーを無効化すると、MCP と REST の両方へのアクセスが直ちにブロックされます。

トラブルシューティング

401 UNAUTHORIZED

サーバーが有効なキーを受け取れませんでした。レスポンス本文の description から、該当するケースを確認できます。

説明	対処方法
No API key provided…	どちらのヘッダーもサーバーに届いていません。ホスト型プラットフォームでは、フォームに入力しただけでなく、ヘッダーがコネクターに実際に保存されていることを確認してください。
Unsupported Authorization scheme…	Basic、Digest などを送信しています。受け付けられるのは Bearer のみです。
Authorization header has no credential after the scheme	値が Bearer の後に何も続いていません。
Authorization header must carry exactly one credential	1 つのヘッダー値に認証情報が 2 つ含まれています。
Conflicting credentials…	両方のヘッダーが異なる値で送信されました。どちらか一方を削除してください。
Invalid API Key provided	キーは届きましたが、アカウントと一致しません。Settings > Integrations からコピーし直してください。通常、貼り付けが途中で切れていることが原因です。
Attempting to use disabled API key	SmartRoutes アカウントでキーが無効化されています。新しいキーを生成してください。
API Key not authorized for expired trial account	アカウントのトライアル期間が終了しています。

すべての 401 レスポンスには、WWW-Authenticate: Bearer レスポンスヘッダーも含まれます。これは「ここでは Bearer トークンが必要です」という標準的な表現にすぎず、サーバーが OAuth を使用しているという意味ではありません。 サインインフローも、検出が必要な認可サーバーも、取得する /.well-known/ メタデータもありません。静的 API キーだけで認証します。このヘッダーを受け取った後にクライアントが OAuth フローを開始しようとする場合は、代わりに静的ヘッダー認証情報を設定してください。

エラー形式

認証は JSON-RPC レイヤーに到達する前に確認されるため、エラーには JSON-RPC エラーオブジェクトではなく、REST API と同じ形式が使用されます。

{
  "name": "UNAUTHORIZED",
  "statusCode": 401,
  "description": "…",
  "details": {}
}

例外として、会話の途中で最も発生しやすいのはレート制限です。この場合、MCP ツールの結果として name: "FORBIDDEN" と details.retry_after_seconds が返されるため、接続を切断せずにアシスタントが待機してから再試行できます。

セキュリティ

• 認証：API キーを Authorization: Bearer <key> または x-access-key ヘッダーとして送信します。Basic、Digest などの方式は拒否されます。
• デポの分離：各キーは 1 つのデポに限定され、すべてのデータはデポごとにフィルタリングされます。
• レート制限：各ツールにはキーごとのレート制限があり、REST API の制限と共有されます。
• 書き込みの確認：書き込みツール（add_order、optimise_plan_for_date）は、実行前にアシスタントが説明して確認を取るよう指示します。特に自動ディスパッチの場合は重要です。
• 共有コネクター：ワークスペースまたは組織に公開されるコネクターでは、閲覧できる全員で 1 つの API キーを共有し、監査ログには個々のユーザーではなくキーが記録されます。個人ごとの帰属情報が必要な場合は、個人用として登録してください。

仕組み

MCP サーバーは、SmartRoutes REST API と同じエンジンを実行します。各ツールは同じ基盤サービスを呼び出すため、MCP と API で動作やデータに食い違いはありません。トランスポートは Streamable HTTP で、認証には API キーを使用します。

「明日のルートを計画する」一般的なフロー：

1. list_orders / list_vehicles — 利用可能な内容を確認します
2. check_booking_availability — 時間枠を確認します（任意）
3. add_order — 新しい作業を登録します
4. optimise_plan_for_date — 計画を作成します（自動ディスパッチの前に確認してください）
5. get_optimisation_status — 完了するまで状態を確認します
6. get_plan / get_route — 結果を読み取ります