外部サービスをAI社員に操作させる（API / MCP連携）

このマニュアルでできること

AI社員に「freeeの未処理明細を確認して仕訳の候補を作って」のように、外部サービス（SaaS・社内API）を使う仕事を任せられるようになります。会計SaaS（freee）を例に、コネクタの接続からAI社員への能力付与、書き込みの承認までを説明します。

仕組み（先に全体像）

1. AI社員はサンドボックス内からMCP（mcporter）でコネクタのツールを呼び出します（呼び方はAI社員に自動で案内されるため、ユーザーが意識する必要はありません）
2. APIキー・OAuthトークンなどの認証情報はプラットフォーム側（Connector Gateway）だけが保持し、暗号化保管されます。AI社員のサンドボックスには渡りません
3. 読み取りは即時、書き込みは承認申請の起票→管理者承認→プラットフォームが代理実行という流れになります
4. 宣言されていないコネクタの呼び出しは自動ブロック（fail-close）され、すべての操作が監査ログに記録されます

手順1: コネクタを接続する（管理者・最初の1回だけ）

サイドバーの Connectors（Connector Settings）を開き、使いたいコネクタを接続します。

• freee / Gmail / Threads（公式コネクタ）: 「OAuth接続」ボタンからサービスの認可画面で許可します。接続を解除するといつでもfixture（疑似データ）モードに戻せます
• カスタムコネクタ: APIキーの設定やOAuthクライアントの設定もこのページで行います

手順2: AI社員に能力を付与する

外部サービスを使えるのは、能力プロファイルとコネクタ宣言を持つAI社員だけです。

Agent Storeのペルソナ詳細に能力プロファイルと必要コネクタが明示されています。コネクタを使うペルソナの採用には管理者の承認（R3）が必要で、承認するとその能力で稼働を開始します。Persona Studioで自作するペルソナも同様に、能力・権限タブでプロファイルとコネクタを宣言します。

Office ViewでAI社員をクリック → サイドバーの Capabilities で、そのAI社員に許可されたコネクタ・ツール権限をいつでも確認できます。

手順3: 操作を依頼する

あとはCommand Inbox（またはSlack等のチャネル）で、普通に仕事を頼むだけです。

例:
「freeeの未処理明細を確認して、仕訳の候補を作ってください」
「今月の試算表を取得して、前月と比べた変化を要約してください」
「この経費明細をfreeeに取引として登録してください」   ← 書き込み（承認フローへ）

AI社員は内部でMCPツール（例: freee.list_wallet_txns / freee.get_trial_balance / freee.create_deal）を呼び出して作業します。読み取り結果を使った分析やレポート・ファイル作成（成果物としてダウンロード可能）も組み合わせられます。

手順4: 書き込みを承認する（管理者）

AI社員が書き込みツール（例: freeeへの取引登録）を呼び出すと、即時実行ではなく承認申請が起票されます。管理者は全社承認ボードで「何を・どう書き込むか」を確認して承認・却下します。

承認されると、プラットフォーム（Connector Gateway）が次の保護付きで代理実行します。

• 冪等実行 — 同じ申請が二重に実行されることはありません
• 実行前スナップショット — 書き込み前の状態を記録します
• 読み戻し検証 — 書き込み後にAPIから読み直し、意図どおりに反映されたかを確認します
• 監査ログ — 起票・承認・実行・検証結果まで全過程が記録されます

ファイルを扱う（Google Drive / SharePoint / OneDrive・ナレッジベース）

ファイル系の公式コネクタ（google-drive / microsoft-graph）を宣言したAI社員は、外部ストレージ内のファイルを検索・取得・編集・書き戻しでき、文書の内容をナレッジベース（RAG）に取り込んで以後の回答に活用できます。

検索と取得（読み取り・即時）

例:
「Google Driveで先月の経費精算ルールのファイルを探して要約してください」
「SharePointの総務ポータルにある就業規則の最新版を開いて、変更点を教えてください」

• ファイル名・全文検索、フォルダ内の一覧、SharePointサイトの検索（list_sites）ができます
• 取得したファイルはAI社員のサンドボックス（/workspace/in/）に配置され、Word / Excel / PowerPoint / PDFをその場で開いて読めます。Googleドキュメント・スプレッドシート等のネイティブ形式は自動でdocx / xlsx / pptxに変換して取得します

