{"slug": "how-i-built-and-verified-one-gemini-consultant-mcp-that-works-from-both-google", "title": "How I built and verified one Gemini consultant MCP that works from both Google Antigravity and OpenAI Codex.", "summary": "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.", "body_md": "*Ahmed Yosry · @amu3dev*\n\n**Independent experiment; not an official Google or OpenAI project.**\n\nRepository: [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)\n\nGemini-backed MCP tools and `ask-gemini`\n\nintegrations 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.\n\nThe result is a local TypeScript STDIO MCP server named `gemini-consultant`\n\n. Antigravity and Codex can call the same server, while the calling agent remains the orchestrator.\n\n```\nAntigravity or Codex\n        ↓\nlocal gemini-consultant MCP\n        ↓\nGemini API\n```\n\nSource and setup: [https://github.com/amu3dev/gemini-consultant-mcp](https://github.com/amu3dev/gemini-consultant-mcp)\n\nAn API makes a provider callable from application code. MCP makes a capability discoverable and invocable by an MCP client under a defined schema.\n\nThe gap contains real engineering work:\n\n- define tools and validate their inputs;\n- load configuration without leaking credentials;\n- translate a review request into a provider request;\n- separate trusted instructions from supplied context;\n- expose safe operational diagnostics;\n- classify provider failures;\n- preserve requested-versus-used model provenance;\n- speak JSON-RPC over STDIO without corrupting stdout.\n\nThe server is the adapter and policy enforcement point. It does not turn Gemini into a filesystem agent.\n\nThe 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.\n\nThe 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.\n\nThe server exposes exactly two tools:\n\nAccepts a required prompt and optional focused context, model, consultation mode, thinking choice, and output-token limit. It returns a one-shot answer with provenance.\n\nReturns 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.\n\nGemini 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.\n\nThe caller prepares the packet:\n\n- exact task;\n- relevant excerpts, diff, requirements, and logs;\n- explicit constraints;\n- a statement of what was not supplied.\n\nContext 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.\n\nThe server uses a configurable allowlist. The verified policy included:\n\n`gemini-3.1-flash-lite`\n\nfor lightweight or free-tier checks;`gemini-3.5-flash`\n\nwhen stronger analysis is requested;`gemini-3.1-pro-preview`\n\nonly when explicitly requested or paid quota is known to exist.\n\nAllowlisted means “permitted by this local server,” not “guaranteed available to this API project.” Provider access, billing, capacity, and quota remain separate.\n\nThinking 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.\n\nEvery 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.\n\nAcross 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.\n\nThis distinction is essential in a multi-model experiment. Without it, a “Gemini 3.5 Flash review” could quietly become evidence from a different model.\n\nLive verification exposed two different operational failures.\n\n`gemini-3.5-flash`\n\ncould return `503 UNAVAILABLE`\n\nunder high demand. That is a transient capacity result, not automatic evidence that the MCP transport or request schema is broken.\n\nThe 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.\n\n`gemini-3.1-pro-preview`\n\nwas 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.\n\nThe 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.\n\nOrdinary transient 429 responses remain retryable. The important lesson is that identical HTTP status numbers can represent different operational states.\n\nThe final policy distinguishes:\n\n- transient HTTP 408, ordinary 429, 500, 502, 503, and 504 responses;\n- equivalent transient network failures;\n- non-retryable validation, authentication, authorization, not-found, and free-tier limit-zero failures.\n\nProvider 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.\n\nRetries are bounded, keep the same model, and never become a recursive agent loop.\n\nThe same server was verified from both Antigravity and Codex. Each client could discover and call:\n\n```\nask_gemini\nget_gemini_consultant_config\n```\n\nThe live verification covered the local MCP route and real Gemini responses. `gemini-3.1-flash-lite`\n\nand `gemini-3.5-flash`\n\nwere live verified. The `gemini-3.1-pro-preview`\n\nresult was a verified free-tier limit-zero condition, not a successful generation claim.\n\nThe build evidence for the prepared implementation is:\n\n- typecheck passed;\n**28 tests** passed across**4 test files**;- build passed;\n**2 MCP tools** registered;**2 verified clients**: Antigravity and Codex;- no silent model fallback.\n\nTests 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.\n\nAhmed Yosry defined the experiment, supplied the constraints, made the product and safety decisions, coordinated the multi-model workflow, and verified the client integrations.\n\nChatGPT/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.\n\nCodex contributed implementation: building the local TypeScript MCP server, schemas, configuration safety, model provenance, retry/error hardening, tests, build path, and client integration materials.\n\nGemini participated as the consulted provider through focused, one-shot calls. It did not receive direct repository access and did not control the orchestrator.\n\nThis attribution describes roles in the experiment; it is not a novelty claim.\n\nVerified in this experiment:\n\n- a reusable local Gemini Consultant MCP was implemented over STDIO;\n- it exposes two named read-only consultant/config tools;\n- the same MCP was called from Antigravity and Codex;\n- model selection is allowlisted and explicit;\n- requested and used model provenance is reported;\n- retries preserve the selected model;\n- high-demand 503 and free-tier limit-zero 429 paths were observed and hardened;\n- typecheck, 28 tests in 4 files, and build passed;\n`gemini-3.1-flash-lite`\n\nand`gemini-3.5-flash`\n\nproduced live verified calls;- the publication pack's secret and privacy scan passed.\n\nNot established by those facts:\n\n- that every Gemini model is available to every API project;\n- that a consultant answer is correct without independent verification;\n- that adding models always improves an outcome;\n- that this architecture establishes novelty or exclusivity.\n\n[ @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\n\n`ask-gemini`\n\ntool, 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.\n\nThe next step is not an uncontrolled swarm. It is a provider-neutral council interface with the same disciplines:\n\n- one primary orchestrator;\n- one focused evidence packet;\n- explicit provider/model selection;\n- independent responses;\n- structured agreement and disagreement;\n- cost, quota, and latency budgets;\n- no recursive loops or silent fallback;\n- a human-auditable final decision.\n\nThat 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).\n\nArchitecture 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)\n\n[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)\n\nRepository: [gemini-consultant-mcp](https://github.com/amu3dev/gemini-consultant-mcp)\n\nAhmed Yosry · @amu3dev\n\nIndependent experiment; not an official Google or OpenAI project.", "url": "https://wpnews.pro/news/how-i-built-and-verified-one-gemini-consultant-mcp-that-works-from-both-google", "canonical_source": "https://gist.github.com/amu3dev/82cd1feec73452224d9cfb332cc469c8", "published_at": "2026-07-17 08:48:11+00:00", "updated_at": "2026-07-18 13:25:40.271172+00:00", "lang": "en", "topics": ["artificial-intelligence", "large-language-models", "developer-tools", "ai-agents", "ai-infrastructure"], "entities": ["Ahmed Yosry", "Google Antigravity", "OpenAI Codex", "Gemini", "MCP", "TypeScript", "JSON-RPC"], "alternates": {"html": "https://wpnews.pro/news/how-i-built-and-verified-one-gemini-consultant-mcp-that-works-from-both-google", "markdown": "https://wpnews.pro/news/how-i-built-and-verified-one-gemini-consultant-mcp-that-works-from-both-google.md", "text": "https://wpnews.pro/news/how-i-built-and-verified-one-gemini-consultant-mcp-that-works-from-both-google.txt", "jsonld": "https://wpnews.pro/news/how-i-built-and-verified-one-gemini-consultant-mcp-that-works-from-both-google.jsonld"}}