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.

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

Variable	Default	Policy
GEMINI_API_KEY	none	Required. Startup fails fast when absent.
GEMINI_DEFAULT_MODEL	gemini-3.1-flash-lite	Default requested model; must be in the allowlist.
GEMINI_ALLOWED_MODELS	gemini-3.1-flash-lite,gemini-3.5-flash,gemini-3.1-pro-preview	Comma-separated exact model IDs.
GEMINI_MAX_OUTPUT_TOKENS	8192	Integer from 1 through 65,536; request overrides cannot exceed it.
GEMINI_MAX_CONTEXT_CHARS	300000	Integer from 1 through 10,000,000; oversized context is rejected, not truncated.

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.

Model	Policy	Verified status
gemini-3.1-flash-lite	Default allowlisted model.	Live verification passed.
gemini-3.5-flash	Allowlisted for explicitly selected consultations.	Live verification passed; capacity errors can still occur.
gemini-3.1-pro-preview	Allowlisted only for explicit use where paid quota is available.	Visible, but free-tier quota limit was 0 for the tested project. Paid API billing is required.

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.

Check	Status
npm ci	Passed
npm run typecheck	Passed
npm test	28 tests across 4 files passed
npm run build	Passed
npm run verify:mcp	Passed: compiled dist/index.js, JSON-RPC-only stdout, and both tools listed
Antigravity live verification	Passed
Codex live verification	Passed

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.

Related work	Relevant precedent	Difference from this verified deployment
ARIS Antigravity adaptation (2026-03-20 commit)	Configures Antigravity to invoke codex mcp-server as an external reviewer.	Near-exact precedent for the Antigravity → Codex edge; it does not establish this full three-edge topology and Gemini policy bundle.
@ask-llm/gemini-mcp	TypeScript STDIO ask-gemini server with documented Codex installation and model metadata.	Near-exact precedent for the core Gemini MCP/Codex idea; its file, execution, and automatic quota-fallback behavior differs from this least-authority, no-silent-substitution contract.
PAL MCP	Multi-model consultation, selected-file context, review, and consensus workflows with Codex support.	Strong council/router precedent with a different central topology, broader routing/fallback behavior, and consensus features.
Lootbox council workflow	Parallel Claude, Codex, and Gemini comparison that surfaces agreement and disagreement.	Strong precedent for same-question comparison; the inspected artifact did not establish the same authority, provenance, retry, or no-recursion policy.
OpenAI Codex MCP interface and Google Antigravity MCP documentation	Official documentation for the MCP capabilities used by the deployment.	Capability documentation, not evidence of novelty or of this combined deployment.

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.