diff --git a/docs/tools/mcp-server.md b/docs/tools/mcp-server.md
index e128a895bd..47f169ba38 100644
--- a/docs/tools/mcp-server.md
+++ b/docs/tools/mcp-server.md
@@ -930,7 +930,7 @@ This is the default transport for running local servers.
 gemini mcp add <name> <command> [args...]
 
 # Example: Adding a local server
-gemini mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3
+gemini mcp add -e API_KEY=123 my-stdio-server /path/to/server arg1 arg2 arg3
 
 # Example: Adding a local python server
 gemini mcp add python-server python server.py --port 8080
@@ -948,7 +948,7 @@ gemini mcp add --transport http <name> <url>
 gemini mcp add --transport http http-server https://api.example.com/mcp/
 
 # Example: Adding an HTTP server with an authentication header
-gemini mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"
+gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/
 ```
 
 #### Adding an SSE server
@@ -963,7 +963,7 @@ gemini mcp add --transport sse <name> <url>
 gemini mcp add --transport sse sse-server https://api.example.com/sse/
 
 # Example: Adding an SSE server with an authentication header
-gemini mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"
+gemini mcp add --transport sse --header "Authorization: Bearer abc123" secure-sse https://api.example.com/sse/
 ```
 
 ### Listing Servers (`gemini mcp list`)
diff --git a/packages/cli/src/commands/mcp/add.test.ts b/packages/cli/src/commands/mcp/add.test.ts
index 369d935185..374d06c749 100644
--- a/packages/cli/src/commands/mcp/add.test.ts
+++ b/packages/cli/src/commands/mcp/add.test.ts
@@ -56,7 +56,7 @@ describe('mcp add command', () => {
 
   it('should add a stdio server to project settings', async () => {
     await parser.parseAsync(
-      'add my-server /path/to/server arg1 arg2 -e FOO=bar',
+      'add -e FOO=bar my-server /path/to/server arg1 arg2',
     );
 
     expect(mockSetValue).toHaveBeenCalledWith(
@@ -72,9 +72,27 @@ describe('mcp add command', () => {
     );
   });
 
+  it('should handle multiple env vars before positional args', async () => {
+    await parser.parseAsync(
+      'add -e FOO=bar -e BAZ=qux my-server /path/to/server',
+    );
+
+    expect(mockSetValue).toHaveBeenCalledWith(
+      SettingScope.Workspace,
+      'mcpServers',
+      {
+        'my-server': {
+          command: '/path/to/server',
+          args: [],
+          env: { FOO: 'bar', BAZ: 'qux' },
+        },
+      },
+    );
+  });
+
   it('should add an sse server to user settings', async () => {
     await parser.parseAsync(
-      'add --transport sse sse-server https://example.com/sse-endpoint --scope user -H "X-API-Key: your-key"',
+      'add --transport sse --scope user -H "X-API-Key: your-key" sse-server https://example.com/sse-endpoint',
     );
 
     expect(mockSetValue).toHaveBeenCalledWith(SettingScope.User, 'mcpServers', {
@@ -87,7 +105,7 @@ describe('mcp add command', () => {
 
   it('should add an http server to project settings', async () => {
     await parser.parseAsync(
-      'add --transport http http-server https://example.com/mcp -H "Authorization: Bearer your-token"',
+      'add --transport http -H "Authorization: Bearer your-token" http-server https://example.com/mcp',
     );
 
     expect(mockSetValue).toHaveBeenCalledWith(
diff --git a/packages/cli/src/commands/mcp/add.ts b/packages/cli/src/commands/mcp/add.ts
index 16c5383a85..a08dcb6526 100644
--- a/packages/cli/src/commands/mcp/add.ts
+++ b/packages/cli/src/commands/mcp/add.ts
@@ -173,6 +173,7 @@ export const addCommand: CommandModule = {
         describe: 'Set environment variables (e.g. -e KEY=value)',
         type: 'array',
         string: true,
+        nargs: 1,
       })
       .option('header', {
         alias: 'H',
@@ -180,6 +181,7 @@ export const addCommand: CommandModule = {
           'Set HTTP headers for SSE and HTTP transports (e.g. -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123")',
         type: 'array',
         string: true,
+        nargs: 1,
       })
       .option('timeout', {
         describe: 'Set connection timeout in milliseconds',