Converse

Converse MCP Server

[](https://www.npmjs.com/package/converse-mcp-server)

An MCP (Model Context Protocol) server that lets Claude talk to other AI models. Use it to chat with models from OpenAI, Google, Anthropic, X.AI, Mistral, DeepSeek, or OpenRouter. You can either talk to one model at a time or get multiple models to weigh in on complex decisions.

📋 Requirements

• Node.js: Version 20 or higher
• Package Manager: npm (or pnpm/yarn)
• API Keys: At least one from any supported provider

🚀 Quick Start

Step 1: Get Your API Keys

You need at least one API key from these providers:

| Provider | Where to Get | Example Format | | ----------------- | ---------------------------------------------------------------------------- | ----------------------- | | OpenAI | platform.openai.com/api-keys | sk-proj-... | | Google/Gemini | makersuite.google.com/app/apikey | AIzaSy... | | X.AI | console.x.ai | xai-... | | Anthropic | console.anthropic.com | sk-ant-... | | Mistral | console.mistral.ai | wfBMkWL0... | | DeepSeek | platform.deepseek.com | sk-... | | OpenRouter | openrouter.ai/keys | sk-or-... | | Codex | ChatGPT login (system-wide) | Local agentic assistant |

Note: Codex uses your ChatGPT login (not an API key). If you have an active ChatGPT session, Codex will work automatically. For headless/server deployments, set CODEX_API_KEY in your environment.

Step 2: Add to Claude Code or Claude Desktop

For Claude Code (Recommended)

# Add the server with your API keys
claude mcp add converse \
  -e OPENAI_API_KEY=your_key_here \
  -e GEMINI_API_KEY=your_key_here \
  -e XAI_API_KEY=your_key_here \
  -e ANTHROPIC_API_KEY=your_key_here \
  -e MISTRAL_API_KEY=your_key_here \
  -e DEEPSEEK_API_KEY=your_key_here \
  -e OPENROUTER_API_KEY=your_key_here \
  -e ENABLE_RESPONSE_SUMMARIZATION=true \
  -e SUMMARIZATION_MODEL=gpt-5 \
  -s user \
  npx converse-mcp-server

For Claude Desktop

Add this configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "converse": {
      "command": "npx",
      "args": ["converse-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "your_key_here",
        "GEMINI_API_KEY": "your_key_here",
        "XAI_API_KEY": "your_key_here",
        "ANTHROPIC_API_KEY": "your_key_here",
        "MISTRAL_API_KEY": "your_key_here",
        "DEEPSEEK_API_KEY": "your_key_here",
        "OPENROUTER_API_KEY": "your_key_here",
        "ENABLE_RESPONSE_SUMMARIZATION": "true",
        "SUMMARIZATION_MODEL": "gpt-5"
      }
    }
  }
}

Windows Troubleshooting: If npx converse-mcp-server doesn't work on Windows, try:

{
  "command": "cmd",
  "args": ["/c", "npx", "converse-mcp-server"],
  "env": {
    "ENABLE_RESPONSE_SUMMARIZATION": "true",
    "SUMMARIZATION_MODEL": "gpt-5"
    // ... add your API keys here
  }
}

Step 3: Start Using Converse

Once installed, you can:

• Chat with a specific model: Ask Claude to use the chat tool with your preferred model
• Get consensus: Ask Claude to use the consensus tool when you need multiple perspectives
• Run tasks in background: Use async: true for long-running operations that you can check later
• Monitor progress: Use the check_status tool to monitor async operations with AI-generated summaries
• Cancel jobs: Use the cancel_job tool to stop running operations
• Smart summaries: Get auto-generated titles and summaries for better context understanding
• Get help: Type /converse:help in Claude

🛠️ Available Tools

1. Chat Tool

Talk to any AI model with support for files, images, and conversation history. The tool automatically routes your request to the right provider based on the model name. When AI summarization is enabled, generates smart titles and summaries for better context understanding.

// Synchronous execution (default)
{
  "prompt": "How should I structure the authentication module for this Express.js API?",
  "model": "gemini-2.5-flash",         // Routes to Google
  "files": ["/path/to/src/auth.js", "/path/to/config.json"],
  "images": ["/path/to/architecture.png"],
  "temperature": 0.5,
  "reasoning_effort": "medium",
  "use_websearch": false
}

// Asynchronous execution (for long-running tasks)
{
  "prompt": "Analyze this large codebase and provide optimization recommendations",
  "model": "gpt-5",
  "files": ["/path/to/large-project"],
  "async": true,           // Enables background processing
  "continuation_id": "my-analysis-task"  // Optional: custom ID for tracking
}

// Codex - Agentic coding assistant with local file access
{
  "prompt": "Analyze this codebase and suggest improvements",
  "model": "codex",
  "files": ["/path/to/your/project"],
  "async": true  // Recommended for Codex (responses take 6-20+ seconds)
}

Codex Notes:

• Uses thread-based sessions (context persists with continuation_id)
• Responses typically take 6-20 seconds (complex tasks may take minutes)
• Accesses files directly from your working directory
• Configure sandbox mode via CODEX_SANDBOX_MODE environment variable

