Second Opinion MCP

Get independent AI reviews from Claude Code, DeepSeek V4 Pro, Kimi K3 (Moonshot), OpenAI (ChatGPT), and 300+ OpenRouter models through any MCP client.

What It Does

When working with Codex, Claude Code, Claude Desktop, or another MCP client, this server lets you:

• Get alternative perspectives on code, architecture, and decisions
• Run systematic code reviews with severity-classified issues
• Stage multi-model debates where AI models argue opposing positions
• Challenge proposals with anti-sycophancy mode (finds weaknesses, not validation)
• Review architectural plans before coding begins
• Review implementations against their original plans

Quickstart

1. Install

Windows

# Install Python 3.10+ from python.org if not installed
# Then install pipx
pip install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp

macOS

# Install Python 3.10+ via Homebrew if not installed
brew install python@3.12

# Install pipx
pip3 install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp

Linux (Ubuntu/Debian)

# Install Python and pipx
sudo apt update
sudo apt install python3 python3-pip python3-venv
pip3 install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp

Linux (Fedora/RHEL)

sudo dnf install python3 python3-pip
pip3 install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp

2. Setup

Run the interactive setup wizard:

second-opinion-mcp setup

The wizard will guide you through selecting providers and entering API keys. Keys are stored securely in your system's credential manager.

The wizard automatically verifies your setup when it finishes. To re-check later:

second-opinion-mcp verify

After setup completes, see Client Integration below for instructions specific to your MCP client.

Client Integration

After running the setup wizard, register the MCP server with your client.

The setup wizard is optional when you only want claude_second_opinion. That tool uses the Claude Code CLI's existing Claude Max login and does not require an API key. The seven API-backed tools remain listed but return configuration errors until their required providers are configured.

Claude Code CLI

Register the server:

claude mcp add -s user second-opinion -- second-opinion-mcp

The server auto-detects which providers have credentials configured (v0.8.0+). To restrict to specific providers, use the env var:

claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek,moonshot" -- second-opinion-mcp

Restart Claude Code after registering.

Verify the server is registered:

claude mcp list | grep second-opinion

Codex CLI

Install Claude Code, run claude once to sign in with your Claude Max account, then register this stdio server:

codex mcp add second-opinion -- second-opinion-mcp

Verify the registration with codex mcp list. Codex can then call claude_second_opinion for difficult, ambiguous, or high-impact work.

Opus 5 xhigh reviews can run for several minutes. Set the MCP tool timeout to at least 630 seconds; 660 seconds leaves a small margin. Put this block in ~/.codex/config.toml; the 30-second startup timeout leaves room for the bounded Claude Max login check:

[mcp_servers.second-opinion]
startup_timeout_sec = 30.0
tool_timeout_sec = 660.0

[mcp_servers.second-opinion.tools.claude_second_opinion]
approval_mode = "approve"

The per-tool approval lets Codex consult Claude automatically while leaving the server's other tools under their existing approval policy.

claude_second_opinion is intended for Codex and other non-Claude clients. It refuses calls from inside Claude Code to prevent recursive Claude sessions; the other MCP tools remain available to Claude Code as before.

Claude Desktop App

Add to your claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "second-opinion": {
      "command": "second-opinion-mcp"
    }
  }
}

The server auto-detects providers from credentials (v0.8.0+). To restrict to specific providers, add an env block with "SECOND_OPINION_PROVIDERS": "deepseek,moonshot".

Restart Claude Desktop after saving. To verify, start a new conversation and check that the second-opinion tools appear in the available tools list.

OpenClaw

OpenClaw uses mcporter for MCP server integration.

Step 1: Run the setup wizard

second-opinion-mcp setup

This stores your API keys in ~/.second-opinion-config:

{
  "credentials": {
    "deepseek": "sk-...",
    "moonshot": "sk-..."
  }
}

Step 2: Install mcporter

npm install -g mcporter

Step 3: Add to mcporter config

Create or edit ~/.mcporter/mcporter.json:

{
  "mcpServers": {
    "second-opinion": {
      "command": "second-opinion-mcp",
      "env": {
        "SECOND_OPINION_PROVIDERS": "deepseek,moonshot",
        "SECOND_OPINION_ALLOWED_ROOTS": "/opt/openclaw"
      }
    }
  }
}

Note: API keys are NOT in mcporter config. They stay in ~/.second-opinion-config, separate from server registration.

Step 4: Verify

mcporter list
mcporter tools second-opinion

OpenClaw automatically discovers servers configured in mcporter.

Other MCP Clients

For other MCP-compatible clients, the server requires:

• Command: second-opinion-mcp
• Optional: SECOND_OPINION_PROVIDERS=deepseek,moonshot to restrict providers (auto-detected from credentials by default)

Refer to your client's documentation for how to add stdio-based MCP servers.

Supported Models

DeepSeek V4 Pro (Recommended)

Extended thinking model with 1M context. Best for code reviews and complex analysis.

