docs(mcp): complete the Gemini Enterprise guide from end-to-end testing - #508
Merged
Conversation
The merged guide stops short of a working setup. Running it against a live
Gemini Enterprise app and the C1 gateway surfaced two required steps it
never mentions, and a full review of the page found contradictions between
sections written before and after that testing.
The two missing steps:
- Each user authorizes the connector themselves, from the Connectors
menu in the web app message box. Enabling actions as an administrator
authorizes nobody, and until a user authorizes there the assistant
answers that it has no C1 integration while the connector reads
Active. This was the last blocker and it is invisible from the admin
console.
- Reload custom actions takes about 30 seconds and holds the request
open, so the action table stays empty until it finishes. Leaving early
looks like a silent failure.
Corrections from the review:
- The Agent Registry section pointed at the import flow that this same
page says breaks tool discovery. Registering the server in the catalog
is now separated from importing it as a connector, with a warning
against the import.
- The client metadata document is not available on any tenant yet, so
the page no longer frames its 404 as a per-tenant rollout lag. A reader
hitting it has a real blocker, not a local mistake.
- Enabling actions no longer claims users can call them, since they
cannot until they authorize.
- The stage table claimed creating the data store and enabling APIs
depend on nothing, contradicting the roles table two sections down.
Both now name the role.
- Dropped "in C1 testing" hedging on four established facts, settled the
client secret on the single value Google documents, scoped the app
location to the optional path that actually uses it, and moved the
per-user caveat from Warning to Note, since it is not irreversible.
Verified: zero em dashes, no banned words, all anchors and internal links
resolve, all component tags balanced, placeholder conventions consistent.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
The guide named a single client ID, the C1-hosted one, which has not shipped. That left the reader with no way to finish and no explanation of why the value has to come from anywhere in particular. State the constraint plainly: Google publishes no client metadata document for Gemini Enterprise. /.well-known/oauth-client-metadata returns 404 on vertexaisearch.cloud.google.com, cloud.google.com, discoveryengine.googleapis.com, and accounts.google.com, and Google's own instructions are to register the MCP server as an OAuth client with your identity provider. Something has to host the document, so the section now presents both options in a table with their status, and the self-hosted path is the one that works today. The self-hosting steps go in an accordion rather than the main flow, since they become unnecessary once C1 hosts the document. A second accordion covers the two organization policies that block publishing it: domain restricted sharing, which rejects allUsers with HTTP 412 and needs an allowAll override rather than an allUsers entry, and public access prevention. The domain restricted sharing override is project-wide rather than bucket-scoped, so it carries a warning to publish from a dedicated project and remove the override once C1 hosts the document. Also moved the outbound-hostname aside into an accordion, since it applies to a minority of organizations and interrupted the org policy procedure. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The hosting options read as a choice between C1 and the customer, which frames a workaround as the design. A client metadata document describes a client, so the client's own vendor is the party whose publication of it carries weight. Google does not publish one for Gemini Enterprise today, and both of the other options exist only because of that gap. The options table now leads with Google and marks it the outcome to prefer, lists self-hosting as what works today, and lists the C1-hosted document as not yet available. The note says plainly that the C1 document is a stopgap rather than the end state, and tells the reader to switch to Google's URL and retire whatever they were hosting once Google publishes one. Also generalized the domain restricted sharing warning, which told the reader to remove the override once C1 hosts the document. The override should come out whenever they stop hosting, whichever way that happens. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Retested the API list from a clean state instead of carrying it forward. Only discoveryengine and orgpolicy are required. With connectors, integrations, secretmanager, and iam all disabled, a new data connector was created, authorized, activated, tool-discovered, and called successfully, and the role commands in the guide still worked. Disabling orgpolicy is the one case that fails, with SERVICE_DISABLED. The self-hosting walkthrough could not be completed as written: the JSON template's client_id used a placeholder domain that the Cloud Storage steps below it never produce, the reader was never told what filename to save the file as before a command referenced that name, and the verification curl came before the steps that create the document. Also documents the pricing step in the create flow, which the console requires and the guide skipped, adds the missing override for storage.publicAccessPrevention, and notes that org policy changes propagate in both directions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ran the guide from scratch against a brand-new Google Cloud project, following only what the page says. Everything through creating the data connector worked, including the domain restricted sharing accordion, which reproduced its 412 verbatim and recovered on the documented override in about ninety seconds. Two required steps were missing. A new Gemini Enterprise app has no identity provider, and the data store form blocks on it with Create greyed out and no hint about where to go. Google's own warning is that changing the provider later means deleting and recreating every access-controlled data store, so this belongs before the first data store exists, not discovered halfway through a wizard. A new app also has a subscription but no licensed users. Both now have their own section ahead of the client ID work. Also drops the pricing step to a conditional aside, since it is a property of which console you are in rather than of the account: the gen-app-builder wizard has four steps and the gemini-enterprise wizard has three. Adds roles/storage.admin, which the self-hosting path needs and the roles table never listed, and notes that a never-set allowedEgressFqdns constraint answers with NOT_FOUND rather than a value. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Built the whole thing again from an empty project, enabling only what the page asks for, and drove every step that has an API from the command line. A live tool call returned real tenant data, so the sequence here is now one that has been walked end to end rather than assembled from parts. The step that was missing is a user opening the Gemini Enterprise web app. Tool discovery runs as the signed-in user and fails until that user has signed in once, and the console never says so: Reload custom actions just reports that it failed, on a connector that reads Active with every setting correct. It cost most of a day to find, so it gets its own section before the reload, plus a userLicenses check for lastLoginTime. Agent Registry and Agent Gateway are not required, and this is now stated from evidence rather than from Google's documentation. A working connector reports use_agent_gateway_egress false, and a setup with no gateway, no registry and no authorization extension discovers tools and serves calls normally. Also adds command-line equivalents for the identity provider and licence assignment, quotes the API error that makes connector creation console-only, and replaces the reload troubleshooting rows, which blamed the API and the credentials for what is almost always a missing sign-in. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Read the page end to end as a customer would, and rendered it locally to check how it behaves rather than how the source looks. Required roles came before the table that explains the placeholders its commands use, and one of those placeholders was never explained at all. Roles now follow the values table, which gained rows for the project number and the email, both of which commands referenced out of nowhere. Licence assignment had the same problem in miniature: it asked for a subscription ID and a project number, and the command that finds the subscription came afterwards. That pair is now the other way round. Hosting the client metadata document was inside a collapsed accordion, which is the one path essentially every reader has to take today. Anyone reading top to bottom could skip the bucket entirely. It is a normal subsection now, and only the conditional org-policy fix stays collapsed. Rendering surfaced its own problems. The JSON payloads were single lines that ran off the edge of their code blocks, and the app-creation command had been squeezed into a bullet. Payloads are multi-line and the command has its own accordion. Also corrects a claim this page kept repeating: licences do not block creating the data store, they block tool discovery later. Adds the console equivalent for granting roles and a worked example for the egress constraint, so no step is command-only where a neighbour got both. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Testing showed neither Agent Registry nor Agent Gateway is required, so a section walking through both was inviting readers to build infrastructure that changes nothing about this integration. Its remaining advice was also the oldest material on the page, written before any of the current testing and never re-checked. The two parts worth keeping already lived elsewhere. Not importing the connector from the registry is a Note on the data store section and a troubleshooting row. The evidence that the gateway is unnecessary now sits in the FAQ answer that used to link here, so the answer stands on its own. Twenty-four lines shorter, one fewer heading, no dangling links. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ser role Final validation pass against the live lab, checking the claims that had been written from reasoning rather than from running them. The egress constraint was wrong twice over. Its name is discoveryengine.managed.allowedEgressFqdns, not discoveryengine.allowedEgressFqdns, and it is a boolean constraint that takes parameters rather than a list of allowed values, so the YAML on this page could not have applied. Both forms are now what the API accepts, confirmed by applying the corrected policy and removing it again. Its description also now says the constraint only reaches projects with VPC Service Controls or projects an organization has explicitly enrolled, which is most of the reason a reader will never meet it. The C1 navigation was stale. Registered clients live under AI, C1 Gateway, on the AI clients tab, with per-user rows on AI connections. Checking this also turned up something worth saying plainly: the Verified column shows the domain hosting your client metadata document, so a self-hosted one reads storage.googleapis.com and not a Google domain. The roles table only ever covered the administrator. End users need roles/discoveryengine.user to open the web app and call anything, and the Google console warns about exactly this while never naming the role. Verified unchanged: the project number command, the public access prevention policy, and both profile-menu paths, including the MCP server URL sitting at the top of AI connections. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
Author
|
@mindymo this is pretty much a total rewrite of the doc, again... but I have live verified all of this now e2e. |
The gateway publishes hundreds of tools and a data store can enable a hundred, which reads as a hard ceiling on what Gemini Enterprise can do. It is not one. Eight of the published tools are the code mode set: search_tools finds any tool the caller is allowed to reach and returns its schema, execute runs a short TypeScript program against them, and the vfs and guide tools give that program somewhere to work and something to read. Enable those eight and everything else stays reachable, so the budget goes on the handful of actions users ask for by name. Enabling actions also turned out to be scriptable, which this page had lumped in with creating the connector as console-only. Only creation and discovery are: enabledActions is an ordinary field, verified by writing a fourteenth action into a working connector and reading it back. Creating the connector stays console-only for the reason already given. Both commands are here, with the caveat that the field replaces rather than merges, and a note that none of this widens anyone's access, since every call is still evaluated against the caller's access profiles. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
mindymo
approved these changes
Aug 25, 2026
mindymo
left a comment
mindymo
left a comment
Collaborator
There was a problem hiding this comment.
Good on my end, ready to merge whenever you like.
The list I gave was eight tools and it should have been twelve. I built it by pattern-matching names rather than reading what the gateway actually publishes, and four fell out. get_execution is the one that mattered. execute answers inline only if the program finishes in about twenty five seconds; past that it returns a pending status and an execution id, and get_execution is what collects the result. Enabling execute without it means long runs cannot be recovered and the agent reports a failure for work that in fact succeeded, so that pairing now carries a warning. The other three are find_api_objects, count_api_objects and query_metrics, which answer lookup, count and reporting questions directly and save writing a program for them at all. All twelve are confirmed present in the published tool list and enabled on the reference connector. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rebuilds the Gemini Enterprise guide around a setup that was walked end to end in a brand-new Google Cloud project, driving every step that has an API from the command line. A live tool call returned real tenant data, so the sequence here is one that has actually been completed rather than assembled from parts.
The step that was missing
A user has to open the Gemini Enterprise web app once before tool discovery works.
Tool discovery runs as the signed-in user and fails until that user has signed in. Nothing in the admin console says so. Reload custom actions reports Failed to reload custom actions on a connector that reads Active, with every setting correct and every API enabled. It is only visible through
userLicenses, where a working user haslastLoginTimeand a broken one does not.This is now its own section before the reload, with the
userLicensescheck to confirm it, and it is the first row in the reload troubleshooting.Agent Registry and Agent Gateway are not required
The page said this on Google's authority. It now says it on evidence:
use_agent_gateway_egress: false, so its traffic never passes through Agent Gateway.Building a gateway, an authorization extension and an authorization policy changed nothing, so that section is now short and clearly marked as catalog listing only.
The required set, verified by building it
Required:
discoveryengine.googleapis.comandorgpolicy.googleapis.comdisableCustomMcpServerConnectoroverrideroles/discoveryengine.editor,roles/discoveryengine.user, androles/storage.adminfor the document bucketNot required, each disproved by direct test: Agent Gateway, Agent Registry, authorization extension and policy, and the Connectors, Application Integration, Secret Manager, IAM and Vertex AI APIs.
More of the setup is scriptable than the page admitted
Added command-line equivalents for the identity provider and licence assignment, both of which were console-only instructions before.
Creating the data connector is the one genuinely console-only step, and the page now quotes the API refusing it rather than asserting it:
It accepts only a pre-obtained access token, not the OAuth client configuration, so it cannot run the per-user authorization this integration depends on.
Other corrections
401onRefreshDataConnectorToolsis normal. The working project logs the same error and succeeds seconds later on retry. Added the log query to check a reload properly, since the console toast is not reliable.roles/storage.adminwas missing from the roles table, though self-hosting the document needs it.allowedEgressFqdnsconstraint answersNOT_FOUND, which looks like a failure and is not.Verification
Confirmed against the live setup: the domain restricted sharing
412and its recovery reproduced in two separate projects, at t+44s and t+88s. Both form traps hold, with PKCE unchecked and Use HTTP Basic Authentication checked by default. Zero em dashes and smart quotes, all in-page anchors resolve, component tags and code fences balanced.