# AIアシスタントの接続 (MCP)

<span data-t="appName">Your AI Connector</span> は、**Claude Code**、**Claude Desktop**、**Cursor**、そして独自のアプリケーションといったAIアシスタントが、あなたの <span data-t="appName">Your AI Connector</span> アカウントを直接操作できるようにする、公式の **MCPサーバー**（Model Context Protocolエンドポイント）を提供しています。「AIエージェントをリストアップして」「このリードを追加して」「今週のAI利用料金はいくら？」といった自然言語で尋ねるだけで、アシスタントがあなたの代わりに <span data-t="appName">Your AI Connector</span> APIを呼び出します。

これは[APIキー](api-access.md)でアクセスするのと同じv1 APIであり、独自のAPIキーで認証されます。MCPサーバーは、公開されているAPI仕様の各操作に対して1つのツールを構築するため、v1 APIのほとんど（すべてではありません）をカバーしています。対象は、連絡先、メッセージ、キャンペーン、AIエージェント、カスタム関数、ナレッジベース、予約、分析、タグ、リスト、ブロードキャスト、取引、チャネル接続、およびサブアカウントです。自動化機能はMCPを通じて一覧表示や読み取りは可能ですが、作成や編集はまだできません。これらはアプリ内で構築してください。
公開されている範囲内では、ツールごとの権限設定やデフォルトの読み取り専用設定は存在しないため、APIキーがアクセス制御のすべてとなります。

