> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/ja/build/tools/mcp-setup.md).

# MCP ツールの作成

このガイドでは、プラットフォームで新しい MCP ツールを作成する手順を説明します。

## MCP とは？ <a href="#what-is-mcp" id="what-is-mcp"></a>

MCP（Model Context Protocol）は、AI と外部ツールを接続する標準プロトコルです。Agent は URL を通じてリモートの MCP サーバーに接続し、そのサービスが提供するツールを利用できます。

### **MCP ソリューション** <a href="#mcp-solution" id="mcp-solution"></a>

MCP サーバーを一度開発すれば、MCP に対応するすべての AI プラットフォームで利用できます。プロトコルの仕組み、MaiAgent が対応するトランスポート方式と制限については、技術マニュアルの [MCP（Model Context Protocol）](https://docs.maiagent.ai/tech/mcp/mcp-model-context-protocol)をご覧ください。

## MCP ツールをすばやく作成する <a href="#quick-create-mcp-tool" id="quick-create-mcp-tool"></a>

### 1. ツール管理画面を開く <a href="#step-1-enter-tool-management" id="step-1-enter-tool-management"></a>

まず、左側のメニューから <mark style="color:blue;">AI 機能</mark> → <mark style="color:blue;">ツール</mark>に移動します。ツール一覧ページで、右上の<mark style="color:blue;">ツールを追加</mark>ボタンをクリックします。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-804dd5ac3ff8177e6576f5a48ecf21d57dc3ee79%2Fmcp-tools-list.png?alt=media" alt="ツール一覧ページ。左側にツール一覧とコネクタ管理があり、右上にツールを追加ボタンがあります"><figcaption><p>「ツールを追加」をクリックして作成を始めます</p></figcaption></figure>

### 2. ツールの種類を選択する <a href="#step-2-select-tool-type" id="step-2-select-tool-type"></a>

ツールの種類は <mark style="color:blue;">MCP</mark> を選択します。

### 3. 表示名を設定する <a href="#step-3-set-display-name" id="step-3-set-display-name"></a>

ツールにわかりやすい表示名を設定します。ここでは <mark style="color:blue;">Composio mcp for google calendar</mark> とします。

* **用途**：この名前はプラットフォームの画面に表示され、すべてのユーザーが確認できます。
* **推奨事項**：ユーザーが理解しやすいように、ツールの主な機能が明確に伝わる名前を選んでください。名前の形式に厳密な制限はありません。

### 4. MCP 構成を入力する <a href="#step-4-configure-mcp" id="step-4-configure-mcp"></a>

MaiAgent は URL を通じてリモートの MCP サーバーに接続します（SSE および Streamable HTTP のストリーミングプロトコルに対応）。`npx` や `node` などのローカルコマンドで起動する MCP サーバーには対応していません。そのため、「<mark style="color:blue;">MCP 構成</mark>」ではサーバーの URL と認証方式のみを設定します。サーバーが必要とするキーは、すべてヘッダーまたは OAuth 認可を通じて提供します。

まず MCP サーバーの認証方式を確認し、以下の表に従って設定してください。

| サーバーの認証方式                               | 設定方法                                                                                                                                                                   |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth ログイン（ユーザーが相手のサービスにログインし、認可に同意します） | 「<mark style="color:blue;">接続するサービスを選択</mark>」でコネクタを選択します。[b. OAuth コネクタと認可対象](#oauth-connector)をご覧ください                                                                |
| 固定の API Key または Token（組織全体で共有）、または認証不要  | 「<mark style="color:blue;">または直接入力（認証なし / Service Account）</mark>」の下に URL を入力します。[a. MCP サーバーの URL](#mcp-server-url)をご覧ください。キーは [c. ヘッダー (JSON)](#mcp-headers) に入力します  |
| 各連絡先が自分の API Key または Token を使用します       | 上の行の手順でツールを作成し、連絡先の「<mark style="color:blue;">MCP 認証情報</mark>」タブで設定します。[連絡先の MCP 認証情報設定](/maiagent-user-guide/ja/build/tools/setup-contacts-mcp-credentials.md)をご覧ください |

#### a. 🔗MCP サーバーの URL <a href="#mcp-server-url" id="mcp-server-url"></a>

* **用途**：Agent がこの URL を通じて MCP サーバーに接続し、サーバーが提供するツールを取得して呼び出します。
* **入力場所**：
  * サーバーが OAuth を使用する場合：「<mark style="color:blue;">接続するサービスを選択</mark>」でコネクタのカードをクリックすると、URL が自動入力されます。以下の [b. OAuth コネクタと認可対象](#oauth-connector)をご覧ください。
  * サーバーが認証不要、または固定キーを使用する場合：「<mark style="color:blue;">または直接入力（認証なし / Service Account）</mark>」の下の入力欄に、`https://mcp.example.com/mcp` のような完全な URL を貼り付けます。
* **形式**：`https://` で始まり、インターネットから接続可能なリモートサーバーのアドレスである必要があります。`localhost` や内部ネットワークのアドレスは保存できません。オンプレミス環境で内部ネットワークの MCP サーバーに接続する必要がある場合は、MaiAgent に接続の有効化をご相談ください。
* **注意**：この項目は必須です。

{% hint style="info" %}
MCP の URL の取得方法については、[技術マニュアル—Remote MCP サービスの概要](https://docs.maiagent.ai/tech/mcp/remote-mcp)をご覧ください。
{% endhint %}

{% hint style="info" %}
MCP サーバーが「現在の会話のユーザー」を識別する必要がある場合：訪問者が Keycloak で Web Chat にログインしていれば、対話プラットフォームで [Keycloak のログイン情報を引き継いでツールを呼び出す](/maiagent-user-guide/ja/build/choose-channel/web-chat.md#keycloak-token-passthrough)を有効にし、この MCP サーバーのホストを許可リストに追加できます。プラットフォームは、訪問者本人の Keycloak 認証情報を `Authorization` ヘッダーに付加します。
{% endhint %}

URL を直接入力するツールでは、「<mark style="color:blue;">許可するツール (JSON 配列)</mark>」でツール一覧を取得する際に、URL と「<mark style="color:blue;">ヘッダー (JSON)</mark>」を使ってサーバーに接続します。接続に失敗すると、「<mark style="color:blue;">MCP サーバーが HTTP 405 を返しました。URL が MCP エンドポイントを指しているか確認してください。</mark>」などの理由が表示されます。表示内容に従って URL とヘッダーを確認してください。保存時にも接続を再検証し、失敗すると「<mark style="color:blue;">MCP ツールの検証に失敗しました。MCP サーバーに接続できません</mark>」と表示されます。OAuth コネクタを使用するツールは先に保存され、認可が完了してからツール一覧を取得します。

#### b. 🔐 OAuth コネクタと認可対象 <a href="#oauth-connector" id="oauth-connector"></a>

MCP サーバーが OAuth を使用する場合、MaiAgent が認可フローを処理し、呼び出し時にアクセストークンを自動で付加します。ヘッダーにキーを入力する必要はありません。

{% stepper %}
{% step %}

### コネクタを選択する <a href="#oauth-select-connector" id="oauth-select-connector"></a>

「<mark style="color:blue;">接続するサービスを選択</mark>」で、接続したいサービスのカード（<mark style="color:blue;">OAuth 2.0</mark> と表示されています）をクリックすると、サーバーの URL が自動入力されます。一覧には、プラットフォームで検証済みのサービスと、組織が作成したカスタムコネクタが含まれます。
{% endstep %}

{% step %}

### サービスが見つからない場合はカスタムコネクタを作成する <a href="#oauth-custom-connector" id="oauth-custom-connector"></a>

最後のカード「<mark style="color:blue;">カスタムコネクタソース</mark>」をクリックし、以下の項目を入力して「<mark style="color:blue;">コネクタを追加</mark>」をクリックします。システムはまずサーバーへの接続をテストします。成功するとカード一覧に戻り、新しいコネクタが自動選択されます。

| 項目                                                   | 必須  | 説明                                                                                                                                                                   |
| ---------------------------------------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">名前</mark>                  | はい  | コネクタの識別名です。使用できるのは英字、数字、アンダースコア、ハイフンのみです。例：`my-mcp-server`                                                                                                           |
| <mark style="color:blue;">表示名</mark>                 | いいえ | カードに表示される名前です                                                                                                                                                        |
| <mark style="color:blue;">説明</mark>                  | いいえ | この MCP サーバーの用途を簡潔に説明します                                                                                                                                              |
| <mark style="color:blue;">ツールカテゴリ</mark>             | いいえ | このサーバーのツールに個別のカテゴリが設定されていない場合に適用される既定のカテゴリです。会話中のツールカードに表示される文言に影響します                                                                                                |
| <mark style="color:blue;">Logo</mark>                | いいえ | カードのアイコンです                                                                                                                                                           |
| <mark style="color:blue;">サーバー URL</mark>            | はい  | MCP サーバーの URL です。`https://` を使用する必要があります                                                                                                                             |
| <mark style="color:blue;">OAuth サーバー URL</mark>      | いいえ | 認可サーバーの URL です。空欄の場合、MCP サーバーが公開する情報から自動検出します。自動検出に失敗した場合、または認可サーバーと MCP サーバーのドメインが異なる場合のみ入力します（例：Supabase の MCP は `mcp.supabase.com`、認可サーバーは `api.supabase.com` です） |
| <mark style="color:blue;">Resource Identifier</mark> | いいえ | 認可サーバーにトークンを要求するときに指定するリソース識別子です。空欄の場合は自動検出します。検出に失敗した場合、またはサーバーの公開情報が誤っている場合のみ入力します（例：Asana では `https://mcp.asana.com` です）                                          |
| <mark style="color:blue;">OAuth Client ID</mark>     | いいえ | サーバーがクライアントの自動登録に対応している場合は空欄にします。対応していない場合は、まず相手の OAuth サービスでアプリケーションを作成し、取得した Client ID をここに入力します                                                                   |
| <mark style="color:blue;">OAuth Client Secret</mark> | いいえ | Client ID と組み合わせて使用します。相手のサービスが機密クライアント（confidential client）を要求する場合のみ入力します。設定済みの場合はマスク表示されます。空欄にすると既存の値を保持し、新しい値を入力すると上書きします                                         |

作成したコネクタは、「<mark style="color:blue;">ツール</mark>」ページの「<mark style="color:blue;">コネクタ管理</mark>」から変更または削除できます。「サーバー URL」を変更すると、そのコネクタを使用するツールの認可が失われるため、慎重に変更してください。
{% endstep %}

{% step %}

### 認可対象を選択する <a href="#oauth-auth-subject" id="oauth-auth-subject"></a>

コネクタを選択したら、「<mark style="color:blue;">認可対象</mark>」で、Agent が誰のアカウントを使ってこのサービスを操作するかを選択します。

| 認可対象                                      | 説明                                                                                                                                        |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">組織で共有</mark>    | 管理者またはメンバーが一度認可し、組織全体で同じ認可を共有します。その後、この Agent を利用するすべてのユーザー（LINE、Web Chat など）は、認可した人のアカウントでサービスにアクセスします。各自のアカウントを使うべき個人向けサービスでは選択しないでください |
| <mark style="color:blue;">連絡先ごとに認可</mark> | 各連絡先が会話中にそれぞれログインして認可し、Agent はその連絡先本人として操作します。ログイン済みのユーザーが対象です。未ログインの匿名訪問者との会話では、Agent にこのツールは提供されません                                     |
| {% endstep %}                             |                                                                                                                                           |

{% step %}

### 認可を完了する <a href="#oauth-authorize" id="oauth-authorize"></a>

* **組織で共有**：「<mark style="color:blue;">認可へ進む</mark>」をクリックします。ツールが未保存の場合は先に保存され、その後、相手のサービスの認可ウィンドウが開きます。ログインして同意すると、画面に「<mark style="color:blue;">認可済み</mark>」と表示されます。ツール一覧が自動で取得・保存され、編集ウィンドウが閉じます。別のアカウントに切り替える場合は、ツールを再度開き、「<mark style="color:blue;">認可を取り消す</mark>」をクリックしてから再認可してください。
* **連絡先ごとに認可**：ここで認可する必要はありません。各連絡先が会話中にそれぞれログインして認可します。認可の状態は、「<mark style="color:blue;">連絡先</mark>」の編集ウィンドウにある「<mark style="color:blue;">Connector 認可</mark>」タブで確認でき、取り消しや再認可の開始も行えます。

{% hint style="warning" %}
認可ウィンドウはポップアップで開きます。「<mark style="color:blue;">ポップアップがブロックされました。ポップアップを許可してから再試行してください</mark>」と表示された場合は、ブラウザーでこのサイトのポップアップを許可し、もう一度「認可へ進む」をクリックしてください。
{% endhint %}
{% endstep %}
{% endstepper %}

#### c. 📰 ヘッダー (JSON) <a href="#mcp-headers" id="mcp-headers"></a>

* **用途**：MCP サーバーへの接続時に毎回付加する HTTP ヘッダーを設定します。固定の API Key や Token などを指定できます。
* **形式**：有効な JSON オブジェクトです。キー（Key）はヘッダー名、値（Value）はヘッダーの内容（文字列）です。不要な場合は `{}` のままにします。
* **URL を直接入力する場合**：サーバーが要求する認証ヘッダーをここに入力します。キーには実際の値を入力してください。

  ```json
  {
    "Authorization": "Bearer サービス提供元から取得した Token をここに貼り付けます"
  }
  ```
* **OAuth コネクタを選択した場合**：認証は自動で処理されるため、ここには追加のカスタムヘッダーのみを必要に応じて入力します。認可対象が「組織で共有」の場合、`Authorization` は入力しないでください。自動付加される認可情報が上書きされます。
* **共有の認証情報と個別の認証情報**：ここのヘッダーはすべての会話で共有されます。各連絡先が自分のキーを使用する場合は、[連絡先の MCP 認証情報](/maiagent-user-guide/ja/build/tools/setup-contacts-mcp-credentials.md)で連絡先ごとに設定してください。呼び出し時に同名のヘッダーがある場合は、連絡先の設定が優先されます。
* **使用可能な変数**：値には、項目の下にある「<mark style="color:blue;">使用可能なコンテキスト変数</mark>」に表示された変数（例：`{{contact_id}}`、`{{conversation_id}}`）を使用できます。システムが会話ごとに実際の値に置き換えます。それ以外の `{{…}}` という名前は置換されず、保存時に「<mark style="color:blue;">不明なテンプレート変数が含まれています</mark>」というエラーになります。キーを独自の変数で置き換えることはできないため、実際の値を入力してください。
* **閲覧できる情報**：保存後に編集ウィンドウを再度開くと、各ヘッダー値は先頭と末尾の各 4 文字だけが表示され、中間は `****` に置き換わります。そのまま保存しても元の値は変わりません。ヘッダーは AI モデルに渡されず、MCP ツールの実行ログにもリクエストヘッダーは保存されません。

### 5. 「<mark style="color:blue;">許可するツール (JSON 配列)</mark>」で「再取得」をクリックする <a href="#step-5-fetch-allowed-tools" id="step-5-fetch-allowed-tools"></a>

* **用途**：この MCP クライアントで Agent が使用を許可される個別のツール一覧を指定します。1 つの MCP クライアントが複数の機能や個別のツールを提供する場合があります。
* **ツールの取得と選択**：「<mark style="color:blue;">再取得</mark>」をクリックします（まだ取得していない場合は、一覧内の「<mark style="color:blue;">ツールを取得</mark>」も使用できます）。現在のサーバー URL とヘッダーで接続し、サーバーが提供するすべてのツールを一覧表示します。各ツールの右側にあるスイッチで、Agent が使用できるツールを選択します。「<mark style="color:blue;">すべて有効</mark>」「<mark style="color:blue;">すべて無効</mark>」で一括切り替えもできます。保存前に少なくとも 1 つのツールを有効にする必要があります。
* **OAuth コネクタ**：認可対象が「組織で共有」の場合、認可完了後にツール一覧が自動で取得・保存されます。

クリックすると、そのサーバーに紐づくツールの内容が自動取得され、一覧に表示されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-a71a8d1d54f524bfea21124d1732678c1956b626%2Fmcp-allowed-tools.png?alt=media" alt="ツール編集ウィンドウの許可するツール (JSON 配列) セクション。3 / 3 個のツールが有効と表示され、すべて有効・すべて無効ボタンと、各ツールの右側のスイッチがあります。上部のヘッダー (JSON) の値は **** でマスクされています"><figcaption><p>ツール一覧を取得したら、各ツールの右側のスイッチで Agent が使用できるツールを選択します</p></figcaption></figure>

### 6. 💾 ツールを保存する <a href="#step-6-save-tool" id="step-6-save-tool"></a>

すべての設定に誤りがないことを確認したら、ページ下部までスクロールし、「<mark style="color:blue;">確認</mark>」ボタンをクリックします。これで新しいツールの作成が完了します。

ツールを追加する際に、<mark style="color:blue;">権限設定</mark>タブを一度も開かずに<mark style="color:blue;">確認</mark>をクリックすると、その時点ではツールは作成されません。画面が自動で<mark style="color:blue;">権限設定</mark>に切り替わり、「まず権限設定を確認し、割り当てられたロールを確認してから送信してください」と表示されます。<mark style="color:blue;">権限範囲のクイック選択</mark>で、このツールを使用できるメンバーのロールを確認してください（既定は<mark style="color:blue;">既定のロールを除外</mark>です）。もう一度<mark style="color:blue;">確認</mark>をクリックすると作成できます。組織で共有する OAuth ツールで「<mark style="color:blue;">認可へ進む</mark>」をクリックした場合も、この確認が先に行われます。既存のツールを編集する場合、この確認は表示されません。

MCP サーバーがツールにインタラクティブな UI を提供している場合、Agent がツールを呼び出すと、会話に直接操作できるカードが表示されます。追加の設定は不要です。[MCP インタラクティブカード（MCP Apps）](/maiagent-user-guide/ja/build/tools/mcp-apps.md)をご覧ください。

## ⚠️ 重要な注意事項 <a href="#important-notes" id="important-notes"></a>

**接続テスト**

* ツールの作成後は、MCP 接続が正常に動作するか、まずテストすることをおすすめします
* テスト環境でツールの機能を検証できます

**権限管理**

* 不要な機能まで許可しないよう、使用を許可するツールを慎重に選択してください
* ツールの利用状況を定期的に確認してください

**トラブルシューティング**

* 接続に失敗した場合は、MCP サーバーの URL が正しいか確認してください
* 「ヘッダー (JSON)」が有効な JSON オブジェクトで、キーに実際の値が入力されていることを確認してください
* OAuth コネクタ（組織で共有）を使用する場合は、ツールに「<mark style="color:blue;">認可済み</mark>」と表示されていることを確認してください


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/build/tools/mcp-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.