# Gemini Consultant MCP

[![CI](https://github.com/amu3dev/gemini-consultant-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/amu3dev/gemini-consultant-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**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.

![Architecture diagram showing Antigravity and Codex calling the same local Gemini Consultant MCP, plus a separate Antigravity to Codex MCP route. Gemini receives only the supplied prompt and focused context; it receives no filesystem, shell, repository, write, or execution tools.](docs/assets/gemini-consultant-architecture-1600x900.png)

## Verified topology and operating policy

```mermaid
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.

```bash
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`](.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](docs/model-policy.md) 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`](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](docs/antigravity-setup.md).

## Codex setup

Codex supports local STDIO MCP entries under `[mcp_servers.<name>]` in `config.toml`. Add the entry from [`examples/codex-config.toml`](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](docs/codex-setup.md) and the official [Codex MCP configuration documentation](https://developers.openai.com/codex/mcp/).

## 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](docs/architecture.md) and [security policy](SECURITY.md).

## 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:

```bash
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:

```bash
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](examples/antigravity-mcp-config.json)
- [Codex MCP configuration](examples/codex-config.toml)
- [Focused consultation prompts](examples/prompts.md)
- [Troubleshooting guide](docs/troubleshooting.md)

## 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](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/blob/main/docs/ANTIGRAVITY_ADAPTATION.md) ([2026-03-20 commit](https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep/commit/fd39540834ddc0dba17cc1ce14d158b0592d8d5a)) | 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`](https://github.com/Lykhoyda/ask-llm/tree/main/packages/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](https://github.com/BeehiveInnovations/pal-mcp-server) | 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](https://gist.github.com/johnlindquist/00dd3f91e8683e41d4881b23b8d5cf05) | 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](https://github.com/openai/codex/blob/main/codex-rs/docs/codex_mcp_interface.md) and [Google Antigravity MCP documentation](https://antigravity.google/docs/mcp) | 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

![Timeline from architecture and Codex implementation through 28 tests across 4 files, live Gemini calls, 503 high demand, a free-tier quota limit of zero, retry hardening, and verification from Antigravity and Codex.](docs/assets/build-hardening-timeline-1600x900.png)

### Controlled engineering roundtable

![Controlled roundtable diagram in which a primary orchestrator sends the same focused evidence to its own analysis, Codex, and Gemini, then preserves agreement, disagreement, and evidence gaps without recursion, forced consensus, or silent model substitution.](docs/assets/controlled-roundtable-1600x900.png)

### Verification proof card

![Proof card stating that typecheck passed, 28 tests passed, build passed, Antigravity and Codex verification passed, gemini-3.1-flash-lite and gemini-3.5-flash live verification passed, and the secret scan passed.](docs/assets/verification-proof-card-1080x1080.png)

Square and portrait variants, together with matching editable SVG sources, are available in [`docs/assets/`](docs/assets/).

## Publication Series

1. [Antigravity → Codex MCP consultant](https://gist.github.com/amu3dev/1a41e227bce7f8f1fdfcc3b03d8c8597)
2. [Reusable Gemini Consultant MCP](https://gist.github.com/amu3dev/82cd1feec73452224d9cfb332cc469c8)
3. [Controlled multi-model engineering roundtable](https://gist.github.com/amu3dev/ce6f1ff37a4de653d0ee1aface53f02b)

## 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](CONTRIBUTING.md) before opening a change. Security-sensitive reports should follow [SECURITY.md](SECURITY.md), not a public issue.

Licensed under the [MIT License](LICENSE). Copyright 2026 Ahmed Yosry.