MCPサーバーにおけるOAuthトークンの共有永続化とワークツリー間の認証維持
MCP (Model Context Protocol) サーバーにおいて、作業用ワークツリーごとに認証が切れる問題を、共有ストレージの導入により解決した。
課題
アクセストークンを Git worktree 配下の一時的なディレクトリやローカルのキャッシュフォルダに保持していたため、新しい作業（Story）ごとにワークツリーを作成・移動すると、キャッシュが引き継がれず、毎回 OAuth の認可フローが発生していた。
解決策
- グローバルな共有ストレージへの配置:
- トークンの保存先をリポジトリ（ワークツリー）配下ではなく、ユーザーのホームディレクトリ直下（例: ユーザー設定ディレクトリ）などの、ワークツリーから独立した場所に変更。
- キャッシュの共有:
- 複数の作業ディレクトリ（worktrees）から、単一のグローバルキャッシュを参照するように設計を変更。
- これにより、一度認可を完了すれば、他のどのワークツリーで AI エージェント（Codex, Claude Code 等）を起動しても、同じ認証状態が維持される。
- トークンの自動更新:
- 共有されたリフレッシュトークンを用いて、期限切れの際もバックグラウンドで自動更新し、開発者の手を止めない。
結論
AI エージェントとワークツリーを組み合わせた開発環境において、認証（OAuthキャッシュ）は「リポジトリ（作業空間）」ではなく「ユーザー（環境）」に紐づくべきである。グローバルな共有ストレージを活用することで、頻繁な認証ストレスを解消し、作業継続性を劇的に向上させることができる。