2. Consensus Tool

Get multiple AI models to analyze the same question simultaneously. Each model can see and respond to the others' answers, creating a rich discussion.

// Synchronous consensus (default)
{
  "prompt": "Should we use microservices or monolith architecture for our e-commerce platform?",
  "models": ["gpt-5", "gemini-2.5-flash", "grok-4"],
  "files": ["/path/to/requirements.md"],
  "enable_cross_feedback": true,
  "temperature": 0.2
}

// Asynchronous consensus (for complex analysis)
{
  "prompt": "Review our system architecture and provide comprehensive recommendations",
  "models": ["gpt-5", "gemini-2.5-pro", "claude-sonnet-4-6"],
  "files": ["/path/to/architecture-docs"],
  "async": true,          // Run in background
  "enable_cross_feedback": true
}

3. Check Status Tool

Monitor the progress and retrieve results from asynchronous operations. When AI summarization is enabled, provides intelligent summaries of ongoing and completed tasks.

// Check status of a specific job
{
  "continuation_id": "my-analysis-task"
}

// List recent jobs (shows last 10)
// With summarization enabled, displays titles and final summaries
{}

// Get full conversation history for completed job
{
  "continuation_id": "my-analysis-task",
  "full_history": true
}

4. Cancel Job Tool

Cancel running asynchronous operations when needed.

// Cancel a running job
{
  "continuation_id": "my-analysis-task"
}

🤖 AI Summarization Feature

When enabled, the server automatically generates intelligent titles and summaries for better context understanding:

• Automatic Title Generation: Creates descriptive titles (up to 60 chars) for each request
• Streaming Summaries: Status check returns an up-to-date summary of the progress based on the partially streamed response
• Final Summaries: Concise 1-2 sentence summaries of completed responses
• Smart Status Display: Enhanced check_status tool shows titles and summaries in job listings
• Persistent Context: Summaries are stored with async jobs for better progress tracking

Configuration:

# Enable in your environment
ENABLE_RESPONSE_SUMMARIZATION=true    # Default: false
SUMMARIZATION_MODEL=gpt-5-nano        # Default: gpt-5-nano

Benefits:

• Quickly understand what each async job is doing without reading full responses
• Better context when reviewing multiple ongoing operations
• Improved job management with at-a-glance understanding of task progress
• Graceful fallback to text snippets when summarization is disabled or fails

📊 Supported Models

OpenAI Models

• gpt-5: Latest flagship model (400K context, 128K output) - Superior reasoning, code generation, and analysis
• gpt-5-mini: Faster, cost-efficient GPT-5 (400K context, 128K output) - Well-defined tasks, precise prompts
• gpt-5-nano: Fastest, most cost-efficient GPT-5 (400K context, 128K output) - Summarization, classification
• gpt-5-pro: Most advanced reasoning model (400K context, 272K output) - Hardest problems, extended compute time (EXPENSIVE)
• o3: Strong reasoning (200K context)
• o3-mini: Fast O3 variant (200K context)
• o3-pro: Professional-grade reasoning (200K context) - EXTREMELY EXPENSIVE
• o3-deep-research: Deep research model (200K context) - 30-90 min runtime
• o4-mini: Latest reasoning model (200K context)
• o4-mini-deep-research: Fast deep research model (200K context) - 15-60 min runtime
• gpt-4.1: Advanced reasoning (1M context)
• gpt-4o: Multimodal flagship (128K context)
• gpt-4o-mini: Fast multimodal (128K context)

Google/Gemini Models

API Key Options:

• GEMINIAPIKEY: For Gemini Developer API (recommended)
• GOOGLEAPIKEY: Alternative name (GEMINIAPIKEY takes priority)
• Vertex AI: Use GOOGLE_GENAI_USE_VERTEXAI=true with project/location settings

Supported Models:

• gemini-3-pro-preview (aliases: pro, gemini): Enhanced reasoning with thinking levels (1M context, 64K output)
• gemini-2.5-flash (alias: flash): Ultra-fast (1M context, 65K output)
• gemini-2.5-pro (alias: pro 2.5): Deep reasoning with thinking budget (1M context, 65K output)
• gemini-2.0-flash: Latest with experimental thinking (1M context, 65K output)
• gemini-2.0-flash-lite: Lightweight fast model, text-only (1M context, 65K output)

Note: Default aliases (gemini, pro) now point to Gemini 3.0 Pro. Use gemini-2.5-pro explicitly if you need version 2.5.

X.AI/Grok Models

• grok-4-0709 (aliases: grok, grok-4): Latest advanced model (256K context)
• grok-code-fast-1: Speedy and economical reasoning model that excels at agentic coding (256K context)

Anthropic Models

• claude-fable-5 (alias: fable): Most capable model for demanding reasoning and long-horizon agentic work (1M context, 128K output)
• claude-opus-4-8 (alias: opus): Most capable Opus for complex reasoning and agentic coding (200K context, 1M via beta, 128K output)
• claude-opus-4-7 / claude-opus-4-6: Previous Opus generations with adaptive thinking (128K output)
• claude-opus-4-5 / claude-opus-4-1: Legacy Opus models with extended thinking (64K / 32K output)
• claude-sonnet-4-6 (alias: sonnet): Best combination of speed and intelligence with adaptive thinking (64K output)
• claude-haiku-4-5 (alias: haiku): Fast and intelligent for simple queries (64K output)