- **エンドポイント:** `https://mcp.youraiconnector.com/mcp`
- **認証:** <span data-t="appName">Your AI Connector</span> APIキー（`X-API-Key`ヘッダーとして送信）
- **要件:** APIアクセス権のあるプラン。[APIキーを作成 →](api-access.md#generating-your-api-key)


> APIキーは**あなた自身のアカウント**に対して機能し、APIの他の部分と同じ権限を持ちます。エージェンシープランをご利用の場合は、管理しているクライアントアカウントも読み取ることができます（下記参照）。パスワードのように扱ってください。「設定」→「統合」→「APIキー」からいつでも取り消すことができ、その時点でアシスタントのアクセスは即座に遮断されます。

## Claude Code



```bash
claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"
```

次に、Claude Code内で`/mcp`を実行し、**ai-connector ✓ connected**と表示されることを確認します。

デフォルトでは、サーバーは**ローカル**スコープ（あなた自身、およびこのプロジェクトのみ）に追加されます。すべてのプロジェクトで利用可能にするには `--scope user` を使用し、チーム全体で利用するには `--scope project` to commit it to a repo's `.mcp.json` を使用してください。

```json
{
  "mcpServers": {
    "ai-connector": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

## Claude Desktop

サーバーをカスタムコネクタとして追加します。これはClaudeアカウントで設定されるため、Claude Desktopとclaude.aiの両方で機能します（無料のClaudeアカウントでも1つのカスタムコネクタを追加できます）。

1. **カスタマイズ → コネクタ**を開き、**+ 追加**をクリックしてから、**カスタムコネクタを追加**を選択します。
2. 名前を付け、URLとして `https://mcp.youraiconnector.com/mcp` を入力します。
3. **認証**で、**サインインなし**を選択します。MCPサーバーにはサインインページがないため、サインインオプションを選択すると「…サインインサービスに登録できませんでした」というエラーになります。
4. **リクエストヘッダー**で、`X-API-Key` という名前のヘッダーを追加し、値をAPIキーにします。
5. **追加**をクリックします。<span data-t="appName">Your AI Connector</span> ツールが新しいチャットのツールメニューに表示されます。

**「リクエストヘッダー」フィールドがありませんか？** Claude Desktopのバージョンが古い可能性があります。アップデートするか、代わりに設定ファイルを使用してください。設定ファイル（`claude_desktop_config.json`、設定 → 開発者 → 設定を編集）はコンピューター上のプログラムのみを実行し、`url` エントリを無視するため、小さな `mcp-remote` ブリッジが必要です。これには [Node.js](https://nodejs.org) 18以降が必要です。

```json
{
  "mcpServers": {
    "ai-connector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.youraiconnector.com/mcp",
        "--header",
        "X-API-Key:${AI_CONNECTOR_KEY}"
      ],
      "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" }
    }
  }
}
```

`X-API-Key:${AI_CONNECTOR_KEY}` はコロンの後にスペースを入れず（Windowsではスペースを入れるとヘッダーが分割されます）、そのまま記述してください。また、キーは `env` にのみ入力してください。その後、Claude Desktopを完全に終了し（Windowsの場合はトレイアイコンを右クリック → 終了）、再度開いてください。

## ChatGPT

ChatGPTは現在、MCPサーバーに接続できません。ChatGPTのカスタムコネクタフォームは **OAuth** または **認証なし** しか選択できず、<span data-t="appName">Your AI Connector</span> MCPサーバーはリクエストヘッダーとして送信されるAPIキーでサインインするためです。OAuthを選択すると「OAuth設定を検出できませんでした」というエラーになり、認証なしを選択するとすべてのリクエストにキーが必要なため拒否されます。

代わりに、リクエストヘッダーを設定できるアシスタントを使用してください：
[Claude Code](#claude-code)、[Claude Desktop](#claude-desktop)、
[Cursorまたはその他のMCPクライアント](#cursor--other-mcp-clients)、または
[Claude API](#the-claude-api-build-it-into-your-own-app)。

ChatGPTでも、接続なしでヘルプドキュメントを読むことは可能です。公開されている `llms.txt` ファイルについては、[ヘルプドキュメントは組み込み済みです](#the-help-docs-are-built-in) を参照してください。

## Cursorおよびその他のMCPクライアント

ほとんどのMCP対応エディタは、上記と同じ`.mcp.json`形式（`url`と`X-API-Key`ヘッダーを持つHTTPサーバー）を使用します。`https://mcp.youraiconnector.com/mcp`を指す`ai-connector`サーバーを追加し、ヘッダーにAPIキーを貼り付けてください。

## Claude API（独自のアプリへの組み込み）

Claude API の MCP コネクタを使用して、プログラムから MCP サーバーに接続することもできます。これにより、構築したエージェントが別のクライアントを介さずに <span data-t="appName">Your AI Connector</span> ツールを使用できるようになります：

```json
{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my AI agents" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "ai-connector",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}
```

## できること

MCP サーバーが公開する v1 API の範囲内で、アシスタントが適切なツールを自動的に選択します。

- **AI エージェント:** 一覧表示、作成、更新、一時停止/再開、設定の確認。
- **連絡先:** 検索、作成、タグ付け、リストへの追加、インポート。
- **ナレッジベース / FAQ:** 追加、編集、一括インポート、AI 提案の承認。
- **メッセージ:** 会話の読み取り、連絡先へのメッセージ送信。
- **予約:** 一覧表示、予約、キャンセル。
- **タスク:** 作成、完了、一覧表示。
- **分析:** メッセージ統計、クレジット使用量、AI コスト。
- **チャネル:** 接続状態の確認、接続フローの開始。

## クライアントのアカウントについて質問する（エージェンシー向け）

1つの接続ですべての管理アカウントをカバーします。クライアントごとに2つ目の接続を追加する必要はありません。エージェンシープランでは、アシスタントは配下のどのクライアントアカウントも読み取ることができるため、1つの会話ですべてのアカウントについて質問できます。

クライアント名を指定するだけです：

- 「Bella's Bistro には連絡先がいくつありますか？」
- 「今週、各クライアントの AI 利用料金はいくらでしたか？」
- 「Northside Dental のチャネルの状態はどうなっていますか？また、今週は何件のチャットがありましたか？」

これには、連絡先、メッセージ、チャット、キャンペーン、予約、タスク、タグ、イベント、FAQ、ナレッジベースのソース、電話番号、チャネル、Webhook、分析の読み取りが含まれます。実行前にそのアカウントが実際にあなたのものであることを確認します。あなたのものではないアカウントを要求した場合は「見つかりません」と返されます。クライアントを指定しない場合、アシスタントはこれまで通りあなた自身のアカウントを読み取ります。

**クライアントのアカウントの変更**も同様の手順で行えます。APIでクライアントアカウントを受け入れるすべてのアクションは、指定されたクライアントに対して利用可能です。これには、AIエージェント、ナレッジベース、カスタム関数、WhatsAppテンプレート、エントリーポイント、チャネル接続、連絡先、タグ、ブロードキャスト、予約、案件とタスクの設定、およびメッセージの送信が含まれます。例外となるのはエージェンシーレベルのアクションで、これらは常にあなた自身のエージェンシーアカウントで実行されます。具体的には、クライアントアカウント自体の管理（制限、機能、価格設定、一時停止）、スナップショット、チーム、およびAPIキーの管理です。クライアントのリストへの連絡先の追加や削除は、指定されたクライアントに対してはまだ利用できません。これらは、そのクライアント自身のキーを使用するか、クライアントのアカウント内で行ってください。サポートされている内容については、[エージェンシーAPIガイド](../agency/api-for-agencies.md#where-sub_account_id-is-supported)を参照してください。

::: neutral-mcp
エージェンシー向けツールは、標準の非ブランド化アドレス `https://mcp.youraiconnector.com/mcp` でのみ利用可能です。独自のドメイン（`mcp.youragency.com`）上のホワイトラベルMCPアドレスはクライアント向けに構築されており、エージェンシー向けツールは含まれていないため、クライアントアカウントを管理する際は標準の非ブランド化アドレスに接続してください。
:::

これは、**1つのログインで複数のビジネスを運営している**クライアントへの回答でもあります。各ビジネスに個別のカウントを与え、クライアントのメールアドレスをすべてのビジネスのチームメンバーとして招待してください。クライアントは一度サインインすれば、サイドバーのアカウントピッカーでブランドを切り替えることができます。

### クライアントのエージェントをテストする

アシスタントにクライアントのエージェントを試すよう依頼します（例：「クライアントXのBakeryエージェントに『日曜日は配達していますか？』と送信し、その結果を表示して」）。これにより、あなたのエージェンシーキーとクライアントの`sub_account_id`を使用して「試用（Try Out）」メッセージが送信され、待機した後に返信内容とエージェントが実行したアクションが読み取られます。エージェントのコピーは必要ありません。アシスタントがエージェンシーアカウントではないと回答した場合は、クライアントのキーで接続されている状態です。エージェンシーアカウントのキーで再接続してください。詳細は[試用（Try Out）](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant)を参照してください。

## ツール数に制限があるクライアント

::: neutral-mcp
一部のAIクライアントは、ツール数が制限されたサーバーのみを受け入れます。例えばComposioは、500個を超えるツールをリストするサーバーを拒否し、ツールを一切インポートしません。エージェンシーのフル接続ではそれ以上のツールがリストされるため、必要なツールグループのみを指定してアドレスに `?tags=` を追加してください。

クライアントアカウントのリスト表示、連絡先・チャット・メッセージの読み取り、およびメッセージ送信を行うエージェンシーの場合：

```
https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages
```

これにより約80個のツールが読み込まれます。リクエスト内でクライアント名を指定すると、前述の通り、アシスタントはそのクライアントのアカウントに対して操作を行います。

- グループはカンマで区切ってください。大文字と小文字のどちらでも機能します。
- 単一のツールを追加するには、`tools=` を使用して正確な名前をリストします（例: `?tags=Contacts&tools=list_or_get_subaccounts`）。どちらのリストからもすべてのツールを取得できます。
- ヘルプドキュメントのツールは常に含まれます。
- APIキーは常に `X-API-Key` ヘッダー（または `Authorization: Bearer YOUR_API_KEY`）に含める必要があり、アドレスには決して含めないでください。
:::

## ヘルプドキュメントは組み込み済みです

MCPサーバーは、アシスタントにあなたの **アカウント** 情報とこの **ドキュメント** を提供します。3つのツールがヘルプドキュメントをライブで読み取るため、アシスタントは推測する代わりに、機能の仕組みや最近の変更点を調べることができます：

- `docs_search`: 質問に対する回答となるセクションを見つけ、ページリンクと共に返します。
- `docs_read`: 1ページ全体、またはそのセクションを読み取ります。
- `docs_list`: エリアごとに全ページを一覧表示します。

セットアップは不要で、ドキュメントツールがアカウントデータに触れることはありません。「エントリーポイントはどのように機能しますか？」や「オートメーションの最新情報は？」と尋ねれば、アシスタントはまずドキュメントを検索します。ツールがヘルプサイト自体を読み取るため、ガイドが公開され次第、アシスタントはその機能を認識できるようになります。

MCP経由で接続されていないアシスタントでも、ドキュメントを読み取ることができます。`https://docs.youraiconnector.com/llms.txt`（各ページのMarkdown版へのリンクを含む全ヘルプページのインデックス）または `https://docs.youraiconnector.com/llms-full.txt`（ドキュメント全体をまとめた1つのMarkdownファイル）を指定してください。どちらも公開されており、キーは不要で、ドキュメントが更新されるたびに再構築されます。

## APIキーの検索または生成

この接続で使用するAPIキーは、Webhooksとは別のセクションである**「設定」→「統合」→「APIキー」**にあります。正確な手順については、[APIアクセス](api-access.md#generating-your-api-key)を参照してください。

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

- **「接続拒否」または「見つかりません」** — アドレスの末尾に `/mcp` がありません。`https://mcp.youraiconnector.com` ではなく `https://mcp.youraiconnector.com/mcp` を使用してください。
- **`Needs authentication` / 401** — APIキーが不足しているか、間違っています。有効な `X-API-Key` を使用してサーバーを再追加してください。
- **「OAuth設定を検出できませんでした」(ChatGPT)** — ChatGPTのカスタムコネクタはOAuthまたは認証なしのみをサポートしており、MCPサーバーはAPIキーを使用するため、現時点ではChatGPTは接続できません。[ChatGPT](#chatgpt) を参照してください。
- **「…サインインサービスに登録できませんでした」または「OAuthクライアントIDを追加してください」(Claude Desktop)** — カスタムコネクタがサインインオプション付きで追加されています。入力すべきOAuthクライアントIDはありません。コネクタを削除し、**認証 → サインインなし**を選択して、[Claude Desktop](#claude-desktop) のようにAPIキーを `X-API-Key` リクエストヘッダーとして追加し直してください。
- **設定ファイルを編集してもClaude Desktopにツールが表示されない** — 設定ファイルは `"url"` エントリを無視します。カスタムコネクタまたは [Claude Desktop](#claude-desktop) の `mcp-remote` フォームを使用し、アプリを完全に終了してから再起動してください。
- **ツールが `403` を返す** — プランまたはチームの役割でそのアクションが許可されていません。MCPサーバー側では追加の制限は設けておらず、APIと同じ権限チェックが行われます。
- **ツールが見つかりません** — ツールリストはAPIからライブで生成されるため、常に現在のバージョンと一致します。再接続して更新してください。
- **独自のドメインでセキュリティまたは証明書の警告が出る** — DNSレコードを向けるだけでは不十分です。安全な接続を提供するには、ダッシュボードでサブドメインも検証されている必要があります。ホワイトラベル代理店は、**設定 → ホワイトラベリング**の下にある **カスタムドメイン** カードから、MCPアドレスを独自のドメイン（例: `mcp.youragency.com`）に設定できます。まずレジストラでCNAMEを追加し、次に **MCPドメイン (AIアシスタント)** ブロックにホスト名を入力して **検証** をクリックします。これは他のブランドサブドメインと同じフローです。ブランド化されたアドレスには代理店用ツールは含まれません。それらについては、引き続き標準のブランド化されていないアドレスを使用してください。ブランド化されたアドレスが検証されるまでは、標準のブランド化されていないアドレスを使用してください。これはクライアントと共有しても安全です。

---

## 次のステップ

- [APIアクセス](api-access.md) — この接続で使用するキーの生成やローテーションを行います。
- [Webhooks](webhooks.md) — このプル型MCP接続に対するプッシュ型の対照機能です。