外部サービスを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（公式コネクタ）: 「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でドメインごとにユーザー名・パスワードを登録します（許可ドメインのみ・パスワードは暗号化して保管）。

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

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

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

制限事項

• コネクタを使えるのは能力プロファイル（connector_assist / connector_write）を宣言し採用承認を経たAI社員のみです
• 書き込みは必ず承認経由です（AI社員が外部サービスへ直接書き込むことはできません）
• カスタムコネクタのreadはGETのみ、writeは読み戻し検証の定義を推奨します（未定義時は2xx応答ベースの確認になります）
• PoC環境ではfreee等を実接続せずfixture（疑似データ）モードのまま試すこともできます

困ったとき