docs(mcp): add Gemini CLI native HTTP config and mcp_orbit scope
What does this MR do and why?
Adds a Gemini CLI section to docs/source/remote/access/mcp.md documenting the
native HTTP MCP transport config, including the mcp_orbit OAuth scope that
Gemini CLI must request explicitly. Without this scope, native HTTP clients
fail to authenticate to the Orbit MCP endpoint even when already signed in to
GitLab.
The customer's original config in the issue already used httpUrl, which is
the documented field for Gemini CLI's streaming HTTP transport (url is
reserved for SSE). The actual fix is the missing oauth.scopes: ["mcp_orbit"]
block, not a different URL field.
Related Issues
Closes #819 (closed)
Testing
npx markdownlint-cli2 docs/source/remote/access/mcp.md passes with 0 errors.
- This merge request does not introduce any performance regression.
Note on the pipeline: the failed jobs on this fork's pipeline (
unit-test,integration-test,corpus-smoke-test,docker-build-mr, and several*-version-checkjobs) all fail before their scripts run. The job logs showPulling docker image gitlab.com:443/ujwal240/dependency_proxy/containers/...returning a 404 ("unexpected end of JSON input"), so thealwayspull policy fails the job immediately. The CI template resolves the Dependency Proxy prefix to the pipeline's own namespace, and a personal fork namespace doesn't have that proxy populated the waygitlab-orgdoes.unit-test,integration-test, andcorpus-smoke-testall pass onmain, and this change only touches a markdown file, so these failures are a fork CI/Dependency-Proxy environment issue, unrelated to this MR's content.
Agent context — long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered
Changes to docs/source/remote/access/mcp.md:
- Prerequisites: added a bullet noting native HTTP MCP clients must include
the
mcp_orbitOAuth scope. - Connect your MCP client: added a "Gemini CLI" subsection with a working
~/.gemini/settings.jsonexample usinghttpUrl+oauth.enabled: true+oauth.scopes: ["mcp_orbit"]. - Added a
[!note]troubleshooting block: if a native HTTP client fails to authenticate, addoauth.scopes: ["mcp_orbit"]to its MCP server config.
On the httpUrl vs url/type question raised in the issue: per Gemini
CLI's documented MCP server schema, httpUrl is the field for streamable HTTP
transport and url is reserved for SSE. The customer's failing config in the
issue already used httpUrl, so this MR keeps that field and adds only the
missing oauth block.