編集と書き戻し（書き込み・承認制）

例:
「この報告書のドラフトを修正して、Driveの経理フォルダにアップロードしてください」

• AI社員が編集したファイルのアップロード・更新は承認申請の起票になります。起票時点のファイル内容がスナップショットとして保存され、承認カードの添付チップからダウンロードして中身を確認してから承認できます（起票後にAI社員側でファイルを変えても実行対象は変わりません）
• 承認後はプラットフォームが代理アップロードし、書き込み結果を読み戻して検証します（手順4と同じ保護）

ナレッジベース（RAG）に取り込む

例:
「この就業規則をナレッジベースに取り込んでください」
「ナレッジベースで経費精算のルールを調べて答えてください」

• 取り込んだ文書は意味検索（ベクトル検索）でき、AI社員は出典ソース名つきで回答します
• 取り込みは既定でテナント共有（他のAI社員からも検索可能）。scope=agent指定で取込者専用にもできます。同名ファイルの再取込は置換、削除は取り込んだAI社員本人のみ可能です
• 埋め込み（ベクトル化）のAPI費用はAI社員別（kb:AI社員ID）に計上され、LLM Controlのコスト画面で確認できます

Webを閲覧・操作させる（Webコネクタ）

Webコネクタ（web）を宣言したAI社員は、ヘッドレスブラウザでWeb検索・ページ閲覧（読み取り・即時）と、フォーム入力・クリック・送信などのページ操作（書き込み・承認制）ができます。APIが公開されていないSaaSを画面越しに操作したいときに使います。

検索と閲覧（読み取り・即時）

例:
「『社内規程 経費』でWeb検索して、上位の結果を教えて」
「https://example.com/news を開いて要点を3行で要約して」

• 公開Webは自由に閲覧できます（社内ネットワークやクラウドのメタデータなど非公開の宛先は自動で遮断されます＝SSRFガード）
• ページ内のリンク・フォーム・ボタンを一覧し、必要なら画面のスクリーンショットを /workspace/in/ に保存できます

ページ操作（書き込み・承認制）

クリック・入力・送信といったページに変化を与える操作は、管理者が登録した「Write許可ドメイン」のページでのみ行え、実行前に承認が必要です。

Connector Settingsの「web」の行で、操作を許可するドメイン（例: portal.example.co.jp）を追加します。ここに無いドメインでは操作の起票自体ができません（閲覧は可能）。

AI社員が操作を実行しようとすると、そのときの画面のスクリーンショット付きで承認申請が起票されます。管理者は全社承認ボードで「どのページで・どんな手順を行うか」を確認して承認します。承認後は、起票時と同じページのままであることを確認したうえでプラットフォームが操作を実行します（ページが変わっていたら中止）。

検索を正式APIにする（web-searchコネクタ）

Webコネクタの検索は簡易的なもの（検索結果ページの解析）のため、業務で検索を多用する場合は検索エンジンの正式APIを使う公式コネクタ web-search を推奨します。

1. Brave Search API（月2,000クエリ無料）またはTavily（月1,000クエリ無料・AIエージェント向けで要約回答つき）のAPIキーを取得します
2. 環境設定 WEB_SEARCH_PROVIDER=brave または tavily でエンジンを選択します
3. Connector Settingsの「Web検索（Brave / Tavily）」の行で「APIキー設定」から登録します（暗号化保管）
4. AI社員のペルソナに web-search コネクタを宣言すると、検索は自動的に正式API側が優先されます

SaaSへのログイン

ログインが必要なSaaSは、Connector Settingsでドメインごとにユーザー名・パスワードを登録します（許可ドメインのみ・パスワードは暗号化して保管）。

Threads に投稿する（threads コネクタ）

公式コネクタ threads を宣言した AI 社員は、自社の Threads アカウントの投稿一覧・効果指標（表示・いいね・返信・リポスト・引用・シェア）・返信と、Threads 上の公開投稿のキーワード検索を読み取れ（即時）、投稿・返信の公開を承認制で行えます。SNS 運用（調査 → 企画 → 投稿 → 効果測定）を AI 社員に任せるときの基盤です。