Mistral Models

• magistral-medium: Frontier-class reasoning model (40K context)
• magistral-small: Small reasoning model (40K context)
• mistral-medium-3: Frontier-class multimodal model (128K context)

DeepSeek Models

• deepseek-chat: Strong MoE model with 671B/37B parameters (64K context)
• deepseek-reasoner: Advanced reasoning model with CoT (64K context)

OpenRouter Models

• qwen3-235b-thinking: Qwen3 with enhanced reasoning (32K context)
• qwen3-coder: Specialized for programming tasks (32K context)
• kimi-k2: Moonshot AI Kimi K2 with extended context (200K context)

Codex Models

• codex: OpenAI Codex agentic coding assistant
• Thread-based sessions with persistent context
• Direct filesystem access from working directory
• Typical response time: 6-20 seconds (longer for complex tasks)
• Requires ChatGPT login or CODEXAPIKEY
• See [Configuration](#configuration) for sandbox and approval settings

Claude Agent SDK Models

• claude (aliases: claude-sdk, claude-code): Claude via the Claude Agent SDK
• Defaults to Claude Fable 5; pick a specific model with claude:fable or claude:opus
• Uses Claude Code CLI authentication (claude login) - no API key needed
• Direct filesystem access from working directory
• Unknown claude:-prefixed names pass through to the SDK (e.g. claude:claude-sonnet-4-6)

📚 Help & Documentation

Built-in Help

Type these commands directly in Claude:

• /converse:help - Full documentation
• /converse:help tools - Tool-specific help (includes async features)
• /converse:help models - Model information
• /converse:help parameters - Configuration details
• /converse:help examples - Usage examples (sync and async)
• /converse:help async - Async execution guide

Additional Resources

• API Reference: [docs/API.md](docs/API.md)
• Architecture Guide: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
• Integration Examples: [docs/EXAMPLES.md](docs/EXAMPLES.md)

⚙️ Configuration

Environment Variables

Create a .env file in your project root:

# Required: At least one API key
OPENAI_API_KEY=sk-proj-your_openai_key_here
GEMINI_API_KEY=your_gemini_api_key_here  # Or GOOGLE_API_KEY (GEMINI_API_KEY takes priority)
XAI_API_KEY=xai-your_xai_key_here
ANTHROPIC_API_KEY=sk-ant-your_anthropic_key_here
MISTRAL_API_KEY=your_mistral_key_here
DEEPSEEK_API_KEY=your_deepseek_key_here
OPENROUTER_API_KEY=sk-or-your_openrouter_key_here

# Optional: Server configuration
PORT=3157
LOG_LEVEL=info

# Optional: AI Summarization (Enhanced async status display)
ENABLE_RESPONSE_SUMMARIZATION=true    # Enable AI-generated titles and summaries
SUMMARIZATION_MODEL=gpt-5-nano        # Model to use for summarization (default: gpt-5-nano)

# Optional: OpenRouter configuration
OPENROUTER_REFERER=https://github.com/FallDownTheSystem/converse
OPENROUTER_TITLE=Converse
OPENROUTER_DYNAMIC_MODELS=true

# Optional: Codex configuration
CODEX_API_KEY=your_codex_api_key_here       # Optional if ChatGPT login available
CODEX_SANDBOX_MODE=read-only                 # read-only (default), workspace-write, danger-full-access
CODEX_SKIP_GIT_CHECK=true                    # true (default), false
CODEX_APPROVAL_POLICY=never                  # never (default), untrusted, on-failure, on-request

Configuration Options

Server Environment Variables (.env file)

| Variable | Description | Default | Example | | ----------- | ------------- | ------- | ------------------------ | | PORT | Server port | 3157 | 3157 | | LOG_LEVEL | Logging level | info | debug, info, error |

Claude Code Environment Variables (System/Global)

These must be set in your system environment or when launching Claude Code, NOT in the project .env file:

| Variable | Description | Default | Example | | ----------------------- | --------------------------- | -------- | ------------------------------------ | | MAX_MCP_OUTPUT_TOKENS | Token response limit | 25000 | 200000 | | MCP_TOOL_TIMEOUT | Tool execution timeout (ms) | 120000 | 5400000 (90 min for deep research) |

# Example: Set globally before starting Claude Code
export MAX_MCP_OUTPUT_TOKENS=200000
export MCP_TOOL_TIMEOUT=5400000  # 90 minutes for deep research models
claude  # Then start Claude Code

Model Selection

Use "auto" for automatic model selection, or specify exact models:

// Auto-selection (recommended)
"auto";

// Specific models
"gemini-2.5-f

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [FallDownTheSystem](https://github.com/FallDownTheSystem)
- **Source:** [FallDownTheSystem/converse](https://github.com/FallDownTheSystem/converse)
- **License:** MIT
- **Homepage:** https://github.com/FallDownTheSystem/converse

Install and usage instructions live in the source repository linked above.