freee-mcpを Local→Remote で出してわかった MCP認可実装のリアル

Transcript

1. freee-mcpを Local→Remote で出してわかった MCP認可実装のリアル OpenID TechNight vol.23 ~ AI x API x Enterprise 2026.05.25
2. 2 てらら 2021年にフリー株式会社入社 去年からOIDF-Jの人材育成WGにて活動し、今 年はKYC WGで活動予定。 趣味はホラー映画と猫と兎田ぺこら。 IdF PdL terara
3. 本日の内容 話すこと • Local → Remoteで責任境界がどう変わるか • Remote MCPをSaaS提供者が運用すると増える認可の論点 • MCP認可仕様と既存SaaS権限モデルのあいだで考えたこと 合言葉 Local / Remoteは「優劣」ではなく「責任境界のトレードオフ」 話さないこと • MCP仕様の網羅的な解説 • freee-mcpの機能紹介
4. 4 AIエージェントからfreeeのPublic APIを使うためのMCPサーバー freee-mcpとは AI Agent freee-mcp MCP Server freee API 業務データ 会計 人事労務 請求書 工数管理 販売 … 対象領域 チャットで「請求書を作って」「今月の試算表を見せて」などを依頼すると、 AIがMCP toolを選び、freee API経由で業務操作を行う。 （現在ベータ版です） 参考: freeeヘルプセンター「freee-mcp（リモート版）を設定して利用する」 2026-04-07更新
5. 5 Local→Remoteの体験談を、認可実装の論点に落とす freee-mcpから学んだこと 1 Localで 価値検証 2 Remote化で 責任境界が移 動 3 認可論点が 一気に増える 4 実装判断と 学び 「Remoteを選ぶとサービス提供者側で何を設計する必要が出るか」
6. 6 サーバーがユーザーの手元にいる Local MCPの世界 ユーザーの手元環境 AI Host Desktop App IDE Local MCP Server freee API local files CLI / env local token Localが得意な場面 • ローカルファイル / CLI / IDE • PoC・開発者向け利用 • ユーザー環境に閉じた連携 価値検証の入り口として強い MCP Architecture: local MCP servers with stdio typically serve a single MCP client; filesystem server is an example of a local MCP server.
7. 7 サーバーがサービス提供者の責任境界に入る Remote MCPの世界 User A Client X User B Client Y User C Client Z Remote MCP Server サービス提供者が運用 Authorization Server freee API Remote化で変わること 「サーバーを置く場所」ではなく 「責任境界」の変更 MCP Transports: Streamable HTTP can handle multiple client connections and supports standard HTTP authentication methods, OAuth recommended. サービス提供者 AI Platform
8. 8 どちらがよいかは、扱う対象と責任分担で決まる Local / Remoteは上位互換ではなくトレードオフ 観点 Local MCPが得意 Remote MCPが得意 データの近さ local files / CLI / IDE クラウド上の業務データ / SaaS API 導入 開発者・PoCで試しやすい 接続設定のみで利用開始しやすい 運用 ユーザー環境に寄せられる サービス提供者が集中管理できる 認可 手元の資格情報を使いやすい OAuth / scope / 監査と接続しやすい 主な難しさ 配布・設定・環境差分 認可・運用責任・マルチテナント 今日の主題： Remoteを選んだときに、サービス提供者側へ寄ってくる認可の責任
9. 9 「動くか」から「誰が、何を、どこまで許されるか」へ Remote化で増える問い Remote MCP Server User / Tenant 誰が使う？ Client identity どのクライアント？ Scope / Role どの権限？ Tool / Action 何をする？ Audience どのトークン？ Log / Audit どう監査する？ Localで暗黙に置けた前提が、 Remoteではサービス提供者の設計対象になる。
10. 10 道筋はある。ただしプロダクトに載せるための判断は残る MCP認可仕様がくれる地図 1 Protected Resource Metadata MCPサーバーが認可サーバーの場所を示す 2 Client Registration 未知のMCPクライアントをどう識別するか 3 Resource Parameter どのMCPサーバー向けのtokenかを明示する 4 Token Handling MCPサーバーがaudienceを検証する 5 insufficient_scope / Step-up 必要なscopeを追加要求する余地がある 仕様は「地図」。実装では、既存の認証認可基盤・ API・権限モデル・ UXにどう接続するかが本番。 MCP Authorization 2025-11-25: protected MCP server acts as OAuth 2.1 resource server; MCP servers MUST implement OAuth Protected Resource Metadata.
11. 11 このクライアントは誰で、どこまで信頼するのか 論点1：MCPクライアントをどう扱うか MCP Authorization 2025-11-25: Client ID Metadata Documents / preregistration / Dynamic Client Registration are described as client registration approaches. MCP Client A / B / C client_id metadata / dcr Authorization Server Remote MCP Server 仕様上の選択肢を選ぶだけではなく、サービスとしての trust policyが必要になる。 未知のクライアントを許すのか。 redirect_uriをどう検証するのか。 認可画面に何を表示するのか。 3rd partyと分けて管理するのか。
12. 12 MCP toolは、API endpointというより「業務行為」に見える 論点2：scopeとtoolの粒度をどう対応させるか read 請求書を見る 情報を見る write 請求書を作る データを作る external 請求書を送る 外部へ影響 scopeはAPI都合だけでなく「 AIにどの業務行為を任せるか」で考える必要がある 細かすぎるとUXが悪い。粗すぎると権限が強すぎる。
13. 13 tokenとscopeだけでは、業務上OKとは限らない 論点3：既存ユーザーアクセス制御とどう接続するか OAuth Access Token MCP tool call 既存サービス 権限モデル 実行可 否 ユーザー / テナント・事業所 / ロール / 契約状態 / API権限 / 監査要件 既存の認可世界を担保しながら、 MCPの認可世界を接続する。
14. 14 MCPサーバー向けのtokenか、上流API向けのtokenか 論点4：audience / token境界を曖昧にしない MCP Authorization 2025-11-25: clients MUST include resource parameter; MCP servers MUST validate tokens were issued for their intended audience and MUST NOT accept/transit other tokens. 良い境界 MCP Client Remote MCP resource=mcp freee API 適切な境界で呼ぶ 危ない境界 MCP Client freee API 別audienceの token? × 問い 誰が 検証する？ どの audience？ 上流APIに は 何を渡す？
15. 15 ユーザーに見える委任と、下流APIを実行する権限を分けて考える 深掘り：MCP scopeとAPI scopeは同じ層ではない MCP Client MCP用scopeで toolを呼ぶ Remote MCP Server MCP tokenを検証 resource = mcp scope = mcp:invoice.create Authorization Server MCP向けtokenを発行 SaaS API API用tokenで実行 resource = api scope = invoice.write MCP scope ユーザーがAI / MCP Clientに委任する「業務能力」の境界。tool公開 ・consent・再認可UXに効く。 API scope Remote MCPが下流APIを安全に実行するための権限。resource / audience / TTL / revokeに効く。
16. 16 同じinsufficient_scopeでも、MCP側の不足とAPI側の不足は扱いを分ける 不足したscopeは「どの層で不足したか」で分岐する 1. Tool call 例: 請求書を作る 2. MCP check MCP scope user / tenant / tool 3. API check API scope token / audience 4. API call 業務APIを実行 MCP scopeが不足 403 + insufficient_scope。 ClientはStep-upでMCP scopeを増やす。 API scopeが不足：grant内 policy上OKならToken Exchange等でAPI 用tokenを狭く発行。 API scopeが不足：consent必要 ユーザーに見える能力が増えるなら追加認 可。高リスク操作なら確認。 業務権限そのものが不足している場合は、 scopeを増やしても実行不可。ユーザーのアクセス制御で denyする。
17. 17 下流APIの実装都合を、そのままユーザー向けscopeに漏らさない MCP scopeを広げるのは「委任能力」が変わるとき 広げるべきケース • AIに任せる業務能力が増える • ユーザーに説明すべきリスクが変わる • read → write → 外部サービス など境界が変わる •認可画面で表現すべき意味が変わる 広げない方がよいケース • 下流APIのscope分割が変わっただけ • APIの内部構成・マイクロサービス都合 • token exchangeに必要な一時的API scope • ユーザーに見える能力は変わらない 例：請求書 invoice.read 見る invoice.create 作る invoice.update 更新する invoice.send 外部へ送る 設計ルール： MCP scopeは「ユーザーに見える約束」。 API scope / policy / token cache は別状態で管理。
18. 18 MCP grantの寿命と、下流API実行tokenの寿命を同じにしない 案）API access_tokenはJIT・短命・狭い権限で扱う 必要scope判定 tool + args + user + tenant 発行 / 交換 resource / audience / scope / TTL を絞る API実行 API用tokenだけを上流 へ渡す 破棄 / 失効 保存しない。必要なら revoke MCP ≠ API 短期間だけ保持 操作単位または短TTLでcache。keyは user / tenant / client / resource / scope。 revokeの使いどころ refresh token / handle型 / 長めのtoken / 接続解除時はrevokeを検討。 MCP scopeとは分離 API tokenを捨ててもMCPの委任能力を毎回 revokeしない。高リスク操作は別途確認。
19. 19 scopeだけで完結させず、policy・grant・token lifecycleを一緒に設計する レイヤーを跨ぐ scope設計のチェックリスト 1 ユーザーに見える能力は何か MCP scopeはAIに任せる業務行為として説明できるか 2 下流APIの最小権限は何か tool + argsごとに必要API scope / resource / audienceを決められるか 3 不足時の経路はどれか MCP step-up / token exchange / 追加認可 / deny を切り分けたか 4 tokenをいつ捨てるか TTL、cache key、revoke、接続解除、権限変更時の扱いを決めたか 5 監査・説明できるか AIが何を試み、何を許可し、どのAPI scopeで実行したかを追えるか 実装判断： MCP scopeは必要条件。最終的な実行可否は、ユーザーアクセス制御 + API token境界 + runtime policyで決める。
20. 20 403を返して終わり、では体験にならない 論点5：認可エラーを AI越しに伝える MCP Authorization 2025-11-25: insufficient_scope errors can include required scopes and clients should attempt step-up authorization when appropriate. User AI Host MCP Client Remote MCP Server freee API 403 insufficient_scope 追加認可が必要？ / どのscopeが足りない？ / AIはユーザーにどう説明する？ / リトライしてよい？
21. 21 仕様・既存基盤・プロダクト体験の分担を決める 実装方針として大切にしたいこと 1 既存のuser / tenant / role / API権限を最終的な実行可否 に反映する。 既存の権限モデルを バイパスしない 2 scopeは業務行為と して 設計する API endpointの集合ではな く、AIに任せる操作の重さで考 える。 3 失敗・再認可・監査ま で 認可の一部 tokenがあるかだけでなく、権 限不足時の誘導とログを含め て設計する。 Remote MCPでは、MCP層だけで完結する認可設計はほぼない。
22. 22 明日から設計レビューで使えるチェックリスト Remote MCPを出す人へ持ち帰っていただきたいこと 1 責任境界 Local→Remoteはデプロイ先変更ではなく、責任境界の変更 2 Resource Server Remote MCP ServerをOAuth Resource Serverとして見る 3 Scope設計 scopeはAPI都合だけでなく、AIに任せる業務行為で考える 4 既存権限 既存のアクセス制御モデルをバイパスしない 5 UX / 監査 認可エラー、再認可、監査ログまで含めて設計する
23. まとめ Remote MCP化とは、 APIをAIに開放することではなく、 AIに業務操作を委任するための 認可境界を設計し直すこと。 Local MCPにも得意領域がある。 Remote MCPを選ぶなら 委任・アクセス制御・運用責任を正面から設計する。
24. スモールビジネスを、世界の主役に。