Merge branch 'main' into main

Author: akabarki76

docs/cli/authentication.md

@@ -33,12 +33,17 @@ The Gemini CLI requires you to authenticate with Google's AI services. On initia
         ```bash
         export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
         ```
-      - For repeated use, you can add the environment variable to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file:
+      - For repeated use, you can add the environment variable to your [.env file](#persisting-environment-variables-with-env-files).
+
+      - Alternatively you can export the API key from your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file:
+
         ```bash
         echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc
         source ~/.bashrc
         ```
 
+        :warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.
+
 3.  **Vertex AI:**
     - Obtain your Google Cloud API key: [Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser)
       - Set the `GOOGLE_API_KEY` environment variable. In the following methods, replace `YOUR_GOOGLE_API_KEY` with your Vertex AI API key:
@@ -63,17 +68,25 @@ The Gemini CLI requires you to authenticate with Google's AI services. On initia
           export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
           export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1
           ```
-        - For repeated use, you can add the environment variables to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands add the environment variables to a `~/.bashrc` file:
+        - For repeated use, you can add the environment variables to your [.env file](#persisting-environment-variables-with-env-files)
+
+        - Alternatively you can export the environment variables from your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands add the environment variables to a `~/.bashrc` file:
+
           ```bash
           echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc
           echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc
           source ~/.bashrc
           ```
+
+          :warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.
+
 4.  **Cloud Shell:**
     - This option is only available when running in a Google Cloud Shell environment.
     - It automatically uses the credentials of the logged-in user in the Cloud Shell environment.
     - This is the default authentication method when running in Cloud Shell and no other method is configured.
 
+          :warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it.
+
 ### Persisting Environment Variables with `.env` Files
 
 You can create a **`.gemini/.env`** file in your project directory or in your home directory. Creating a plain **`.env`** file also works, but `.gemini/.env` is recommended to keep Gemini variables isolated from other tools.
@@ -107,3 +120,24 @@ GOOGLE_CLOUD_PROJECT="your-project-id"
 GEMINI_API_KEY="your-gemini-api-key"
 EOF
 ```
+
+## Non-Interactive Mode / Headless Environments
+
+When running the Gemini CLI in a non-interactive environment, you cannot use the interactive login flow.
+Instead, you must configure authentication using environment variables.
+
+The CLI will automatically detect if it is running in a non-interactive terminal and will use one of the
+following authentication methods if available:
+
+1.  **Gemini API Key:**
+    - Set the `GEMINI_API_KEY` environment variable.
+    - The CLI will use this key to authenticate with the Gemini API.
+
+2.  **Vertex AI:**
+    - Set the `GOOGLE_GENAI_USE_VERTEXAI=true` environment variable.
+    - **Using an API Key:** Set the `GOOGLE_API_KEY` environment variable.
+    - **Using Application Default Credentials (ADC):**
+      - Run `gcloud auth application-default login` in your environment to configure ADC.
+      - Ensure the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` environment variables are set.
+
+If none of these environment variables are set in a non-interactive session, the CLI will exit with an error.

docs/tools/mcp-server.md

@@ -95,6 +95,90 @@ Each server configuration supports the following properties:
 - **`includeTools`** (string[]): List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (whitelist behavior). If not specified, all tools from the server are enabled by default.
 - **`excludeTools`** (string[]): List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server. **Note:** `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded.
 
+### OAuth Support for Remote MCP Servers
+
+The Gemini CLI supports OAuth 2.0 authentication for remote MCP servers using SSE or HTTP transports. This enables secure access to MCP servers that require authentication.
+
+#### Automatic OAuth Discovery
+
+For servers that support OAuth discovery, you can omit the OAuth configuration and let the CLI discover it automatically:
+
+```json
+{
+  "mcpServers": {
+    "discoveredServer": {
+      "url": "https://api.example.com/sse"
+    }
+  }
+}
+```
+
+The CLI will automatically:
+
+- Detect when a server requires OAuth authentication (401 responses)
+- Discover OAuth endpoints from server metadata
+- Perform dynamic client registration if supported
+- Handle the OAuth flow and token management
+
+#### Authentication Flow
+
+When connecting to an OAuth-enabled server:
+
+1. **Initial connection attempt** fails with 401 Unauthorized
+2. **OAuth discovery** finds authorization and token endpoints
+3. **Browser opens** for user authentication (requires local browser access)
+4. **Authorization code** is exchanged for access tokens
+5. **Tokens are stored** securely for future use
+6. **Connection retry** succeeds with valid tokens
+
+#### Browser Redirect Requirements
+
+**Important:** OAuth authentication requires that your local machine can:
+
+- Open a web browser for authentication
+- Receive redirects on `http://localhost:7777/oauth/callback`
+
+This feature will not work in:
+
+- Headless environments without browser access
+- Remote SSH sessions without X11 forwarding
+- Containerized environments without browser support
+
+#### Managing OAuth Authentication
+
+Use the `/mcp auth` command to manage OAuth authentication:
+
+```bash
+# List servers requiring authentication
+/mcp auth
+
+# Authenticate with a specific server
+/mcp auth serverName
+
+# Re-authenticate if tokens expire
+/mcp auth serverName
+```
+
+#### OAuth Configuration Properties
+
+- **`enabled`** (boolean): Enable OAuth for this server
+- **`clientId`** (string): OAuth client identifier (optional with dynamic registration)
+- **`clientSecret`** (string): OAuth client secret (optional for public clients)
+- **`authorizationUrl`** (string): OAuth authorization endpoint (auto-discovered if omitted)
+- **`tokenUrl`** (string): OAuth token endpoint (auto-discovered if omitted)
+- **`scopes`** (string[]): Required OAuth scopes
+- **`redirectUri`** (string): Custom redirect URI (defaults to `http://localhost:7777/oauth/callback`)
+- **`tokenParamName`** (string): Query parameter name for tokens in SSE URLs
+
+#### Token Management
+
+OAuth tokens are automatically:
+
+- **Stored securely** in `~/.gemini/mcp-oauth-tokens.json`
+- **Refreshed** when expired (if refresh tokens are available)
+- **Validated** before each connection attempt
+- **Cleaned up** when invalid or expired
+
 ### Example Configurations
 
 #### Python MCP Server (Stdio)

packages/cli/src/gemini.tsx

@@ -17,7 +17,6 @@ import { start_sandbox } from './utils/sandbox.js';
 import {
   LoadedSettings,
   loadSettings,
-  USER_SETTINGS_PATH,
   SettingScope,
 } from './config/settings.js';
 import { themeManager } from './ui/themes/theme-manager.js';
@@ -40,6 +39,7 @@ import {
 } from '@google/gemini-cli-core';
 import { validateAuthMethod } from './config/auth.js';
 import { setMaxSizedBoxDebugging } from './ui/components/shared/MaxSizedBox.js';
+import { validateNonInteractiveAuth } from './validateNonInterActiveAuth.js';
 
 function getNodeMemoryArgs(config: Config): string[] {
   const totalMemoryMB = os.totalmem() / (1024 * 1024);
@@ -320,33 +320,8 @@ async function loadNonInteractiveConfig(
     await finalConfig.initialize();
   }
 
-  return await validateNonInterActiveAuth(
+  return await validateNonInteractiveAuth(
     settings.merged.selectedAuthType,
     finalConfig,
   );
 }
-
-async function validateNonInterActiveAuth(
-  selectedAuthType: AuthType | undefined,
-  nonInteractiveConfig: Config,
-) {
-  // making a special case for the cli. many headless environments might not have a settings.json set
-  // so if GEMINI_API_KEY is set, we'll use that. However since the oauth things are interactive anyway, we'll
-  // still expect that exists
-  if (!selectedAuthType && !process.env.GEMINI_API_KEY) {
-    console.error(
-      `Please set an Auth method in your ${USER_SETTINGS_PATH} OR specify GEMINI_API_KEY env variable file before running`,
-    );
-    process.exit(1);
-  }
-
-  selectedAuthType = selectedAuthType || AuthType.USE_GEMINI;
-  const err = validateAuthMethod(selectedAuthType);
-  if (err != null) {
-    console.error(err);
-    process.exit(1);
-  }
-
-  await nonInteractiveConfig.refreshAuth(selectedAuthType);
-  return nonInteractiveConfig;
-}

packages/cli/src/ui/commands/mcpCommand.test.ts

@@ -30,6 +30,13 @@ vi.mock('@google/gemini-cli-core', async (importOriginal) => {
     ...actual,
     getMCPServerStatus: vi.fn(),
     getMCPDiscoveryState: vi.fn(),
+    MCPOAuthProvider: {
+      authenticate: vi.fn(),
+    },
+    MCPOAuthTokenStorage: {
+      getToken: vi.fn(),
+      isTokenExpired: vi.fn(),
+    },
   };
 });
 
@@ -810,4 +817,163 @@ describe('mcpCommand', () => {
       }
     });
   });
