API ツールの作成
このガイドでは、プラットフォームで新しい MCP ツールを作成する手順を説明します。
API ツールは、外部サービスの連携や操作フローの自動化に使用します。
API とは？
API（Application Programming Interface、アプリケーションプログラミングインターフェース） は、異なるソフトウェアシステム間の通信をつなぐ橋渡しです。簡単に言うと、ソフトウェアの世界の「ウェイター」 のように、プログラム同士の情報交換や機能の実行を支援します。
レストランで食事をする場面を想像してください。
あなた：料理を必要とするお客様（アプリケーション）です
キッチン：料理を作る場所（サービスを提供するシステム）です
ウェイター：あなたとキッチンの間で情報を伝えます（API）
自分でキッチンに入る必要はありません。ウェイターに注文を伝えると、ウェイターがキッチンへ伝え、できあがった料理を運んでくれます。
API ツールは、標準化されたフローの自動実行や特定の応答形式の設定に役立ちます。また、システム内の情報を取得できます。たとえば、次のような用途があります。
EC カスタマーサポートの自動化
マーケティングキャンペーンの管理
オンライン講座プラットフォーム：
API ツールにより、AI アシスタントは単なるチャットボットから、業務フローを実際に実行できるインテリジェントなアシスタントへと進化し、作業効率と自動化の度合いを大きく向上させます。
API ツールをすばやく作成する
1. ツール管理画面を開く
まず、左側のナビゲーションバーから「AI 機能」を開き、「🔧 ツール」をクリックします。ツール一覧ページで、右上の「➕ ツールを追加」ボタンをクリックします。
2. ツールの種類を選択する
ツールの種類として API を選択します。
3. 表示名を設定する
ツールにわかりやすい表示名を設定します。ここでは google calendar とします。
用途：この名前はプラットフォームの画面に表示され、すべてのユーザーが確認できます。
推奨事項：ツールの主な機能が明確に伝わり、ユーザーが理解しやすい名前を選びます。厳密な形式の制限はありません。
4. ツール名を設定する
次に「ツール名」を設定します。
用途：AI アシスタントが内部でこのツールを呼び出し、識別するための一意の識別子です。
命名規則（重要）：
英字を使用する必要があります。
使用できる文字は次のとおりです。
英小文字（a-z）
英大文字（A-Z）
数字（0-9）
アンダースコア（
_）ハイフン（
-）
例：
get_weather_forecast,database-query-tool
下図では google_calendar_retriever と設定しています
5. ツールの説明を記述する
「ツールの説明」に、明確で詳しい説明を入力します。
重要性：適切な説明は、AI アシスタントが次の内容をより正確に理解するのに役立ちます。
ツールの機能と目的です。
ツールを使用すべきタイミングです。
ツールの出力結果の解釈方法です。
推奨する内容：ツールが何をするか、入力と出力は何か、使用上の注意事項を説明します。
6. API の詳細設定
a. 🔗 API URL
対象 API エンドポイントの完全な URL を入力します（
http://またはhttps://を含めます）。例：
https://api.opencalendar.org/data/2.5
b. 📮 HTTP メソッド
ドロップダウンから、API サービスが要求する HTTP メソッドを選択します。
GET：通常、リソースの取得に使用します。POST：通常、新しいリソースの作成やデータの送信に使用します。PUT：通常、リソース全体の置き換えや更新に使用します。DELETE：通常、リソースの削除に使用します。
c. 📰 ヘッダー（Headers）
ヘッダーは手紙の「封筒」のようなもので、実際のデータを読む前に重要な情報を受信側に伝えます。正しいヘッダーがないと、API リクエストの認証に失敗したり、受信側がデータを正しく解析できなかったりする可能性があります。
主な用途：
認証（
Authorization,X-API-Key）コンテンツタイプの指定（
Content-Type）受け入れる応答形式の指定（
Accept）
ヘッダーを追加するには、次の手順を実行します。
「➕ ヘッダーを追加」をクリックして、リクエストとともに送信する HTTP ヘッダーを定義します。
形式：有効な JSON オブジェクトを使用します。キー（Key）はヘッダー名、値（Value）はヘッダーの内容（文字列）です。
例：
d. 🔎 クエリパラメーター（Query Params）
クエリパラメーターは、URL の疑問符の後に付くクエリ文字列です（例：?format=json&limit=10）。呼び出しのたびにリクエストとともに送信されます。固定の検索条件や、クエリ文字列でしか渡せない API キーに適しています。
「利用可能なコンテキスト変数」をクリックすると、現在サポートされている変数（連絡先 ID、会話 ID、受信トレイ ID など）の一覧が展開されます。
形式：有効な JSON オブジェクトです。キー（Key）はパラメーター名、値（Value）はパラメーターの内容（文字列）です。
値には固定の文字列を指定するか、
{{參數名}}を使って「パラメータースキーマ」で宣言したパラメーターを参照できます。AI アシスタントが呼び出し時に値を入力するため、「前半は固定、後半はユーザーが指定する」検索条件を設定だけで実現できます。詳しくは、下の クエリパラメーターで AI アシスタントのパラメーターを参照する をご覧ください。例：
e. 🧩 パラメータースキーマ（Parameters Schema）
パラメータースキーマは「注文票」のようなもので、API にどのようなデータを、どのように要求できるかを AI アシスタントに伝えます。
基本設定：AI アシスタントがこのツールを呼び出す際に指定できる、または指定する必要があるパラメーター（システムに渡して処理する内容）と、その形式を定義します。
形式：標準の JSON Schema 形式を使用します。
主な要素：
type: "object"：パラメーターがオブジェクトであることを示します。properties：各パラメーターのオブジェクトを定義します。パラメーター名（例：
"search"）：対応するオブジェクトに、そのパラメーターの詳細を記述します。type：パラメーターのデータ型です（string,integer,number,boolean,array,object）。description：パラメーターの意味を AI アシスタントに説明します。default（省略可能）：パラメーターのデフォルト値です。enum（省略可能）：値が特定の選択肢に限られる場合、その選択肢を列挙します。
required：すべての必須パラメーター名を含む配列です。
例（メディア検索ツール）：
f. パスパラメーターとパラメーターの位置
API URL では、{參數名} を使って URL パス内の可変部分を指定できます。例：/users/{userId}/orders/{orderId}。AI アシスタントが指定した値を URL に代入するには、「パラメータースキーマ」で同名のパラメーターを定義し、その位置を「パス」に設定します。リクエストを送信する前に、システムが値を URL エンコードしてから代入します。たとえば A/B 01 は A%2FB%2001 となり、値に含まれるスラッシュや空白によって URL の構造が変わることを防ぎます。
使用例：カスタマーサポート責任者のマイさんは、AI アシスタントに顧客番号と注文番号を使って会社の注文 API から 1 件の注文を取得させたいと考えています。API ツールを作成し、両方の番号をパスパラメーターに設定して、AI アシスタントに割り当てます。同僚が会話で「顧客 customer-01 の注文 order-25 を調べてください」と入力すると、AI アシスタントが両方の番号を URL の正しい位置に入れて問い合わせます。注文番号がない場合、ツールは値の不足をすぐに報告し、不完全なリクエストは送信しません。
パラメータースキーマで同名のパラメーターを宣言する
パラメータースキーマ（JSON Schema） に次の内容を入力します。
パラメーター名は、URL の波括弧内の名前と大文字・小文字を含めて完全に一致する必要があります。required は、呼び出しのたびに両方の値が必要であることを AI アシスタントに伝えます。
入力後、パラメータースキーマの下に各パラメーターと位置のドロップダウンが表示され、初期値は「デフォルト」になります。この時点では、API URL の下に赤字で「次のパラメーターの位置は「パス」ではないため、URL 内のプレースホルダーは置換されません」と表示されます。次の手順を完了する必要があることを示しています。
パラメーターの位置を「パス」に設定する
パラメータースキーマの下で、userId と orderId の位置のドロップダウンを両方とも「パス」に変更します。
選択すると、システムがパラメータースキーマに "location": "path" を自動で追加し、API URL の下の赤字のメッセージも消えます。設定を確認し、「確認」をクリックしてツールを保存します。
位置が「デフォルト」のままのパラメーターは URL に代入されません。AI アシスタントが値を指定していても、URL 内の {userId} は値がない状態となり、ツールはエラーを報告してリクエストを送信しません。URL で使用するすべてのパラメーターを「パス」に設定してください。
AI アシスタントに割り当てて動作を確認する
AI アシスタントにツールを設定する に従って、Agent モードの AI アシスタントにツールを追加します。次に、左側のナビゲーションバーから「Agent マーケットプレイス」を開き、「組織独自作成」に切り替えます。対象の AI アシスタントを選択し、「顧客 customer-01 の注文 order-25 を調べてください」と入力します。AI アシスタントがツールを呼び出すと、httpbin は実際に受け取ったリクエスト URL https://httpbin.org/anything/users/customer-01/orders/order-25 を返します。
各呼び出しで実際に送信された URL を確認するには、左側のナビゲーションバーから「AgentOps」→「ツール実行ログ」を開きます。対象のレコードの操作欄にある目のアイコンをクリックして「詳細」を開き、「リクエスト情報」の「リクエスト URL」を確認します。下図は、顧客番号にスラッシュと空白（A/B 01）を含む呼び出しで、値が URL エンコードされていることを確認できます。
練習が終わったら、公開デモの URL を会社の注文 API の URL に変更します。
パラメーターの位置の選択肢
パラメータースキーマの各パラメーターには位置を設定でき、呼び出し時に値をリクエストのどこに配置するかを指定します。
デフォルト
元の動作を維持します。GET はクエリ文字列に、POST、PUT、PATCH は本文に配置します。DELETE では自動的に値を含めないため、値を渡す場合は位置を明示的に選択してください
パス
API URL 内の同名の {參數名} に代入します
クエリ
URL の疑問符の後のクエリ文字列に追加します
本文
JSON 本文に配置します
ヘッダー
パラメーター名を HTTP ヘッダー名として送信します。「ヘッダー（JSON）」に同名のヘッダーが設定されている場合（大文字・小文字は区別しません）、設定済みの内容が優先されます
位置が設定されていない既存ツールの動作は変わりません。
パスパラメーターの値がない場合はリクエストを送信しません
呼び出し時に URL 内のパスパラメーターのいずれかに値がない場合（AI アシスタントが指定していない、値が空、または位置が「パス」ではない場合）、ツールはすぐに停止し、「今回の呼び出しでパスパラメーター {orderId} に値がありません」と報告します。{orderId} を含む URL は送信しません。AI アシスタントは、問い合わせが失敗した理由を会話で説明します。「ツール実行ログ」では、該当レコードのステータスが失敗となり、「リクエスト情報」にリクエスト内容は表示されません。「エラーメッセージ」に、値がないパラメーターが示されます。
URL の記述上の制限
パスパラメーター名に使用できるのは英字、数字、アンダースコアのみで、数字から始めることはできません。例：
{order_id}。{order-id}のような名前では保存できません。{參數名}は URL のパス部分に配置してください。クエリ文字列に配置する値は、パラメーターの位置を「クエリ」にするか、Query Params で{{參數名}}を使って参照します。API URL では
{{變數}}のような二重波括弧の構文は使用できません。保存時に「エラー通知」が表示され、「パスパラメーターには {identifier} 構文を使用してください」と通知されます。API ツールでは、{{參數名}}は「ヘッダー（JSON）」と「Query Params（JSON）」で使用してください。
Google Style REST のカスタムアクションでは、コロンの接尾辞をそのまま使用できます。たとえば、Google Weather の問い合わせは次のとおりです。
7. 💾 ツールを保存する
すべての設定を確認し、ページ下部までスクロールして「確認」ボタンをクリックします。これで新しいツールの作成が完了します！
クエリパラメーターで AI アシスタントのパラメーターを参照する
多くの外部 API では、検索条件に「固定の構文＋ユーザーが指定する値」を組み合わせた 1 つの文字列を使用します。たとえば、OData 形式の $filter=ProductName eq 'Chai' や検索 API の q= パラメーターです。このような API では、独立したパラメーターではなく、固定の文字列に値を埋め込む必要があります。
「Query Params」の値に {{參數名}} と記述すると、AI アシスタントがツールを呼び出す際、MaiAgent が「パラメータースキーマ」の同名パラメーターの値を代入してからリクエストを送信します。設定者が固定の構造を記述し、AI アシスタントは値の入力だけを担当するため、構文の正しさをモデルに判断させる必要がなくなります。
使用例
購買部門は、社内の AI アシスタントに「ある製品の現在の単価と在庫はいくつですか」と直接回答させたいと考えています。データは、会社の商品カタログシステムが提供する OData クエリサービスから取得します。以前は、このような問い合わせのために API ごとにプログラムを作成する必要がありました。現在は、購買担当者が API ツールを作成し、検索条件を ProductName eq '{{product_name}}' に設定して、AI アシスタントに割り当てるだけで実現できます。同僚が会話で「Chai の単価と在庫はいくつですか」と尋ねると、AI アシスタントが検索条件に Chai を自動で代入し、API を呼び出して、製品名、単価、在庫を回答します。
設定手順
以下では、公開の Northwind デモデータサービス（OData）を使用します。そのまま手順に沿って操作できます。
AI アシスタントに割り当ててテストする
AI アシスタントにツールを設定する に従って、Agent モードの AI アシスタントにこのツールを追加し、保存します。次に、左側のナビゲーションバーから「Agent マーケットプレイス」を開き、「組織独自作成」に切り替えます。対象の AI アシスタントを選択して会話を開始し、「Chai の単価と在庫を教えてください」と入力します。AI アシスタントは「ツールを使用しました」と表示し、Chai の単価と在庫を回答します。
代入ルール
変数名はパラメータ構造と一致させる必要があります
{{product_name}} は「パラメータ構造」の properties にあるパラメータ名に対応します。大文字・小文字も完全に一致させてください
値のみが代入されます
テンプレートは Query パラメータの値にのみ適用されます。キー (Key) はそのまま保持され、代入の対象にはなりません
値は文字列のまま代入されます
パラメータ値は常に文字列としてそのまま代入され、数値には変換されません。たとえば、法人番号 04595257 の先頭のゼロは保持されます
値が欠けていると処理を中止します
今回の呼び出しで AI アシスタントが該当パラメータを指定していない場合（または値が空の場合）、ツールは不足しているパラメータを示すエラーで処理を中止します。{{product_name}} をそのまま送信することはありません
コンテキスト変数が優先されます
パラメータ名がコンテキスト変数（contact_id、conversation_id など）と同じ場合、必ずコンテキスト変数の値が代入されます。AI アシスタントが指定した値で上書きされることはありません
参照されたパラメータも個別に送信されます
テンプレートで参照されたパラメータも、従来の動作どおり独立した query パラメータとして一緒に送信されます（たとえば product_name=Chai も送信されます）。多くの API は余分なパラメータを無視します
パラメータ名はそのまま保持されます
Query パラメータのキーにアンダースコアや大文字が含まれる場合（Business_Accounting_NO など）も、そのまま保持され、システムによって書き換えられることはありません
{{ }} を含まない既存のツール設定には影響しません。古いツールの Query パラメータ名が以前システムによって書き換えられていた場合（たとえば Business_Accounting_NO が business__accounting_no になっている場合）は、ツールを開き直し、正しい名前に戻して保存してください。編集画面を開き直すと、Query パラメータの値は **** でマスク表示されますが、そのまま保存しても元の値は失われません。
⚠️ 重要な注意事項
接続テスト
ツールを作成したら、まず API が正常に動作するかテストすることをお勧めします
以下のようなテストツールを使って、ツールの機能を検証できます：
POSTMAN
企業が独自に構築した API リクエストのテストプラットフォーム
権限管理
ツールの利用状況とアクセス権限の設定状況を定期的に確認してください
最終更新
役に立ちましたか？