メインコンテンツまでスキップ

MCP 統合

モジュール構成を使用している組織では、接続先の組織にアクティブな CRM モジュールと、統合に必要なスコープの両方が必要です。CRM へのアクセスがない場合、基盤 API は module_not_active を含む HTTP 403 を返します。再試行する前に Subscription でモジュールへのアクセスを解決してください。API キーを変更するだけでは、このエラーは解消されません。

Scoutello は、組織データへの制御されたアクセスを提供するリモート Model Context Protocol (MCP) サーバーを提供します。REST API と同じ統合、API キー、スコープ、テナントチェック、レート制限、レコード動作を使用します。Scoutello REST API

AI クライアントまたはエージェントで Scoutello の操作をツールとして検出・呼び出す場合は MCP を使用します。一般的な HTTP エンドポイントや生成済み OpenAPI クライアントが必要なアプリケーションでは REST を使用します。どちらも同じ基盤データコントラクトを使用します。

接続前の準備​

組織管理者は、Organization settings → Developer/API で統合を作成する必要があります。キーを作成またはローテーションする際は、次の点に注意してください。

  1. MCP クライアントに必要な読み取り・書き込みスコープのみを選択します。
  2. 表示された完全な sctl_api_ キーを保存します。Scoutello で表示されるのは一度だけです。
  3. キーはソース管理ではなく、MCP クライアントのシークレットまたは環境設定に保存します。

同じ統合キーで REST と MCP の両方を呼び出せます。MCP 専用のキーを別途作成する必要はなく、推奨もされません。以前の sctl_mcp_ キーは受け付けられません。

接続値​

次の値をクライアントに設定します。

Transport: Streamable HTTP
URL: https://admin.scoutello.com/api/v1/mcp
Header name: Authorization
Header value: Bearer YOUR_API_KEY

YOUR_API_KEY を保存した統合キーに置き換えます。クライアントによって設定形式は異なりますが、上記のトランスポート、URL、HTTP ヘッダーは同じです。クライアントで Authorization を設定できない場合は、代わりに x-api-key でキーを送信できます。両方のヘッダーを設定しないでください。

従来の https://admin.scoutello.com/api/mcp URL は、互換性エイリアスとして引き続き使用できます。新しい接続では、バージョン付きの /api/v1/mcp エンドポイントを使用してください。

接続を確認する​

クライアントの接続後、最初に whoami ツールを呼び出します。このツールは、現在の統合と組織、認証情報の有効期限と使用状況、レート制限の状態、付与されたスコープを返します。組織のレコードは公開しません。

whoami で予期しない組織または統合が示された場合は、クライアントを切断し、別のツールを呼び出す前にキーを修正してください。

ツールとスコープ​

MCP サーバーは、現在のキーに付与されたツールのみを公開します。対応する読み取りスコープだけでは、書き込みツールを検出または呼び出すことはできません。

API スコープMCP ツール
contacts.readcontacts_list、contacts_get、contacts_get_by_external_id
contacts.writecontacts_batch_upsert
tasks.readtasks_list、tasks_get、tasks_get_by_external_id
tasks.writetasks_batch_upsert
protocols.readprotocols_list、protocols_get、protocols_get_by_external_id
protocols.writeprotocols_batch_upsert
opportunities.readopportunities_list、opportunities_get、opportunities_get_by_external_id
opportunities.writeopportunities_batch_upsert
projects.readprojects_list、projects_get、projects_get_by_external_id
projects.writeprojects_batch_upsert(参加者の upsert を含む)
milestones.readmilestones_list、milestones_get、milestones_get_by_external_id
milestones.writemilestones_batch_upsert
members.readmembers_list
events.readevents_list、events_get、events_get_by_external_id
events.writeevents_batch_upsert
mails.readmails_list、mails_get
mail-drafts.readmail_drafts_list、mail_drafts_get、mail_drafts_get_by_external_id
mail-drafts.writemail_drafts_batch_upsert(人による確認の準備のみ)
tags.readtags_list

whoami は、認証済みの接続で常に使用できます。ツールの入力と結果は、関連付けられた REST 操作と同じスキーマおよびレスポンスエンベロープに従います。

