# Vox MCP: Multi-Model AI Gateway

URL: https://research-memex.org/docs/toolkit/vox-mcp
Description: Vox lets an MCP client ask several model providers without adding hidden instructions.



*The right model for the right question beats the best model for every question.*

Vox MCP is a multi-model AI gateway that lets you access any AI provider directly from Claude Code, Claude Desktop, Cursor, or any MCP client. Unlike other multi-model tools, Vox uses a pure passthrough design: prompts go to providers unmodified and responses come back unmodified. No system prompt injection, no response formatting, no behavioral directives.

<ToolMeta slug="vox-mcp" runtime="Python / uv" note="Minimal intervention. The only value Vox adds is routing and conversation memory. Everything else is pure passthrough." />

## Why it matters [#why-it-matters]

When you're working in Claude Code and want a second opinion from Gemini, GPT, GLM, Kimi, or DeepSeek, you'd normally have to switch applications. Vox lets you query any model without leaving your current workflow.

The difference from alternatives: Most multi-model tools inject their own system prompts or modify your messages. Vox doesn't. What you send is what the model receives.

## Supported providers [#supported-providers]

<KeyTable column="2">
  | Provider        | Env Variable         |
  | --------------- | -------------------- |
  | Google Gemini   | `GEMINI_API_KEY`     |
  | OpenAI          | `OPENAI_API_KEY`     |
  | Anthropic       | `ANTHROPIC_API_KEY`  |
  | xAI             | `XAI_API_KEY`        |
  | DeepSeek        | `DEEPSEEK_API_KEY`   |
  | Moonshot (Kimi) | `MOONSHOT_API_KEY`   |
  | OpenRouter      | `OPENROUTER_API_KEY` |
  | Custom/Local    | `CUSTOM_API_URL`     |
</KeyTable>

<Aside label="MODEL NAMES">
  No model list here, on purpose. That catalog lives in Vox's own `conf/*_models.json` and moves on the provider's schedule, not ours. Run `listmodels` to see what your keys actually reach.
</Aside>

You only need API keys for providers you want to use. Vox works with any subset.

## Tools [#tools]

Vox provides three tools through the MCP protocol:

### `chat` [#chat]

Send prompts to any supported model with optional file or image attachments.

```
"Use vox chat with gemini-2.5-pro:
Compare these two theoretical frameworks and identify tensions..."
```

### `listmodels` [#listmodels]

Show all available models, aliases, and capabilities across your configured providers. This is the source of truth for a live Vox install because provider availability depends on the API keys and allowlists present in that process.

### `dump_threads` [#dump_threads]

Export conversation threads as JSON or Markdown. This is useful for documenting multi-model analysis.

## Multi-turn conversations [#multi-turn-conversations]

Vox supports persistent threads via `continuation_id`. This means you can:

1. Start a conversation with Gemini about a theoretical framework
2. Continue the same thread with follow-up questions
3. Switch to DeepSeek mid-conversation to get a different perspective
4. Export the entire multi-model dialogue

Vox automatically saves threads to disk as JSONL for durability. You can export threads as Markdown.

## Research workflows [#research-workflows]

<Tabs>
  <Tab title="Model Comparison">
    Compare perspectives on the same research question:

    Ask the same analytical question to 3-4 models and compare their responses. Each model brings different strengths: Claude for nuanced interpretation, Gemini for large-context synthesis, DeepSeek for cost-effective exploration.

    This is particularly valuable for:

    * Theory development (different models foreground different tensions)
    * Literature gap identification
    * Methodological critique
  </Tab>

  <Tab title="Critical Challenge">
    Use a second model as a devil's advocate:

    Send your draft thesis or framework to Kimi or DeepSeek via Vox and ask it to find weaknesses.

    Then use Claude Opus to respond to those challenges. The dialogue between models often reveals blind spots.
  </Tab>

  <Tab title="Triangulation">
    Multi-model verification:

    When you get an important finding or synthesis from one model, verify it with 2-3 others. If multiple models converge on the same insight from different angles, you have a stronger basis for trusting it.

    Vox makes this trivial. You don't leave your workspace.
  </Tab>
</Tabs>

## Host support [#host-support]

Vox is a standard stdio MCP server, so it runs anywhere MCP runs.

<HostSupport
  rows="[
{ host: 'Claude Code (CLI)', status: 'full', note: '`claude mcp add` or project `.mcp.json`' },
{ host: 'Claude Code (Desktop &#x22;Code&#x22; tab)', status: 'full', note: 'Same `.mcp.json` as the CLI' },
{ host: 'Claude Desktop (chat)', status: 'full', note: '`claude_desktop_config.json`' },
{ host: 'Codex CLI / Codex Desktop', status: 'full', note: '`codex mcp add vox -- uv run --directory /path/to/vox python server.py`' },
{ host: 'Cursor / Windsurf / VS Code', status: 'full', note: 'Standard `mcp.json` / `mcp_config.json`' },
{ host: 'Cherry Studio, Witsy, other MCP clients', status: 'full', note: 'Standard MCP server entry — same args block as the configs below' },
]"
/>

