> 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/tech/ja/mcp/maiagent-mcp.md). # MaiAgent MCP：外部 AI ツールからプラットフォームを操作する MaiAgent MCP を通じて Claude や Cursor などの MCP 対応 AI ツールからプラットフォームを操作する方法：サービスエンドポイントと提供ツール、API Key と OAuth による接続、検証とトラブルシューティング 本ページは、Claude Code、Claude Desktop、Cursor などの AI ツールから MaiAgent MCP を通じてプラットフォームを操作したい開発者向けです。サービスエンドポイントと提供ツール、API Key と OAuth による接続設定、接続の検証とトラブルシューティングを説明します。MCP 自体の概念については、[MCP（Model Context Protocol）](/tech/ja/mcp/mcp-model-context-protocol.md)をご覧ください。 ## 1. MaiAgent MCP とは？ MaiAgent MCP は、MaiAgent が公式に提供するリモート [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) サービスです。Claude Code、Claude Desktop、Cursor などの MCP 対応 AI ツールに追加すると、自然言語で MaiAgent プラットフォームを直接操作できます。例えば、次のように指示できます。 * 「Claude Sonnet モデルを使って、カスタマーサポート用の Agent を作成してください」 * 「組織内のすべてのナレッジベースを一覧表示し、この FAQ を製品ナレッジベースにアップロードしてください」 * 「昨日の会話履歴を確認し、ユーザーからよく寄せられる質問をまとめてください」 | 項目 | 説明 | | --------------- | -------------------------------------------------------------------------- | | **サービスエンドポイント** | `https://mcp.maiagent.ai/mcp` | | **通信方式** | Streamable HTTP（リモート接続のため、ローカルにソフトウェアをインストールする必要はありません） | | **認証方式** | API Key（HTTP ヘッダーに設定）、または OAuth 2.1（メンバーがブラウザーで MaiAgent にログインして認可します） | | **対応範囲** | MaiAgent プラットフォームの全 API：Agent、ナレッジベース、会話、ツール、組織管理など、300 以上のエンドポイントに対応しています | ### 提供ツール 接続に成功すると、AI ツールで次の 6 つのツールを利用できます。AI がこれらを自動的に組み合わせて使用します（API の検索、仕様の確認、実行の順）。API の詳細を覚える必要はありません。 | ツール | 用途 | | --------------------- | --------------------------------------------------------------------- | | `debug_auth` | 認証状態が正しいかを確認します | | `list_api_categories` | すべての API カテゴリを一覧表示します | | `search_apis` | カテゴリやキーワードで API エンドポイントを検索します | | `get_api_details` | 特定の API の完全な仕様（パラメーター、リクエストボディ、レスポンス形式）を取得します | | `call_api` | API 呼び出しを実行します | | `refresh_schema` | API 一覧を強制的に再読み込みします（公開されたばかりの API が見つからない場合に使用します。通常は 5 分ごとに自動更新されます） | #### ツールの入力形式 | ツール | 入力フィールド | 説明 | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `debug_auth`、`list_api_categories`、`refresh_schema` | なし | — | | `search_apis` | `category`（string、任意）、`search`（string、任意）、`limit`（number、任意、デフォルト 20） | `search` にはスペース区切りで複数の語句を指定できます。すべての語句が一致する必要があります。一致したエンドポイントと `operation_id` を返します | | `get_api_details` | `operation_id`（string、必須） | エンドポイントのパス、メソッド、パラメーター、リクエストとレスポンスの構造を返します | | `call_api` | `operation_id`（string、必須）、`path_params`（object、任意）、`query_params`（object、任意）、`body`（object、任意） | 呼び出しを実行します。3 つのオブジェクトはすべて「名前→値」のフラットなオブジェクトです | `call_api` のルールは次のとおりです。 * `operation_id` は、API ドキュメントの各エンドポイントに記載されている operationId です。例：`v1KnowledgeBasesFilesList`。 * `path_params` のキーは、パス内の `{…}` の名前（例：`knowledgeBasePk`）に対応します。値は URL エンコードされてから代入されます。パスパラメーターが不足している場合、呼び出しは失敗し、リクエストは送信されません。 * `query_params` はそのままクエリ文字列になります。`body` は JSON として送信され、`POST`／`PUT`／`PATCH` の場合のみ必要です。 * 認証には接続時の API Key または OAuth トークンを使用します。パラメーターにキーを含める必要はありません。権限はそのメンバーのロールと同じです。 * レスポンスが 50,000 bytes を超える場合は切り詰められ、その旨が表示されます。ページネーションのパラメーターやフィルターで結果を絞り込んでください。 * API が返すエラー（`400`、`403`、`404` など）は、そのまま AI に返されます。内容の形式については、[API 共通規約：エラーレスポンス](https://docs.maiagent.ai/api/preparation/conventions#errors)をご覧ください。 例えば「特定のナレッジベースの PDF ファイルを一覧表示する」場合、AI は次の順序で呼び出します。 ```json // 1. search_apis {"search": "knowledge base files", "limit": 5} // 2. get_api_details {"operation_id": "v1KnowledgeBasesFilesList"} // 3. call_api { "operation_id": "v1KnowledgeBasesFilesList", "path_params": {"knowledgeBasePk": "550e8400-e29b-41d4-a716-446655440000"}, "query_params": {"fileType": "pdf", "pageSize": 20} } ``` {% hint style="info" %} **接続の方向にご注意ください**：本ページでは「MaiAgent を**外部** AI ツールに接続する方法」を説明しています。逆に、MaiAgent の Agent に他の MCP ツールを追加したい場合、管理画面での操作はユーザーマニュアルの [MCP ツールの作成](https://docs.maiagent.ai/build/tools/mcp-setup)をご覧ください。自社システムを MCP Server として提供するための仕様は、[セルフホスト MCP Server 接続仕様](/tech/ja/mcp/self-hosted-mcp-server.md)をご覧ください。 {% endhint %} *** ## 2. 事前準備 まず、使用する認証方式を選んでください。 | 認証方式 | 対象 | 必要なもの | | ----------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- | | **API Key** | 個人や自動化スクリプト向けです。カスタムヘッダーに対応するすべての MCP クライアントで使用できます | API Key が必要です。下記の [API Key の取得](#get-api-key)をご覧ください | | **OAuth** | 複数のメンバーが自分のアカウントで接続する場合に適しています。設定ファイルにキーを貼り付ける必要はありません | 管理者が事前に OAuth アプリケーションを作成する必要があります。下記の [OAuth アプリケーションの準備](#prepare-oauth-app)をご覧ください | どちらの方式でも、操作権限はメンバー自身のロールの権限と同じです。 {% hint style="warning" %} API Key は「**キー作成時に選択されていた組織**」に紐づきます。MCP のすべての操作は、この組織に対して実行されます。複数の組織に所属している場合は、管理画面の左上で操作対象の組織に切り替えてからキーを作成してください。各メンバーは複数のキーを持つことができます。管理方法については、ユーザーマニュアルの [API Key 管理](https://docs.maiagent.ai/org/developer/api-keys)をご覧ください。 {% endhint %} ### API Key の取得 [MaiAgent 管理画面](https://admin.maiagent.ai)にログインし、右上のアバターをクリック → アカウント → API キータブに切り替え → キーを作成をクリックして、生成された API Key をコピーしてください。 詳しくは、ユーザーマニュアルの [個人アカウント設定：API キー](https://docs.maiagent.ai/start/profile#api-keys)をご覧ください。管理者がメンバーの代理でキーを発行する方法は、[API Key 管理](https://docs.maiagent.ai/org/developer/api-keys#create-api-key)をご覧ください。 {% hint style="danger" %} API Key は作成後に一度だけ表示されます。すぐにコピーして安全に保管してください。API Key はご自身のログイン資格情報と同等です。他の人と共有したり、バージョン管理（git）にコミットしたりしないでください。 {% endhint %} ### OAuth アプリケーションの準備 OAuth で接続する前に、「OAuth アプリケーション管理権限」を持つ管理者が組織内にアプリケーションを作成する必要があります。 1. 組織設定 → 組織概要 → 管理操作 → OAuth アプリケーションに移動し、アプリケーションを作成をクリックします。 2. アプリケーションの種類で Public を選択します。 3. Redirect URIs に、MCP クライアントの認可完了後にリダイレクトする URL を入力します。クライアントが実際に使用する URL と完全に一致する必要があります。例えば Claude のウェブ版では `https://claude.ai/api/mcp/auth_callback` です。Claude Code については、下記の [OAuth で接続する](#setup-oauth)をご覧ください。 4. 作成後、接続するメンバーに Client ID を渡します。 詳しい手順は、ユーザーマニュアルの [OAuth アプリケーション](https://docs.maiagent.ai/org/developer/oauth-applications#create-application)をご覧ください。 {% hint style="warning" %} * OAuth で接続する場合、操作対象は**アプリケーションが所属する組織**です。別の組織を操作するには、その組織で作成されたアプリケーションを使用してください。 * 認可ページでは Email とパスワードによるログインのみ利用できます。SSO のみでログインし、ログインパスワードを持たないメンバーは認可を完了できません。API Key を使用してください。[SSO のみでログインするメンバー](https://docs.maiagent.ai/org/developer/oauth-applications#sso-only-members)をご覧ください。 {% endhint %} *** ## 3. 接続設定 使用する AI ツールに応じた設定方法を選んでください。以下の例では API Key を使用します。`` を事前準備で取得した API Key に置き換えてください。OAuth を使用する場合は、[OAuth で接続する](#setup-oauth)をご覧ください。 {% tabs %} {% tab title="Claude Code" %} ターミナルで次のコマンドを実行します。 ```bash claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \ -s user \ --header "Authorization: Api-Key " ``` `-s user` を指定すると、すべてのプロジェクトで使用できます。現在のプロジェクトだけで使用する場合は、`-s project` に変更してください（設定はプロジェクトのルートディレクトリの `.mcp.json` に書き込まれます）。 `.mcp.json` を直接手動で編集することもできます。 ```json { "mcpServers": { "maiagent": { "type": "http", "url": "https://mcp.maiagent.ai/mcp", "headers": { "Authorization": "Api-Key " } } } } ``` {% hint style="warning" %} `-s project` を使用すると、Claude Code の初回起動時に、このプロジェクトの MCP server を信頼するか確認されます。同意してください。`.mcp.json` があるディレクトリが git プロジェクトの場合は、API Key のコミットを防ぐため、`.mcp.json` を `.gitignore` に追加してください。 {% endhint %} {% endtab %} {% tab title="Claude Desktop" %} Claude Desktop の設定ファイル（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`、Windows：`%APPDATA%\Claude\claude_desktop_config.json`）を編集し、次を追加します。 ```json { "mcpServers": { "maiagent": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.maiagent.ai/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Api-Key " } } } } ``` 保存後、Claude Desktop を再起動してください。 {% hint style="info" %} この方法では、ローカルに [Node.js](https://nodejs.org/) がインストールされている必要があります。`Authorization` の値を `env` 経由で渡すのは、設定ファイル内のスペースを含む引数が誤って分割されるのを防ぐためです。 {% endhint %} {% endtab %} {% tab title="Cursor" %} `~/.cursor/mcp.json`（グローバル）またはプロジェクト内の `.cursor/mcp.json` を編集し、次を追加します。 ```json { "mcpServers": { "maiagent": { "url": "https://mcp.maiagent.ai/mcp", "headers": { "Authorization": "Api-Key " } } } } ``` 保存後、Cursor Settings → MCP に移動し、`maiagent` が接続済みと表示されていることを確認してください。 {% endtab %} {% tab title="その他の MCP ツール" %} **Streamable HTTP** によるリモート接続に対応するすべての MCP クライアントで使用できます。主な設定は次のとおりです。 | 設定項目 | 値 | | ---------------------- | ----------------------------- | | Server URL | `https://mcp.maiagent.ai/mcp` | | Transport | Streamable HTTP | | Header：`Authorization` | `Api-Key ` | | {% endtab %} | | | {% endtabs %} | | ### OAuth で接続する OAuth で接続する場合、設定に `Authorization` ヘッダーを**含めないでください**。初回接続時に、MCP クライアントは MaiAgent MCP から認可を求めるレスポンスを受け取り、ブラウザーを開いて MaiAgent へのログインを促します。認可ページにはアプリケーション名、所属組織、現在ログインしているアカウントが表示されます。確認後に「認可」をクリックすると完了です。その後はクライアントが自動的に更新するため、毎回ログインする必要はありません。 MaiAgent は動的クライアント登録に対応していません。MCP クライアントは、事前に作成された Client ID を入力できる必要があります。 {% tabs %} {% tab title="Claude Code" %} ターミナルで次のコマンドを実行します（`8765` は任意の固定ポートに変更できます）。 ```bash claude mcp add --transport http maiagent https://mcp.maiagent.ai/mcp \ -s user \ --client-id \ --callback-port 8765 ``` OAuth アプリケーションの Redirect URIs に `http://localhost:8765/callback` を登録してください。ポートは `--callback-port` と一致する必要があります。 設定後、Claude Code で `/mcp` を入力し、`maiagent` を選択して、案内に従ってブラウザーでの認可を完了してください。 {% endtab %} {% tab title="Claude（ウェブ版／Desktop）" %} Claude のコネクタ設定でカスタムコネクタを追加します。URL に `https://mcp.maiagent.ai/mcp` を入力し、詳細設定に OAuth Client ID を入力して、案内に従って接続と認可を完了してください。 OAuth アプリケーションの Redirect URIs に `https://claude.ai/api/mcp/auth_callback` を登録してください。 {% endtab %} {% tab title="その他の MCP ツール" %} クライアントは MCP の OAuth 認可（認可コード＋PKCE）に対応し、事前登録された Client ID を入力できる必要があります。 | 設定項目 | 値 | | --------------- | ------------------------------------------------------ | | Server URL | `https://mcp.maiagent.ai/mcp` | | Transport | Streamable HTTP | | OAuth Client ID | OAuth アプリケーションの Client ID です | | Redirect URI | クライアントが実際に使用するコールバック URL です。OAuth アプリケーションに登録する必要があります | 認可サーバーのエンドポイントとプロトコルの詳細については、[OAuth 2.1 認可サーバーとしての MaiAgent](/tech/ja/identity-and-access/maiagent-oauth-server.md)をご覧ください。 {% endtab %} {% endtabs %} *** ## 4. 接続の検証 設定後、AI ツールで AI に `debug_auth` ツールの呼び出しを依頼してください（例えば「maiagent の debug\_auth ツールを呼び出して接続を確認してください」と入力します）。次のような結果が表示されます。 ```json { "has_auth_header": true, "auth_header_preview": "Api-Key xxxxxxxx...", "has_organization_id": false, "organization_id": null } ``` `has_auth_header` が `true` であれば、設定した認証情報が送信されています。OAuth で接続している場合、`auth_header_preview` は `Bearer` で始まります。`organization_id` が `null` と表示されるのは正常です。操作対象の組織は API Key、または OAuth アプリケーションが所属する組織によって決まります。実際に呼び出しが成功するかは、続けて AI にクエリの実行（例：「すべての Agent を一覧表示してください」）を依頼して確認できます。 *** ## 5. 利用を開始する 接続に成功したら、自然言語で直接指示できます。AI は `search_apis` → `get_api_details` → `call_api` の流れで、対応する API を自動的に見つけて実行します。便利な指示の例を紹介します。 * **照会**：「すべての Agent を一覧表示してください」「この組織にはどのようなメンバーがいますか？」 * **作成**：「『製品サポート』という名前の Agent を作成してください。ロールの指示は……」 * **ナレッジベース**：「新しいナレッジベースを作成し、現在のファイルを一覧表示してください」 * **運用**：「『製品サポート』Agent の最近の会話を確認し、よくある質問をまとめてください」 {% hint style="warning" %} MCP を通じて実行する操作は、管理画面での手動操作と**同じ効力を持ちます**（権限はご自身のアカウントと同じです）。削除や変更などを行う前に、AI に実行予定の操作内容を説明してもらうことをお勧めします。 {% endhint %} *** ## 6. トラブルシューティング | 症状 | 考えられる原因と対処方法 | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API 呼び出しで **401** が返されます | API Key が誤っているか、失効または無効化されています。形式が `Api-Key ` であることを確認してください（`Api-Key` とキーの間にスペースが 1 つ必要です）。 | | API Key を使用しているのに、クライアントがログインを要求したり、認証が必要と表示したりします | 設定から `Authorization` ヘッダーが送信されていないため、MaiAgent MCP がクライアントに OAuth の使用を求めています。ヘッダーの設定方法を確認してください。OAuth を使う場合は、[OAuth で接続する](#setup-oauth)に従って Client ID を設定してください。 | | OAuth 認可時に Redirect URI の不一致が表示されます | クライアントのコールバック URL と OAuth アプリケーションに登録された URL が一致していません。スキーム、ホスト、ポート、パスが完全に一致していることを確認してください。 | | OAuth の認可ページでログインできません | 認可ページでは Email とパスワードによるログインのみ利用できます。SSO のみでログインするアカウントは API Key を使用してください。 | | 誤った組織を操作しています（想定した Agent／ナレッジベースが見つかりません） | API Key は「キー作成時に選択されていた組織」に紐づきます。正しい組織に切り替えてキーを再作成し、設定ファイルを更新してください。OAuth ではアプリケーションが所属する組織を操作するため、正しい組織の Client ID を使用してください。 | | ツール一覧が空です | 接続が正常に確立されていません。AI ツールを再起動してください。Claude Code では `/mcp` コマンドで接続状態を確認できます。 | | Claude Code に `Pending approval` と表示されます | プロジェクトレベル（`-s project`）の MCP は、接続する前に信頼を承認する必要があります。対話モードの Claude Code を起動し、案内に従って同意してください。 | | API の実行時に権限エラーが発生します | `call_api` はご自身の認証情報で実行され、アカウントにアクセス権限があるリソースのみ操作できます。その組織でのロールの権限を確認してください。 | {% hint style="info" %} 専用デプロイ（On-Premise）環境を使用している場合、MCP サービスエンドポイントはクラウド版と異なります。MaiAgent のサービス担当者にお問い合わせください。 {% endhint %} --- # 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/tech/ja/mcp/maiagent-mcp.md?ask=&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.