+
+  describe('auth subcommand', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('should list OAuth-enabled servers when no server name is provided', async () => {
+      const context = createMockCommandContext({
+        services: {
+          config: {
+            getMcpServers: vi.fn().mockReturnValue({
+              'oauth-server': { oauth: { enabled: true } },
+              'regular-server': {},
+              'another-oauth': { oauth: { enabled: true } },
+            }),
+          },
+        },
+      });
+
+      const authCommand = mcpCommand.subCommands?.find(
+        (cmd) => cmd.name === 'auth',
+      );
+      expect(authCommand).toBeDefined();
+
+      const result = await authCommand!.action!(context, '');
+      expect(isMessageAction(result)).toBe(true);
+      if (isMessageAction(result)) {
+        expect(result.messageType).toBe('info');
+        expect(result.content).toContain('oauth-server');
+        expect(result.content).toContain('another-oauth');
+        expect(result.content).not.toContain('regular-server');
+        expect(result.content).toContain('/mcp auth <server-name>');
+      }
+    });
+
+    it('should show message when no OAuth servers are configured', async () => {
+      const context = createMockCommandContext({
+        services: {
+          config: {
+            getMcpServers: vi.fn().mockReturnValue({
+              'regular-server': {},
+            }),
+          },
+        },
+      });
+
+      const authCommand = mcpCommand.subCommands?.find(
+        (cmd) => cmd.name === 'auth',
+      );
+      const result = await authCommand!.action!(context, '');
+
+      expect(isMessageAction(result)).toBe(true);
+      if (isMessageAction(result)) {
+        expect(result.messageType).toBe('info');
+        expect(result.content).toBe(
+          'No MCP servers configured with OAuth authentication.',
+        );
+      }
+    });
+
+    it('should authenticate with a specific server', async () => {
+      const mockToolRegistry = {
+        discoverToolsForServer: vi.fn(),
+      };
+      const mockGeminiClient = {
+        setTools: vi.fn(),
+      };
+
+      const context = createMockCommandContext({
+        services: {
+          config: {
+            getMcpServers: vi.fn().mockReturnValue({
+              'test-server': {
+                url: 'http://localhost:3000',
+                oauth: { enabled: true },
+              },
+            }),
+            getToolRegistry: vi.fn().mockResolvedValue(mockToolRegistry),
+            getGeminiClient: vi.fn().mockReturnValue(mockGeminiClient),
+          },
+        },
+      });
+
+      const { MCPOAuthProvider } = await import('@google/gemini-cli-core');
+
+      const authCommand = mcpCommand.subCommands?.find(
+        (cmd) => cmd.name === 'auth',
+      );
+      const result = await authCommand!.action!(context, 'test-server');
+
+      expect(MCPOAuthProvider.authenticate).toHaveBeenCalledWith(
+        'test-server',
+        { enabled: true },
+        'http://localhost:3000',
+      );
+      expect(mockToolRegistry.discoverToolsForServer).toHaveBeenCalledWith(
+        'test-server',
+      );
+      expect(mockGeminiClient.setTools).toHaveBeenCalled();
+
+      expect(isMessageAction(result)).toBe(true);
+      if (isMessageAction(result)) {
+        expect(result.messageType).toBe('info');
+        expect(result.content).toContain('Successfully authenticated');
+      }
+    });
+
+    it('should handle authentication errors', async () => {
+      const context = createMockCommandContext({
+        services: {
+          config: {
+            getMcpServers: vi.fn().mockReturnValue({
+              'test-server': { oauth: { enabled: true } },
+            }),
+          },
+        },
+      });
+
+      const { MCPOAuthProvider } = await import('@google/gemini-cli-core');
+      (
+        MCPOAuthProvider.authenticate as ReturnType<typeof vi.fn>
+      ).mockRejectedValue(new Error('Auth failed'));
+
+      const authCommand = mcpCommand.subCommands?.find(
+        (cmd) => cmd.name === 'auth',
+      );
+      const result = await authCommand!.action!(context, 'test-server');
+
+      expect(isMessageAction(result)).toBe(true);
+      if (isMessageAction(result)) {
+        expect(result.messageType).toBe('error');
+        expect(result.content).toContain('Failed to authenticate');
+        expect(result.content).toContain('Auth failed');
+      }
+    });
+
+    it('should handle non-existent server', async () => {
+      const context = createMockCommandContext({
+        services: {
+          config: {
+            getMcpServers: vi.fn().mockReturnValue({
+              'existing-server': {},
+            }),
+          },
+        },
+      });
+
+      const authCommand = mcpCommand.subCommands?.find(
+        (cmd) => cmd.name === 'auth',
+      );
+      const result = await authCommand!.action!(context, 'non-existent');
+
+      expect(isMessageAction(result)).toBe(true);
+      if (isMessageAction(result)) {
+        expect(result.messageType).toBe('error');
+        expect(result.content).toContain("MCP server 'non-existent' not found");
+      }
+    });
+  });
 });