Gemini Consultant MCP

A documented reusable Gemini consultant MCP verified from Antigravity and Codex.

gemini-consultant is a local TypeScript MCP server that lets an orchestrating agent request a focused, one-shot second opinion from an allowlisted Google Gemini model. The caller chooses the prompt and the exact context to disclose. The server reports requested and used model provenance, applies bounded retries, and never silently changes models.

Verified topology and operating policy

flowchart LR
    A["Antigravity"] -->|"MCP"| C["Codex via codex mcp-server"]
    A -->|"MCP"| G["Gemini Consultant MCP"]
    C -->|"MCP"| G
    G --> B["Focused prompt boundary"]
    B --> M["Allowlisted Gemini model"]
    M --> P["Attributable answer + requested/used model"]

The verified deployment has three directed consultation edges:

1. Antigravity → Codex MCP;

2. Antigravity → Gemini Consultant MCP; and

3. Codex → the same Gemini Consultant MCP.

This repository implements the Gemini Consultant MCP component. The calling client remains the orchestrator: it selects focused evidence, retains the source label on each response, and can preserve agreement or disagreement for human review rather than forcing consensus.

The combined operating policy is:

• focused evidence rather than open-ended workspace delegation;

• a least-authority Gemini boundary with no filesystem, shell, Git, browser, URL-fetching, or code-execution capability exposed to Gemini;

• explicit requested and used model identifiers;

• bounded retry semantics that retain the same requested model;

• no silent model substitution;

• attributable agreement and disagreement; and

• no automatic recursive agent loop.

There is no automatic edge from Gemini back to Codex or Antigravity. Gemini receives only the request content selected by the caller, and this server does not discover project context or act on the response.

Related MCP server: MCP-Typescribe

MCP tools

ask_gemini

Requests an independent consultation. Required input: prompt. Optional inputs: focused context, allowlisted model, mode (general, code_review, architecture, or critic), thinkingLevel, thinkingBudget, and maxOutputTokens.

The response includes:

• provider;

• requested model;

• provider-reported used model;

• mode and thinking selection;

• answer;

• available token usage metadata.

get_gemini_consultant_config

Returns safe, read-only runtime metadata: server version, default and allowed model IDs, context/output limits, and whether an API key is configured. It never returns the key or a key fragment.

Install

Requirements: Node.js 22 or newer, npm, and a Gemini API key for the Google Gemini API.

git clone https://github.com/amu3dev/gemini-consultant-mcp.git $HOME/work/mcp/gemini-consultant
cd $HOME/work/mcp/gemini-consultant
npm ci
cp -n .env.example .env
chmod 600 .env
npm run build

Edit only the local .env file and add the key there. Never put the key in client configuration, prompts, logs, commits, or chat. .env is ignored; .env.example contains placeholders only.

Environment variables

Example values live in .env.example. Use a real key only in the ignored .env file.

Model policy, thinking, and provenance

Allowlisted means the server permits a model ID. It does not guarantee quota, billing, geographic access, capacity, or continued provider availability.

thinkingLevel accepts default, minimal, low, medium, or high. thinkingBudget accepts 0 through 32,768 tokens. A non-default level and a budget cannot be sent together. With the default level and no budget, the server omits thinkingConfig and leaves the choice to the provider default.

Every successful consultation states both the requested model and the provider-reported used model. If the provider omits a model version, the requested model is reported as the used model. The server has no silent model fallback: retries use the same requested model, and selecting another model requires an explicit caller action.

Transient HTTP 408, ordinary 429, 500, 502, 503, and 504 responses, plus recognized transient network failures, receive at most four total attempts with approximately 1, 2, and 4 second delays plus small jitter. HTTP 400, 401, 403, 404, and free-tier limit-zero 429 responses are not retried. See the model policy for the complete behavior.

Antigravity setup