接続する（管理者・最初の 1 回）

1. Meta for Developers で「Threads API」ユースケースのアプリを作成し、リダイレクト URL に https://＜コンソールの公開 URL＞/api/connectors/threads/oauth/callback を登録、投稿に使う Threads アカウントをテスター（または本番ユーザー）として追加します。
2. アプリの ID とシークレットを環境設定 THREADS_OAUTH_CLIENT_ID / THREADS_OAUTH_CLIENT_SECRET に設定します（テナント管理者または運営が実施）。
3. Connector Settings の「Threads (Meta)」の行で「OAuth接続」を押し、Threads の認可画面で許可します。接続後のアクセストークンは 60 日ごとに自動更新されます（長期間まったく使わなかった場合のみ再接続が必要です）。

依頼する

例:
「先週の投稿の表示数といいね数を一覧にして、伸びた投稿の共通点を教えて」
「『AI社員』でキーワード検索して、今日盛り上がっている話題を 3 つ挙げて」
「明日の朝に投稿する本文を 3 案作って、いちばん期待できる案を推薦して」
「案 2 を投稿して」 → 承認カードが届きます

• 読み取り（投稿一覧・効果指標・返信・検索）は即時に実行され、結果は監査ログに残ります。
• 投稿・返信は承認制です。AI 社員が起票すると全社承認ボード／Approval Center に本文がそのまま表示され、管理者が承認した時点で公開されます。1 回の承認で 1 投稿が公開されます（Threads の 2 段階 API はプラットフォームがまとめて処理します）。
• 公開後は投稿を読み戻して本文が一致することを確認し、一致しない場合は「未検証」として成功扱いにしません。

画像付きで投稿する

AI 社員が /out/ に用意した PNG / JPEG（media コネクタで生成した画像や、加工した画像）を 1 枚添えて投稿できます。起票時点の画像が承認対象になり、承認カードの添付チップから内容を確認できます。公開時にだけプラットフォームが15 分間有効な署名付き URLを発行して Meta に画像を取得させ、公開後すぐに失効させます。

制限事項

• 本文は 500 文字まで、画像は 1 枚・8MB まで（カルーセル・動画は未対応）。
• キーワード検索と投稿には Threads 側の回数制限があります。AI 社員には「1 回の調査で検索は数回まで、1 回の依頼で起票する投稿は 1 件」と案内しています。
• 投稿別の「プロフィールアクセス数」「フォロワー増加数」は Threads API が提供していないため取得できません（アカウント全体のフォロワー数の推移で代替します）。
• 承認して公開した投稿を取り消す機能はありません。Threads 側で削除してください。

freee以外の会計SaaS・社内API・MCPサーバをつなぐ（カスタムコネクタ）

マネーフォワード等の他の会計SaaSや社内APIは、Persona Studioの「コネクタ開発」でWebUIだけから追加できます（git・CLI不要）。種別はREST APIとMCPサーバの2つです。

MCPサーバを選ぶと、外部のMCPサーバ（SaaS公式のMCP・自社で立てたMCP等。streamable HTTP）のURLと認証を宣言し、「ツールを取得」でツール一覧を取り込んで、使うツールだけを採用します。AI社員がMCPサーバへ直接つながるわけではなく、採用したツールをConnector Gateway経由で呼び出します（公式コネクタ・REST APIコネクタと同じ統制）。MCPにはツールの副作用の区別が無いため、採用した各ツールをread / write に分類する必要があります（writeは承認制）。

1. 認証方式を選ぶ: APIキー / Bearerトークン / OAuth2 / 認証なし
2. readツールを宣言する（GETのみ。URL・パラメータ・説明）
3. writeツールを宣言する（読み戻し検証 verify の定義つき: 実行後にどのAPIで何を確認するか）
4. テナント内の公開承認（4-eyes）を経ると、公式コネクタと同じ統制フロー（read即時 / write承認制・fail-close・監査）で利用できるようになります

コミュニティMCPサーバをワンクリックで使う（運営カタログ）