• Get your API key at https://platform.deepseek.com
• Thinking mode always on with reasoning_effort=high
• 1M-token context window

Kimi K3 (Moonshot)

Chinese AI model with thinking mode. Good for alternative perspectives and debates.

• Get your API key at https://platform.moonshot.ai
• Thinking mode always on, temperature locked to 1.0
• Supports 1M-token context window

OpenAI (ChatGPT)

GPT-5.6 Sol (OAuth only), running at xhigh reasoning effort. Good for architectural reviews and implementation analysis.

The recommended way to authenticate is via the built-in OAuth login, which provides free access for ChatGPT Plus subscribers. Run the setup wizard and choose "Login with ChatGPT Plus (OAuth)":

second-opinion-mcp setup
# Select OpenAI, choose "Login with ChatGPT Plus (OAuth)"
# Browser opens for sign-in, tokens stored automatically

On headless systems (SSH, Docker), the wizard uses a device code flow instead: it displays a URL and code to enter on any device with a browser.

Two authentication methods are supported (checked in this order):

1. Built-in OAuth token from setup wizard (free for ChatGPT Plus, stored in ~/.second-opinion-config)
2. Codex CLI OAuth token from ~/.codex/auth.json (fallback if Codex CLI is installed)

Tokens are automatically refreshed when expired. The API-key authentication path is not available (the server is OAuth-only for OpenAI).

OpenRouter (Optional)

Access 300+ models through a single API. Enable for variety or specific model access.

• Get your API key at https://openrouter.ai/keys

Claude Code (Claude Max)

Claude Opus 5 runs through the locally installed Claude Code CLI at xhigh effort. Before every call, the adapter verifies that claude auth status --json reports a claude.ai login with subscription type max. It removes Anthropic API/provider overrides from the child environment and rejects other active credential methods, including an apiKeyHelper. It never reads or stores Claude credentials itself.

Available Tools

second_opinion

Get a straightforward second opinion on any question, code, or decision.

Use second_opinion to review this database schema: [paste schema]

claude_second_opinion

Ask Claude Opus 5 at xhigh effort for an independent opinion using your local Claude Max login. This tool is for Codex and other non-Claude MCP clients; it refuses recursive use from inside Claude Code. The tool is text-only and gives Claude no filesystem, shell, browser, skill, or MCP tools. Include all relevant code, diffs, errors, and constraints in prompt or context.

Use claude_second_opinion to challenge this implementation plan: [paste plan]

challenge

Anti-sycophancy mode. The model is instructed to find weaknesses, not validate.

Use challenge to critique: "We should use a global singleton for database connections"

code_review

Systematic directory-based code review with BLOCKER/CRITICAL/MAJOR/MINOR classifications.

Use code_review on directory="./src" with focus_areas=["security", "performance"]

consensus

3-way debate where DeepSeek, Moonshot, and OpenAI share independent opinions, cross-critique, and optionally rebut. Returns structured transcript plus synthesis directive for Claude Code client (Opus 4.7 at extended/high thinking budget).

Use consensus to debate: "GraphQL vs REST for internal microservices"

review_synthesis

Full workflow: three parallel reviews (DeepSeek, Moonshot, OpenAI), debate via consensus, then synthesis instructions for the client.

Perform a comprehensive code review of ./myproject using review_synthesis

architect_review

Review an implementation plan before coding begins. Identifies architectural risks, missing edge cases, security gaps, and over-engineering. Defaults to OpenAI if enabled.

Use architect_review to review this plan: [paste plan document]

Use architect_review with context="We're building a REST API for a fintech startup"
to review: [paste design document]

implementation_review

Review actual code changes after implementation, optionally against the original plan. Analyzes for bugs, security issues, and quality. Defaults to OpenAI if enabled.

Use implementation_review on directory="./src"

Use implementation_review on directory="./src" with plan="[paste original plan]"
and save_to="./docs/reviews"

New in v0.9.0: consensus and review_synthesis are 3-way and delegate final synthesis to the Claude Code client (designed for Opus 4.7 with extended thinking at high budget). The consensus tool no longer accepts stances or include_reasoning parameters; it returns raw material + a synthesis directive. The fast parameter is removed from all tools (single-model policy).

Usage Examples

Thorough Code Review Workflow

For comprehensive code reviews, use this prompt pattern with Claude Code:

MyProject: perform a comprehensive deep parallel code review with deepseek and kimi
using mcp server second-opinion - save resulting md files to the project folder
to the docs subfolder in md format.

After that perform Consensus debate + arbiter synthesis using same mcp server tools
with opus 4.5 compiling a final document for the final review.

First 2 tasks can be run in parallel.

This triggers parallel code_review calls to DeepSeek and Moonshot, then a consensus debate on findings, and finally Claude synthesizes the final review document.

Plan-Then-Review Workflow

Use architect_review before coding and implementation_review after:

1. Use architect_review to review my plan: [paste plan]
2. [Make changes based on feedback]
3. Use implementation_review on directory="./src" with plan="[paste plan]"