contacts_list は、名、姓、会社名、type、status、tagIds(1~50 個の ID の配列。選択したタグのいずれかに一致)を対象に、件数が制限された search を受け付けます。検索トークンはすべて名前フィールドに一致する必要があり、すべてのフィルターは AND 条件で組み合わされます。これらのフィルターは、すべてのカーソルページに引き継いでください。たとえば、{ "search": "Hamburg Hotel", "type": "company", "tagIds": ["tag-one", "tag-two"] } を使用すると、全件を走査せずに一致する既存のアカウントを検索できます。

Scoutello ログインにリンクされた非メンバーの CRM 連絡先は、読み取りおよび参照が可能です。一方、メンバーシップやアカウントのフィールドは非表示のままで、連絡先の編集は保護されます。外部リンクのみの upsert では、externalId、その scoutelloId、任意の externalUpdatedAt を使用して、読み取り可能な連絡先を登録できます。CRM フィールドはすべて省略してください。後続の再試行やメタデータ更新では、scoutelloId を省略します。連絡先の境界とリンクルールを参照してください。

安全に書き込む​

一括アップサートツールは、Scoutello のデータを直ちに変更できます。同じインテグレーションと外部 ID の組み合わせに対しては冪等ですが、変更を適用する前に、対象のリソース、組織、スコープを確認してください。

mode を validate に設定すると、書き込みを行わずに照合と検証を実行できます。結果を確認した後、mode: "apply" を付けて再度呼び出すと、有効なレコードを受け入れられます。MCP では削除操作を利用できません。

インテグレーションを一時停止すると、そのキーを使用する REST と MCP のリクエストがどちらも拒否されます。ローテーションでは認証情報が置き換えられ、失効ではそのインテグレーションに属するすべての認証情報が恒久的に無効になります。

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

結果確認事項
401 認証エラー完全なキーが含まれていること、ヘッダーで Bearer が使用されていること、キーが引用符で囲まれていないことを確認します。
403 認可エラーインテグレーションキーをローテーションして必要なスコープを付与し、置き換え後のキーでクライアントを更新します。
404 MCP URL でのエラーURL の末尾が /api/v1/mcp であることを確認します。その Scoutello 環境では MCP サービスがまだ有効になっていない可能性があります。
429 レート制限エラー再試行する前に、返されたリセット時刻まで待ちます。REST と MCP は同じインテグレーションのクォータを消費します。
ツールが見つからないwhoami でキーのスコープを確認します。利用できないツールは、意図的に検出結果から除外されています。

レコードフィールド、ページネーション、一括処理の動作、エラーエンベロープについては、Scoutello API リファレンスを参照してください。

接続済みプロジェクト計画​

安定したインテグレーション外部 ID を使用して、プロジェクト、マイルストーン、タスク、プロトコルの順に作成します。新しいマイルストーンへのアクセスには milestones.read/milestones.write が必要です。割り当て可能なメンバーを検索するには members.read を付与します。既存の認証情報の権限は自動的に拡張されません。アクセスをローテーションまたは付与した後、ツールの検出結果を更新して whoami を確認します。

プロジェクトまたはマイルストーンの assignedContacts にはメンバーの Customer ID を使用し、タスクの assignedScoutelloUserIds または商談の ownerScoutelloUserId には User ID を使用します。タスクまたはプロトコルの参照には projectScoutelloId または projectExternalId と、それぞれに対応するマイルストーンまたは商談の ID ペアを指定できます。マイルストーンのみのリンクではプロジェクトが推測されます。不一致がある場合、その一括処理項目は拒否されます。プロジェクト参加者は追加型アップサートとして処理され、省略されたエントリは保持されます。

プロトコルでは、連絡先を必要としないプロジェクトまたはマイルストーンのメモと、draft/final ステータスに対応しています。この接続済み作業のインポートは非通知で実行され、連絡は一切送信されません。一覧ツールでは、REST と同じエンティティ固有のプロジェクト、ステータス、割り当て、期限のフィルターを利用できます。updatedSince を含む正確なフィルターを、各カーソルページに引き継いでください。完全な仕様と null/省略時の動作については、API リファレンスを参照してください。

依存関係のある各一括処理を検証して適用し、すべての結果を確認してから、レコードを読み戻し、データ登録が完了したと判断します。ドライランでは、別のドライランでのみ存在する親を解決できません。scoutelloId を使用して不明確な初回リンクを再試行する場合は、まず外部 ID で読み取ります。リンクが存在すると、ブートストラップ ID を再利用することはできません。

