MCP servers with Gemini CLI

概要

Model Context Protocol（MCP）サーバーへの接続設定と、ツールの発見・実行の仕組み。settings.json の mcpServers でサーバーを定義し、mcp オブジェクトでグローバルな規則を定める。

仕様

グローバル設定（`mcp`）

mcp.serverCommand（string）: MCP サーバーを起動するグローバルコマンド
mcp.allowed（string[]）: 設定すると、この一覧（mcpServers のキーと一致するもの）のサーバーにのみ接続する
mcp.excluded（string[]）: 接続しないサーバー

サーバーごとの設定（`mcpServers`）

必須（いずれか 1 つ）:

キー	内容
`command`	Stdio transport 用の実行ファイルのパス
`url`	SSE のエンドポイント URL
`httpUrl`	HTTP streaming のエンドポイント URL

任意:

キー	既定	内容
`args`	—	Stdio transport のコマンドライン引数
`headers`	—	`url` / `httpUrl` 使用時のカスタム HTTP ヘッダー
`env`	—	サーバープロセスの環境変数。`$VAR_NAME` / `${VAR_NAME}`（全プラットフォーム）、`%VAR_NAME%`（Windows のみ）で参照できる
`cwd`	—	Stdio transport の作業ディレクトリ
`timeout`	600,000 ms（10 分）	リクエストのタイムアウト
`trust`	`false`	`true` でこのサーバーのすべてのツール呼び出し確認を飛ばす
`includeTools`	—	このサーバーから使うツール名の allowlist。指定しなければサーバーの全ツールが既定で有効
`excludeTools`	—	除外するツール名。`excludeTools` は `includeTools` に優先する。両方に載っているツールは除外される
`targetAudience`	—	IAP 保護されたアプリで allowlist された OAuth Client ID。`authProviderType: 'service_account_impersonation'` と併用
`targetServiceAccount`	—	impersonate する Google Cloud サービスアカウントのメールアドレス

環境変数の展開

env ブロック内で環境変数が自動展開される
POSIX / Bash 構文 $VARIABLE_NAME と ${VARIABLE_NAME} は全プラットフォーム、%VARIABLE_NAME% は Windows 実行時のみ
現在の環境に定義されていない変数は空文字列に解決される

環境のサニタイズ

MCP サーバープロセスを起動する際、既定でホストプロセスから継承した機微な環境変数を redact する。対象は
- コアのプロジェクトキー（GEMINI_API_KEY、GOOGLE_API_KEY など）
- 機微パターンに一致する変数（*TOKEN*、*SECRET*、*PASSWORD*、*KEY*、*AUTH*、*CREDENTIAL*）
- 証明書と秘密鍵のパターン
サーバー設定の env プロパティで明示した変数（extension 由来のものを含む）は信頼され、自動 redaction の対象外になる
明示的に定義する場合でも、秘密をハードコードせず環境変数展開（"MY_KEY": "$MY_KEY"）を使うことが推奨されている

リモートサーバーの OAuth

SSE または HTTP transport のリモート MCP サーバーで OAuth 2.0 に対応する。

OAuth discovery に対応するサーバーでは、OAuth 設定を省略して自動発見に任せられる

OAuth 設定プロパティ:

プロパティ	内容
`enabled`	このサーバーで OAuth を有効にする
`clientId`	クライアント ID（dynamic registration では任意）
`clientSecret`	クライアントシークレット（public client では任意）
`authorizationUrl`	認可エンドポイント（省略時は自動発見）
`tokenUrl`	トークンエンドポイント（省略時は自動発見）
`scopes`	必要なスコープ
`redirectUri`	カスタムリダイレクト URI。既定は OS が割り当てるランダムポート（`http://localhost:<random-port>/oauth/callback`）
`tokenParamName`	SSE URL でトークンを渡すクエリパラメータ名
`audiences`	トークンが有効な audience

トークン管理:

~/.gemini/mcp-oauth-tokens.json に安全に保存される
refresh token がある場合、期限切れ時に更新される
接続の試行ごとに検証され、無効・期限切れなら片付けられる

authProviderType:

値	内容
`dynamic_discovery`	既定。サーバーから OAuth 設定を自動発見する
`google_credentials`	Google Application Default Credentials（ADC）を使う。このプロバイダでは必要なスコープの指定が必須
`service_account_impersonation`	Google Cloud サービスアカウントを impersonate する。IAP 保護されたサービス向け（Cloud Run サービス向けに設計された）

service_account_impersonation では targetAudience と targetServiceAccount が必要。ローカルの ADC を使って対象のサービスアカウントと audience に対する OIDC ID トークンを生成し、それで認証する

ツールの命名と名前空間

すべての MCP ツールに無条件で FQN mcp_{serverName}_{toolName} が割り当てられる
ツールレジストリが FQN と元のサーバー識別のメタデータ対応を保持する
2 つのサーバーが同じエイリアスを持ち、同名のツールを提供すると、最後に登録されたツールが前のものを上書きする
MCP サーバー名にアンダースコア（_）を使わない。 ポリシーパーサーは FQN を mcp_ 接頭辞直後の最初のアンダースコアで分割するため、ワイルドカードルールとセキュリティポリシーが黙って機能しなくなりうる

名前のサニタイズ:

英数字・_・-・.・: 以外の文字はアンダースコアに置き換えられる
63 文字を超える名前は中間を ... に置き換えて切り詰められる

スキーマの処理

Gemini API 互換のためツールのパラメータスキーマがサニタイズされる。

$schema プロパティは削除される
additionalProperties は取り除かれる
default を持つ anyOf は既定値が削除される（Vertex AI 互換のため）
ネストしたスキーマにも再帰的に適用される

接続の管理

ツールの登録に成功したサーバーは接続を維持する
使えるツールを提供しないサーバーは接続が閉じられる
最終的なサーバー状態は CONNECTED または DISCONNECTED になる

ツール実行のフロー

trust が true のサーバーは確認をスキップする
動的な allow-list をサーバー単位（serverName）とツール単位（serverName.toolName）で保持する
確認が必要なとき、ユーザーは「Proceed once」「Always allow this tool」「Always allow this server」「Cancel」から選ぶ
実行時は引数をツールのスキーマに対して検証してから呼び出す
実行結果は llmContent（モデルのコンテキスト向けの生の応答パート）と returnDisplay（ユーザー表示向けの整形出力。多くは Markdown のコードブロック内の JSON）を含む

操作コマンド

/mcp で設定済みサーバーとツールを一覧する（サブコマンドは facts/gemini-cli/commands.md）
/mcp auth <serverName> で特定サーバーの OAuth 認証、トークン失効時の再認証を行う

設定

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  },
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": { "API_KEY": "$MY_API_TOKEN" },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "googleCloudServer": {
      "httpUrl": "https://my-gcp-service.run.app/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/userinfo.email"]
      }
    }
  }
}