注意
Fin Agent APIのMCPサーバーは現在ベータ版であり、正式リリース前に大幅に変更される可能性があります。ご意見をお待ちしており、今後の製品機能の指針に役立てます。
Fin Agent APIはリモートのModel Context Protocol (MCP)サーバーを公開し、外部のAIエージェントがFinをツールとして呼び出せるようにします。独自のエージェントでサポートロジックを再構築する代わりに、Claude、Claude Code、Cursor、または独自のエージェントフレームワークなど、MCP対応クライアントから直接Finのknowledge base、手順、マルチターン会話機能を利用できます。
接続方法はクライアントが誰として動作するかによって2つあります。
| チームメイト | エンドユーザー |
URL | ||
認証 | Fin Agent APIのapiキーを使ったワークスペース認証 | Messenger JWTを使った単一の認証済みエンドユーザー認証 |
信頼モデル | 信頼されたサーバー間バックエンド | 信頼されていないユーザーごとのクライアント（エンドユーザー環境内または近くで動作するAIアシスタント） |
誰のIDか？ | クライアントは各呼び出しがどのエンドユーザー（user_id）として動作するかを主張します | トークン自体がIDであり、クライアントは他の誰としても動作できません |
アプリレベルのシークレットを保持しているか？ | はい（Fin Agent APIキー） | いいえ — 1ユーザーにスコープされたJWTのみ |
ユースケース
Fin Agent API MCPサーバーは、独自のエージェントがFinの機能にアクセスする必要があるマルチエージェントシナリオ向けに設計されています。
製品エージェントへの組み込みサポート。 製品のAIアシスタントに、knowledge baseやコンテンツを重複させることなく、設定済みのFin knowledgeを使ってサポート質問に答える能力を与えます。
手順の自動化。 オーケストレーションエージェントがユーザーの代わりにFinの手順（返金、アップグレード、キャンセル）をトリガーし、マルチターンのやり取りをプログラム的に処理できます。
能力駆動のルーティング。 list_fin_capabilitiesを使って特定ユーザーに利用可能なアクションを判別し、エージェントの意思決定ロジックで適切なツールにルーティングします。
開発者向けツール。 Claude CodeやCursorなどの開発者ツール内にFin knowledgeを表示し、内部のusersが既存のワークフローからサポートコンテンツを問い合わせられるようにします。
前提条件
IntercomのワークスペースでFin Agent API機能が有効になっている必要があります。アクセス権がない場合はIntercomのアカウントチームにお問い合わせください。
エンドポイント
リクエストを行う者によって2つのエンドポイントがあります。
チームメイトエンドポイント
https://api.intercom.io/fin/mcp
信頼されたバックエンドサービスがユーザーの代わりにFinを呼び出す場合に使用します。呼び出し元はワークスペースのOAuthアクセストークンで認証します。エンドユーザーのIDは呼び出しサービスがリクエストボディで提供します。
このモデルは、バックエンドがリクエストを行う者を制御するサーバー間統合に適しています。
エンドユーザーエンドポイント
https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}MCPクライアントがエンドユーザーの環境内または近くで動作する場合に使用します。例えば、ユーザーのマシン上でローカルに動作するAIアシスタントなどです。呼び出し元は単一の認証済みエンドユーザーを表す署名済みJWTで認証します。
{YOUR_APP_ID_CODE}パスパラメータはIntercomワークスペース識別子です（Messengerインストールスニペットで使用されるapp_idと同じ）。
認証はすでにID検証に使われているMessenger JWTメカニズムと同じです。MessengerのID検証が設定済みなら、Intercom側で追加設定は不要です。
認証
チームメイトエンドポイント
Fin Agent APIのapiキーをAuthorizationヘッダーのBearerトークンとして渡します。
Authorization: Bearer YOUR_FIN_AGENT_API_KEY
エンドユーザーエンドポイント
ワークスペースのMessengerシークレット（設定 → セキュリティ → ID検証にあります）を使って署名済みJWTを生成します。JWTはHS256で署名し、subクレームにユーザーの外部IDを含める必要があります。これはMessengerのエンドユーザー認証用に生成するJWTと全く同じです。
JWTペイロードの例:
{
"user_id":"user@example.com"
}
Bearerトークンとして渡します:
Authorization: Bearer YOUR_USER_JWT
JWTで識別されたユーザーがFinの応答対象です。このユーザーを使って会話を作成し、手順をマッチングします。バックエンドがこのトークンをサーバー側で生成し、クライアントに提供します。Messengerシークレットをクライアント側で絶対に公開しないでください。
Claudeからの接続
Claude Desktop
claude_desktop_config.jsonに以下を追加してください:
チームメイトエンドポイント:
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp",
"--header",
"Authorization: Bearer {YOUR_FIN_AGENT_API_KEY}"
}
}
}
}
エンドユーザーエンドポイント:
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}",
"--header",
"Authorization: Bearer {YOUR_USER_JWT}"
}
}
}
}
Claude Code (CLI)
チームメイトエンドポイント:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp \
--header "Authorization: Bearer YOUR_FIN_AGENT_API_KEY"
エンドユーザーエンドポイント:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp/YOUR_APP_ID_CODE \
--header "Authorization: Bearer YOUR_USER_JWT"
または.mcp.jsonのmcpServersに同等のJSONを追加してください。
ツール
接続後、MCPサーバーはクライアントに5つのツールを公開します。
list_fin_capabilities
指定ユーザーに利用可能なFin Agent APIの機能を返します：ユーザーがトリガーできる対象者マッチの手順と、すべてのusersが利用できる静的アクション（質問する、会話に返信する）。
最初にこれを呼び出して、特定ユーザーに対してFinが何をできるかを確認してください。手順アクセスは対象者マッチで、すべてのユーザーがすべての手順にアクセスできるわけではありません。
入力: user_id — ユーザーの外部ID。
返却: 利用可能な機能をタイプ、ID、名前付きでリストしたJSONドキュメント。
ask_fin
Finに一度きりの質問を送り、回答を返します。Finは設定済みのknowledge sourcesを検索し、持続的な会話を開始せずに直接応答を返します。
マルチターンのフローが不要で直接回答が欲しい情報検索に使用してください。
入力: user_id、message（質問内容）。
get_fin_response
進行中の会話や手順フローに対するFinの返信をポーリングします。会話や手順開始後にFinの最新応答を取得するために使用します。
入力: conversation_id。
reply_to_fin_conversation
既存のFin会話にフォローアップメッセージを送信します。マルチターンのやり取りを続けるために使用します。例えば、手順中にFinが要求した追加情報を提供する場合などです。
入力: conversation_id、message。
run_fin_procedure
ユーザーのために特定のFin手順をトリガーします。手順は設定されたマルチステップワークフローで、例えば返金処理やサブスクリプション更新などです。Finは手順を開始し、追加情報を求め、やり取りを完了まで進めます。
実行したいアクションの手順IDを見つけるために、まずlist_fin_capabilitiesを使用してください。
入力: procedure_id、user_id。