How I built and verified one Gemini consultant MCP that works from both Google Antigravity and OpenAI Codex.

A developer built and verified a local TypeScript STDIO MCP server named 'gemini-consultant' that allows coding agents like Google Antigravity and OpenAI Codex to call the Gemini API for independent engineering opinions. The server exposes two tools—one for one-shot consultations with provenance tracking and one for safe configuration diagnostics—and enforces strict safety policies including an allowlist of Gemini models and rejection of oversized context.

Ahmed Yosry · @amu3dev Independent experiment; not an official Google or OpenAI project. Repository: https://github.com/amu3dev/gemini-consultant-mcp https://github.com/amu3dev/gemini-consultant-mcp · Release: https://github.com/amu3dev/gemini-consultant-mcp/releases/tag/v1.0.0 https://github.com/amu3dev/gemini-consultant-mcp/releases/tag/v1.0.0 Gemini-backed MCP tools and ask-gemini integrations for Codex already exist publicly. The original need here was narrower: let a primary coding agent ask Gemini for an independent engineering opinion without pasting a whole repository into a chat, giving the consultant write access, or hiding which model actually answered. The result is a local TypeScript STDIO MCP server named gemini-consultant . Antigravity and Codex can call the same server, while the calling agent remains the orchestrator. Antigravity or Codex ↓ local gemini-consultant MCP ↓ Gemini API Source and setup: https://github.com/amu3dev/gemini-consultant-mcp https://github.com/amu3dev/gemini-consultant-mcp An API makes a provider callable from application code. MCP makes a capability discoverable and invocable by an MCP client under a defined schema. The gap contains real engineering work: - define tools and validate their inputs; - load configuration without leaking credentials; - translate a review request into a provider request; - separate trusted instructions from supplied context; - expose safe operational diagnostics; - classify provider failures; - preserve requested-versus-used model provenance; - speak JSON-RPC over STDIO without corrupting stdout. The server is the adapter and policy enforcement point. It does not turn Gemini into a filesystem agent. The implementation runs compiled JavaScript locally over STDIO. TypeScript and the development runner are build-time tools; clients start the compiled server. STDIO keeps the integration local and avoids adding a network service to operate. The code is separated by responsibility: environment parsing, schemas, prompt construction, provider invocation, retry/error policy, and MCP tool registration. That separation made the safety properties testable without live provider calls. The server exposes exactly two tools: Accepts a required prompt and optional focused context, model, consultation mode, thinking choice, and output-token limit. It returns a one-shot answer with provenance. Returns only safe configuration: server version, default and allowed model IDs, output/context limits, and whether a key is configured. It never returns the key or a fragment of it. Gemini receives only the strings supplied in the tool call. The server does not read project files or automatically collect repository context. No filesystem, shell, Git, browser, URL-fetching, code-execution, or write tools are declared for Gemini. The caller prepares the packet: - exact task; - relevant excerpts, diff, requirements, and logs; - explicit constraints; - a statement of what was not supplied. Context is enclosed as supplied, untrusted reference material; the task is kept distinct. Oversized context is rejected instead of silently truncated. The response remains advice until the orchestrator verifies it. The server uses a configurable allowlist. The verified policy included: gemini-3.1-flash-lite for lightweight or free-tier checks; gemini-3.5-flash when stronger analysis is requested; gemini-3.1-pro-preview only when explicitly requested or paid quota is known to exist. Allowlisted means “permitted by this local server,” not “guaranteed available to this API project.” Provider access, billing, capacity, and quota remain separate. Thinking controls accept provider-default behavior, a supported thinking level, or a bounded thinking budget. A non-default level and a budget cannot be sent together. Invalid combinations are rejected before the provider call. Every successful consultation reports both the requested model and the model used. This makes silent substitution visible—and the implementation goes further: it never silently falls back. Across retries, the selected model stays unchanged. If that model cannot answer, the call fails with concise guidance. The orchestrator may later make a new, explicit request for another allowlisted model, but that is a new decision rather than a hidden fallback. This distinction is essential in a multi-model experiment. Without it, a “Gemini 3.5 Flash review” could quietly become evidence from a different model. Live verification exposed two different operational failures. gemini-3.5-flash could return 503 UNAVAILABLE under high demand. That is a transient capacity result, not automatic evidence that the MCP transport or request schema is broken. The hardened behavior uses bounded retries for transient failures: at most four total attempts, with approximately one-, two-, and four-second delays plus small jitter. If demand remains high, the tool reports the final failure and names the requested model. It does not switch models. gemini-3.1-pro-preview was visible to the tested API project, but its free-tier request and input-token quotas were both explicitly zero. Paid Gemini API billing is required. This is not an ordinary burst limit that becomes healthy after a short delay. The hardened classifier recognizes the free-tier limit-zero condition, does not retry it, and explains that billing/quota must change or the orchestrator must explicitly choose another allowlisted model. Repeated automatic retries would only add latency and noise. Ordinary transient 429 responses remain retryable. The important lesson is that identical HTTP status numbers can represent different operational states. The final policy distinguishes: - transient HTTP 408, ordinary 429, 500, 502, 503, and 504 responses; - equivalent transient network failures; - non-retryable validation, authentication, authorization, not-found, and free-tier limit-zero failures. Provider errors are reduced to concise diagnostics. Credentials and provider internals are not echoed into tool output. Tests also check that a supplied fake key cannot appear in safe error messages. Retries are bounded, keep the same model, and never become a recursive agent loop. The same server was verified from both Antigravity and Codex. Each client could discover and call: ask gemini get gemini consultant config The live verification covered the local MCP route and real Gemini responses. gemini-3.1-flash-lite and gemini-3.5-flash were live verified. The gemini-3.1-pro-preview result was a verified free-tier limit-zero condition, not a successful generation claim. The build evidence for the prepared implementation is: - typecheck passed; 28 tests passed across 4 test files ;- build passed; 2 MCP tools registered; 2 verified clients : Antigravity and Codex;- no silent model fallback. Tests remain separate from live smoke calls: the unit suite does not call Google, while explicit smoke commands exercise a selected model and never change it. Ahmed Yosry defined the experiment, supplied the constraints, made the product and safety decisions, coordinated the multi-model workflow, and verified the client integrations. ChatGPT/GPT contributed architecture and diagnosis: shaping the consultant boundary, separating API access from MCP exposure, reasoning through failure classes, and preserving a clear distinction between advice and verification. Codex contributed implementation: building the local TypeScript MCP server, schemas, configuration safety, model provenance, retry/error hardening, tests, build path, and client integration materials. Gemini participated as the consulted provider through focused, one-shot calls. It did not receive direct repository access and did not control the orchestrator. This attribution describes roles in the experiment; it is not a novelty claim. Verified in this experiment: - a reusable local Gemini Consultant MCP was implemented over STDIO; - it exposes two named read-only consultant/config tools; - the same MCP was called from Antigravity and Codex; - model selection is allowlisted and explicit; - requested and used model provenance is reported; - retries preserve the selected model; - high-demand 503 and free-tier limit-zero 429 paths were observed and hardened; - typecheck, 28 tests in 4 files, and build passed; gemini-3.1-flash-lite and gemini-3.5-flash produced live verified calls;- the publication pack's secret and privacy scan passed. Not established by those facts: - that every Gemini model is available to every API project; - that a consultant answer is correct without independent verification; - that adding models always improves an outcome; - that this architecture establishes novelty or exclusivity. @ask-llm/gemini-mcp https://github.com/Lykhoyda/ask-llm/tree/main/packages/gemini-mcp is a near-exact precedent for a TypeScript STDIO MCP with an ask-gemini tool, Codex setup, second-opinion positioning, and structured model metadata. It differs materially by supporting file inclusion, sandbox/edit modes, a Gemini CLI subprocess, and automatic Pro-to-Flash fallback. PAL MCP https://github.com/BeehiveInnovations/pal-mcp-server is a broader multi-provider consultant/router precedent. The contribution documented here is the same focused Gemini consultant verified from both Antigravity and Codex, with no local action tools for Gemini, explicit requested/used model provenance, bounded retries, safe diagnostics, and no silent fallback. The next step is not an uncontrolled swarm. It is a provider-neutral council interface with the same disciplines: - one primary orchestrator; - one focused evidence packet; - explicit provider/model selection; - independent responses; - structured agreement and disagreement; - cost, quota, and latency budgets; - no recursive loops or silent fallback; - a human-auditable final decision. That future architecture is a roadmap, not a claim about the current implementation. The controlled roundtable pattern is described at https://gist.github.com/amu3dev/ce6f1ff37a4de653d0ee1aface53f02b https://gist.github.com/amu3dev/ce6f1ff37a4de653d0ee1aface53f02b . Architecture visual: https://raw.githubusercontent.com/amu3dev/gemini-consultant-mcp/main/docs/assets/gemini-consultant-architecture-1600x900.png https://raw.githubusercontent.com/amu3dev/gemini-consultant-mcp/main/docs/assets/gemini-consultant-architecture-1600x900.png · Timeline: https://raw.githubusercontent.com/amu3dev/gemini-consultant-mcp/main/docs/assets/build-hardening-timeline-1600x900.png https://raw.githubusercontent.com/amu3dev/gemini-consultant-mcp/main/docs/assets/build-hardening-timeline-1600x900.png · Proof card: https://raw.githubusercontent.com/amu3dev/gemini-consultant-mcp/main/docs/assets/verification-proof-card-1080x1080.png https://raw.githubusercontent.com/amu3dev/gemini-consultant-mcp/main/docs/assets/verification-proof-card-1080x1080.png Turning OpenAI Codex into a Read-Only MCP Consultant for Antigravity https://gist.github.com/amu3dev/1a41e227bce7f8f1fdfcc3b03d8c8597 Building a Reusable Gemini Consultant MCP https://gist.github.com/amu3dev/82cd1feec73452224d9cfb332cc469c8 A Controlled Multi-Model Engineering Roundtable with MCP https://gist.github.com/amu3dev/ce6f1ff37a4de653d0ee1aface53f02b Repository: gemini-consultant-mcp https://github.com/amu3dev/gemini-consultant-mcp Ahmed Yosry · @amu3dev Independent experiment; not an official Google or OpenAI project.