The exact config blocks for the common hosts live in the Installation section.

## Install [#install]

Two ways to set Vox up:

* Manually — clone, configure `.env`, register with your MCP client. See the steps below.
* Via [Carrel](/docs/toolkit/carrel) — run `/carrel-setup` and answer yes when the interview asks about multi-model access (Gemini, GPT, Grok, Kimi, …). Carrel adds Vox at project level and prompts for at least one provider API key.

The manual path is host-agnostic; the Carrel path is Claude Code-only but skips the config steps.

### Setup [#setup]

<Steps>
  <Step title="Clone and install">
    ```bash
    git clone https://github.com/linxule/vox-mcp.git
    cd vox-mcp
    uv sync
    ```
  </Step>

  <Step title="Configure API keys">
    ```bash
    cp .env.example .env
    # Edit .env — add at least one provider API key
    ```
  </Step>

  <Step title="Test the server">
    ```bash
    uv run python server.py
    ```
  </Step>

  <Step title="Add to your MCP client">
    See the configuration tabs below for your specific client.
  </Step>
</Steps>

### MCP client configuration [#mcp-client-configuration]

Vox runs as a stdio MCP server. Replace `/path/to/vox-mcp` with the absolute path to your cloned repo.

<Tabs>
  <Tab title="Claude Code" icon="terminal">
    Via CLI:

    ```bash
    claude mcp add vox-mcp \
      -e GEMINI_API_KEY=your-key-here \
      -- uv run --directory /path/to/vox-mcp python server.py
    ```

    Or add to `.mcp.json` in your project root:

    ```json
    {
      "mcpServers": {
        "vox-mcp": {
          "command": "uv",
          "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
          "env": {
            "GEMINI_API_KEY": "your-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop" icon="message-bot">
    Add to `claude_desktop_config.json`:

    macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    Windows: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json
    {
      "mcpServers": {
        "vox-mcp": {
          "command": "uv",
          "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
          "env": {
            "GEMINI_API_KEY": "your-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor" icon="code">
    Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

    ```json
    {
      "mcpServers": {
        "vox-mcp": {
          "command": "uv",
          "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
          "env": {
            "GEMINI_API_KEY": "your-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf" icon="wind">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json
    {
      "mcpServers": {
        "vox-mcp": {
          "command": "uv",
          "args": ["run", "--directory", "/path/to/vox-mcp", "python", "server.py"],
          "env": {
            "GEMINI_API_KEY": "your-key-here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  API keys can live in either the MCP client config or the `.env` file inside the vox-mcp directory (loaded automatically). If both are set and conflict, add `VOX_FORCE_ENV_OVERRIDE=true` to `.env` to prefer your local values.
</Tip>

## Configuration options [#configuration-options]

Beyond API keys, Vox supports several configuration options in `.env`; the repository's `.env.example` is the full reference:

<Columns>
  <Card title="DEFAULT_MODEL" icon="bullseye">
    Set to `auto` (default) to let the agent pick the best model, or specify a model name like `gemini-2.5-pro` to always route to that model.
  </Card>

  <Card title="CONVERSATION_TIMEOUT_HOURS" icon="clock">
    How long conversation threads stay alive. Default: 24 hours. Threads expire after this period of inactivity.
  </Card>

  <Card title="MAX_CONVERSATION_TURNS" icon="arrows-spin">
    Maximum number of turns per conversation thread. Default: 100. Prevents runaway threads from consuming memory.
  </Card>

  <Card title="Model Restrictions" icon="filter">
    Per-provider allowlists like `GOOGLE_ALLOWED_MODELS`, `OPENAI_ALLOWED_MODELS`, etc. Restrict which models are available to prevent accidental use of expensive models.
  </Card>
</Columns>

### Provider behavior notes [#provider-behavior-notes]

* Vox routes Gemini requests through Google's Interactions API when available, using it statelessly (`store=false`) so Vox still owns conversation memory. Image inputs and failed Interactions attempts fall back to `generateContent`; set `VOX_GEMINI_USE_INTERACTIONS=false` to skip the Interactions path.
* Gemini thinking controls differ by API surface. Gemini 3 uses `thinking_level`; Gemini 2.x still has thinking support, but the Interactions path maps Vox's `thinking_mode` to the levels that API accepts.
* Vox omits temperature unless the caller explicitly supplies one. That preserves provider defaults for models where changing temperature is discouraged or unsupported.

## Part of Research Memex [#part-of-research-memex]

Vox integrates naturally with other Research Memex tools:

* [Interpretive Orchestration Plugin](/docs/toolkit/interpretive-orchestration-plugin) — Multi-model triangulation during qualitative analysis
* [Kimi Plugin for Claude Code](/docs/toolkit/kimi-plugin-cc) — For full delegation/review jobs rather than one-shot consults
* [Claude Code Setup Guide](/docs/implementation/agentic-ai-tools/claude-code-setup-guide) — Your primary research environment
* [AI Model Reference Guide](/docs/implementation/core-references/ai-model-reference-guide) — Understanding which models to query for what