自分でMCPサーバの定義を書かなくても、運営が公開しているコミュニティMCPサーバをそのままコネクタとして使えます。運営は公式MCP Registryのサーバを毎日自動で取り込み、ツールを読み取り／書き込みに分類したうえで、次のレーンで公開しています。

公開中のサーバがカードで並びます。レーン、読み取りツール名、「APIキー必要」の有無、機械翻訳バッジが表示されます。

Green はそのまま有効になり、Yellow は承認申請（R3）が起票されます。有効化されたサーバは custom.<名前> というIDのコネクタになり、上の Connector Settings 一覧にも表示されます。

「APIキー必要」のサーバは、有効化（承認）後に Connector Settings 一覧の「APIキー設定」からそのサービスのキーを登録してください。登録するまで、AI社員からの実行は「キー未設定」で止まります（運営のキーが配布されることはありません）。

他のコネクタと同じく、使わせたいAI社員の required_connectors（Persona Studio の能力・権限タブ、または Capabilities ページ）にそのコネクタIDを宣言します。読み取りは即時、書き込みは承認制という統制はそのままです。

コミュニティ REST API（OpenAPI）をワンクリックで使う（運営カタログ）

MCP サーバと同じく、運営が公開しているコミュニティ REST APIもそのままコネクタとして使えます。運営は公開 OpenAPI ディレクトリ（APIs.guru）と手動登録の OpenAPI 定義を毎日自動で取り込み、GET エンドポイントだけをツールにして公開しています（書き込みは含まれません）。

• Green（すぐ使える）: 認証不要・GET のみ・自動判定をすべて通過。Connector Settings 下部の「コミュニティ REST API」から「有効化」を押すと即座にコネクタになります
• Yellow（運営審査済み）: API キーが必要、またはエンドポイントが多く運営が採用分を選んだもの。「有効化」で承認申請が起票され、承認後に使えます。API キーが必要なものは Connector Settings 一覧の「APIキー設定」から自社のキーを登録してください

有効化されたコネクタの ID は custom.api-スラッグ名（スラッグ名は運営カタログの ID） です。AI 社員には他のコネクタと同じく required_connectors で宣言します。ツールは OpenAPI の各 GET に対応し、パラメータは query と path のみです。応答は 2MB までに制限されます。

制限事項

• コネクタを使えるのは能力プロファイル（connector_assist / connector_write）を宣言し採用承認を経たAI社員のみです
• 書き込みは必ず承認経由です（AI社員が外部サービスへ直接書き込むことはできません）
• カスタムコネクタ（REST API）のreadはGETのみ、writeは読み戻し検証の定義を推奨します（未定義時は2xx応答ベースの確認になります）
• カスタムコネクタ（MCPサーバ）はツール（tools）のみ対応です。resources / prompts / sampling は使いません。採用ツールのread/write分類は申請者の宣言であり、承認者が確認します
• MCPサーバ側でツールの引数が変わる・削除されると（ドリフト）、該当ツールは再承認まで実行が止まります。Persona Studioの「上流に合わせて再取り込み」→再承認で解消します（自動追従はしません）
• コミュニティMCPサーバ（運営カタログ）で使えるのは読み取りツールのみです。書き込みツールが必要な場合は、Persona Studio で自社のカスタムコネクタとして定義してください。OAuth方式のMCPサーバは運営カタログの対象外です
• コミュニティ REST API（運営カタログ）で使えるのは GET のみ（query／path パラメータ）です。OAuth2・URL パラメータ方式の API キー・HTTP Basic 認証の API は対象外です。書き込みが必要な場合は Persona Studio の REST コネクタとして定義してください
• PoC環境ではfreee等を実接続せずfixture（疑似データ）モードのまま試すこともできます

Web 閲覧許可ドメイン（AI 社員が読んでよい Web サイト）

Connectors 画面の Web コネクタ欄にある「Web 閲覧許可ドメイン」に登録したドメイン（サブドメインを含む）は、Web 調査以上の権限を持つすべての AI 社員が Web ページの取得に使えます。各 AI 社員が宣言しているドメインと合わせて適用され、登録外のドメインへのアクセスは遮断されて監査ログに残ります。変更は即時に反映され、再デプロイは不要です。

困ったとき