営業プロジェクト向けエージェント指示​

営業プロジェクト用に作成または再利用するすべての連絡先では、contacts_batch_upsert 内の projectScoutelloId または projectExternalId を使用して、そのプロジェクトを明示的に参照する必要があります。メモや外部 ID でプロジェクトに言及しても、メンバーシップにはなりません。プロジェクト参照を含む連絡先の書き込みには、projects.write も必要です。contacts.read と projects.read で連絡先を読み戻し、projectParticipations を確認します。既存のメンバーシップとグループは保持してください。プロジェクト外の一般的な連絡先には、プロジェクト参照は必要ありません。

会社と確認済みの人物は、別々の連絡先として保持します。companyScoutelloId または companyExternalId を使用して人物を会社にリンクし、companyName だけに依存しないでください。連絡先、会社との関係、メンバーシップの変更は、一括処理項目ごとにアトミックに適用されます。無効な参照がある場合、連絡先は一部だけ作成されることはありません。人物を推測したり、出所タグを付けたりしないでください。

送信メールは mail_drafts_batch_upsert を使用して準備し、プロトコル本文として扱わないでください。新しい mail-drafts.read と mail-drafts.write のスコープを明示的に付与します。準備には contacts.read と projects.write も必要です。既存の認証情報に新しい権限が自動的に付与されることはありません。安定した外部 ID、作成時の expectedVersion: 0、明示的なプロジェクト/連絡先参照、承認済み承認者の User ID、設定済みの organization または personal の送信者スコープを使用します。受信者のアドレスや送信者設定を推測しないでください。

調査内容は content.notes に保持し、送信用のコピーには content.subject と content.body だけを使用します。下書きを作成すると、連絡先がプロジェクト参加者になります。更新時には、最新の読み取りで返されたバージョンを使用します。レビュー済みまたは送信済みの下書きは編集できません。同一内容の再試行では、別のレビューを作成せず、元の下書きが返されます。reviewUrl、draftVersion、contentHash、承認/送信ステータス、最終的な mailScoutelloId を読み戻します。

割り当てられた担当者だけが、既存のレビュー画面から承認して送信できます。インテグレーションでは、下書きの書き込み権限があっても、承認、送信処理、メール送信を実行できません。古い下書きを変換する場合は、元のプロトコルを保持し、置き換えたものを相互参照してください。キュー投入または不明確な配信失敗が発生した場合は調査が必要であり、盲目的に再送してはいけません。

ソーシャル投稿の準備​

必要に応じて social-channels.read、social-posts.read、social-post-drafts.read、social-post-drafts.write を付与します。members_list(members.read)では、レビュー担当者のユーザー ID を取得できます。ソーシャルツールは、対応するスコープが付与されている場合にのみ表示されます。

スコープツール
social-channels.readsocial_channels_list
social-posts.readsocial_posts_list、social_posts_get
social-post-drafts.readsocial_post_drafts_list、social_post_drafts_get、social_post_drafts_get_by_external_id
social-post-drafts.writesocial_post_drafts_batch_upsert、social_media_create_upload、social_media_finalize_upload

チャンネルの機能と Scoutello が作成した履歴を確認し、アセットをアップロードしてから、レビュー担当者を指定した完全なチャンネル別バリエーションを送信します。アップロードツールは HTTP PUT の手順を返します。MCP の外部で元ファイルのバイト列を転送し、その後 { "assetId": "..." } でアップロードを完了します。ツールの引数に base64 ファイルを埋め込まないでください。

新しい下書きには expectedVersion: 0 を使用し、保留中の修正版には現在のバージョンを使用します。mode: "validate" は書き込みを実行しません。ツールはレビュー URL を返します。公開またはスケジュール設定を承認できるのは、ダッシュボードを使用する担当者だけです。投稿の承認、公開、キャンセル、削除を行う MCP ツールはありません。下書き/履歴ツールをポーリングして、承認状況、却下理由、チャンネルごとの配信結果を確認します。レビュー済みの下書きについて、さらに提案するには新しい外部 ID が必要です。

入力例、アップロード制限、ページネーション、レビューが遅れた場合の動作については、人によるレビュー用のソーシャル投稿を参照してください。