feat(cli): add OAuth configuration flags to mcp add (#3442)

* feat(cli): Add OAuth redirect URI support to  command

- Add --oauth-redirect-uri, --oauth-client-id, --oauth-client-secret,
  --oauth-authorization-url, --oauth-token-url, and --oauth-scopes flags
  to the  command
- Enable configuration of custom OAuth redirect URIs for remote/cloud
  server deployments (fixes hardcoded localhost issue)
- Document auth.redirectUri in both developer and user-facing MCP docs
- Add comprehensive tests for OAuth configuration via CLI
- Update documentation with examples and guidance for remote deployments

Fixes #3336

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

* refactor(cli): harden OAuth flag handling in mcp add

- Reject combining --oauth-* flags with --transport stdio to surface the
  mistake instead of silently persisting an unused oauth config
- Rebuild OAuth config via single spread expression; drop the prior
  mutate-then-check pattern and the post-hoc enabled assignment
- Trim each scope token after comma split so "read, write" no longer
  stores leading/trailing whitespace
- Cover both new behaviors with tests; add missing --oauth-client-secret
  row and stdio-incompatibility note to the user MCP docs

* test(cli): use explicit Vitest/Yargs type imports in mcp add tests

Switch from namespace-style 'vi.Mock' and 'yargs.Argv' references to
explicit 'Mock' and 'Argv' imports, and replace the narrow
'(code?: number) => never' cast on the process.exit mock with
'typeof process.exit' so it tracks the current Node signature.

---------

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

docs/developers/tools/mcp-server.md

@@ -158,16 +158,28 @@ When connecting to an OAuth-enabled server:
 
 #### Browser Redirect Requirements
 
-**Important:** OAuth authentication requires that your local machine can:
+**Important:** OAuth authentication requires that the redirect URI is accessible:
 
-- Open a web browser for authentication
-- Receive redirects on `http://localhost:7777/oauth/callback`
+- **Default behavior**: Redirects to `http://localhost:7777/oauth/callback` (works for local setups)
+- **Custom redirect URI**: Use `--oauth-redirect-uri` or configure `redirectUri` in settings.json to specify a different URL
 
-This feature will not work in:
+For **remote/cloud server deployments** (e.g., web terminals, SSH sessions, cloud IDEs):
+
+- The default `localhost` redirect will NOT work
+- You MUST configure a custom `redirectUri` pointing to a publicly accessible URL
+- The user's browser must be able to reach this URL and redirect back to the server
+
+Example for remote servers:
+
+```bash
+qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
+  --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback
+```
+
+OAuth will not work in:
 
 - Headless environments without browser access
-- Remote SSH sessions without X11 forwarding
-- Containerized environments without browser support
+- Environments where the configured `redirectUri` is unreachable from the user's browser
 
 #### Managing OAuth Authentication
 
@@ -192,7 +204,7 @@ Use the `/mcp auth` command to manage OAuth authentication:
 - **`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`)
+- **`redirectUri`** (string): Custom redirect URI. **Critical for remote deployments**: Defaults to `http://localhost:7777/oauth/callback`. When running Qwen Code on remote/cloud servers, set this to a publicly accessible URL (e.g., `https://your-server.com/oauth/callback`). Can be configured via `qwen mcp add --oauth-redirect-uri` or directly in settings.json.
 - **`tokenParamName`** (string): Query parameter name for tokens in SSE URLs
 - **`audiences`** (string[]): Audiences the token is valid for
 
@@ -788,6 +800,12 @@ qwen mcp add [options] <name> <commandOrUrl> [args...]
 - `--description`: Set the description for the server.
 - `--include-tools`: A comma-separated list of tools to include.
 - `--exclude-tools`: A comma-separated list of tools to exclude.
+- `--oauth-client-id`: OAuth client ID for MCP server authentication.
+- `--oauth-client-secret`: OAuth client secret for MCP server authentication.
+- `--oauth-redirect-uri`: OAuth redirect URI (e.g., `https://your-server.com/oauth/callback`). Defaults to `http://localhost:7777/oauth/callback` for local setups. **Important for remote deployments**: When running Qwen Code on remote/cloud servers, set this to a publicly accessible URL.
+- `--oauth-authorization-url`: OAuth authorization URL.
+- `--oauth-token-url`: OAuth token URL.
+- `--oauth-scopes`: OAuth scopes (comma-separated).
 
 #### Adding an stdio server
 
@@ -832,6 +850,13 @@ qwen mcp add --transport sse sse-server https://api.example.com/sse/
 
 # Example: Adding an SSE server with an authentication header
 qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"
+
+# Example: Adding an OAuth-enabled SSE server
+qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
+  --oauth-client-id your-client-id \
+  --oauth-redirect-uri https://your-server.com/oauth/callback \
+  --oauth-authorization-url https://provider.example.com/authorize \
+  --oauth-token-url https://provider.example.com/token
 ```
 
 ### Managing Servers (`qwen mcp`)