Build first, find the absolute Node path with command -v node, and merge the entry from examples/antigravity-mcp-config.json into the existing mcpServers object. Replace /absolute/path/to/node and /Users/USERNAME/work/mcp/gemini-consultant with local absolute paths.

Do not add GEMINI_API_KEY to the JSON. The process loads the ignored .env from its configured working directory. Detailed steps and the conservative merge helper are in Antigravity setup.

Codex setup

Codex supports local STDIO MCP entries under [mcp_servers.<name>] in config.toml. Add the entry from examples/codex-config.toml to the user-level configuration, replace the generic paths, and restart Codex. The example explicitly enables only ask_gemini and get_gemini_consultant_config.

No Gemini key belongs in the Codex configuration. See Codex setup and the official Codex MCP configuration documentation.

Security boundary

• The server sends only the supplied prompt and optional context to Gemini.

• Supplied context is delimited and treated as untrusted reference material, not instructions.

• The Gemini client receives no function or tool declarations.

• The server exposes no filesystem, shell, Git, browser, URL-fetching, or write capabilities.

• Context size is bounded and oversized input is rejected without silent truncation.

• stdout is reserved for MCP JSON-RPC; startup diagnostics use stderr.

• API keys are excluded from client examples and safe configuration output.

• Provider errors are reduced to concise operational guidance.

This is a focused-context boundary, not a guarantee that supplied data is non-sensitive. Callers remain responsible for minimizing and reviewing every excerpt sent to a third-party model. See architecture and security policy.

Build and verification status

The publication checks are offline and deterministic; they do not require a live Gemini call.

Run the same local publication checks:

npm ci
npm run typecheck
npm test
npm run build
npm run verify:mcp

npm test uses injected provider doubles and does not call Google. A separate live smoke command exists for operator diagnostics, but it is not required for build, test, or publication:

npm run smoke -- --model gemini-3.1-flash-lite

Gemini API billing, quota, model visibility, capacity, and availability are controlled by Google and can change independently of this project. Do not state or assume that Gemini Pro works on a free tier.

Examples

• Antigravity MCP configuration

• Codex MCP configuration

• Focused consultation prompts

• Troubleshooting guide

Prior Art / Related Work

The individual components are not presented as novel. Public precedents already cover Antigravity invoking Codex through MCP, TypeScript ask-gemini MCP servers documented for Codex, and multi-model councils or comparison workflows.

In the public sources inspected through 2026-07-17, I did not find an example combining the same verified three-edge topology with the same least-authority, provenance-preserving, no-silent-fallback, no-recursion, and disagreement-preserving policy. This is not a claim of being first.

This is a bounded public-source result, not a patent search or proof of absence. Private, unindexed, deleted, paywalled, non-English, or newer examples may exist.

Visuals

The architecture image above shows the verified three-edge topology and the focused Gemini evidence boundary. The visual sequence below records implementation hardening, the controlled roundtable policy, and the verified proof points. These are documentation assets, not novelty or priority claims.

Build and hardening timeline

Controlled engineering roundtable

Verification proof card

Square and portrait variants, together with matching editable SVG sources, are available in docs/assets/.

Publication Series

1. Antigravity → Codex MCP consultant

2. Reusable Gemini Consultant MCP

3. Controlled multi-model engineering roundtable

Roadmap

• Add optional structured consultation outputs while retaining plain-text compatibility.

• Expand deterministic protocol and provider-error fixtures.

• Improve install diagnostics across supported local MCP clients.

• Explore a future provider-neutral model council in which explicitly configured consultants can return provenance-preserving opinions without silent provider or model substitution. The current verified consultant is Gemini-specific and MCP-mediated across providers.

Independent project disclaimer

This is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Google, Gemini, OpenAI, Codex, or Antigravity. Product names and trademarks belong to their respective owners.

Contributing and license

See CONTRIBUTING.md before opening a change. Security-sensitive reports should follow SECURITY.md, not a public issue.

Licensed under the MIT License. Copyright 2026 Ahmed Yosry.