Quick Second Opinion

Use second_opinion to review this database schema:
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255),
  password VARCHAR(255)
);

Critical Challenge

Use challenge to critique this proposal: "We should use a global singleton for
database connections because it's simpler"

Consensus Debate

Use consensus to debate: "GraphQL vs REST for our internal microservices API"

Code Review with Focus Areas

Use code_review on directory="./src" with focus_areas=["security", "error-handling"]
and save_to="./docs/reviews"

Configuration

Changing Providers

To reconfigure which providers are enabled, run the setup wizard again:

second-opinion-mcp setup

Or re-register the server with specific providers:

# Auto-detect all configured providers (default)
claude mcp add -s user second-opinion -- second-opinion-mcp

# Restrict to specific providers
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek,moonshot" -- second-opinion-mcp

API Key Management

Credentials are stored using platform-appropriate storage:

On Linux and headless macOS, credentials are stored in ~/.second-opinion-config with SSH-style permissions (600). This is the same security model used by SSH private keys.

OpenAI OAuth tokens are stored in ~/.second-opinion-config under openai_oauth and automatically refreshed at runtime. Codex CLI tokens from ~/.codex/auth.json are also supported as a fallback.

To update keys:

second-opinion-mcp setup

Or manually edit ~/.second-opinion-config (Linux/macOS headless):

{
  "credentials": {
    "deepseek": "sk-YOUR_DEEPSEEK_KEY",
    "moonshot": "YOUR_MOONSHOT_KEY",
    "openrouter": "sk-or-YOUR_OPENROUTER_KEY",
    "openai": "sk-YOUR_OPENAI_KEY"
  }
}

Then set permissions: chmod 600 ~/.second-opinion-config

Troubleshooting

"No API key configured" Error

Run the setup wizard again:

second-opinion-mcp setup

For OpenAI specifically, you can also authenticate via the setup wizard OAuth flow or Codex CLI:

# Recommended: built-in OAuth login
second-opinion-mcp setup  # Choose "Login with ChatGPT Plus (OAuth)"

# Alternative: Codex CLI
codex login

Connection Timeout

Check firewall, VPN, or proxy settings. Both DeepSeek (api.deepseek.com) and Moonshot (api.moonshot.ai) must be accessible.

Rate Limit Exceeded

Moonshot has rate limits (3 concurrent, 20 RPM at Tier 0). Wait a minute and retry.

Tool Not Found in Claude

Verify registration:

claude mcp list

If not listed, re-register:

claude mcp add -s user second-opinion -- second-opinion-mcp

Advanced Usage

Include Reasoning

See the model's chain-of-thought:

Use second_opinion with include_reasoning=true to analyze this algorithm

Focus Areas for Reviews

Use code_review with focus_areas=["security", "error-handling", "performance"]

Save Review Output

Use code_review on directory="./src" with save_to="./docs/reviews"

Updating

The server checks for updates on startup and notifies you if a new version is available.

To update manually:

pipx upgrade second-opinion-mcp

Or reinstall:

pipx uninstall second-opinion-mcp
pipx install second-opinion-mcp

Your API keys are preserved in the system keyring across updates.

Uninstalling

# Remove from Claude
claude mcp remove second-opinion

# Optional: remove stored API keys BEFORE uninstalling (requires pipx venv Python)
SOPYTHON=~/.local/share/pipx/venvs/second-opinion-mcp/bin/python3
$SOPYTHON -c "import keyring; keyring.delete_password('second-opinion', 'deepseek')"
$SOPYTHON -c "import keyring; keyring.delete_password('second-opinion', 'moonshot')"
$SOPYTHON -c "import keyring; keyring.delete_password('second-opinion', 'openrouter')"
$SOPYTHON -c "import keyring; keyring.delete_password('second-opinion', 'openai')"

# Uninstall package
pipx uninstall second-opinion-mcp

Security

API keys are stored in your OS keyring, not in environment variables or config files. OpenAI OAuth tokens are stored in ~/.second-opinion-config and refreshed automatically. Codex CLI tokens from ~/.codex/auth.json are also supported as a fallback. The code review tool:

• Skips .env files, credentials, SSH keys, and certificates
• Validates directories against allowed roots
• Detects symlinks to prevent traversal attacks
• Limits content size to prevent memory exhaustion

claude_second_opinion does not handle Claude credentials. It verifies an active Claude Max subscription through the CLI, launches Claude Code in safe mode from a neutral temporary directory, removes Anthropic API/provider environment overrides, passes the request over stdin, disables all tools, limits the run to one turn, and does not persist the session.

Cost Estimates

Per operation (typical usage):

OpenAI costs are higher per token than DeepSeek/Moonshot. Using OAuth login with ChatGPT Plus provides free access (subject to rate limits). OAuth flow ported from OpenClaw (MIT, github.com/openclaw/openclaw).

License

MIT License. See LICENSE file.

Links

• GitHub Repository
• Issue Tracker
• Changelog