alper
/
claudish
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
claudish/docs/usage/mcp-server.md

5.6 KiB
Raw Blame History

MCP Server Mode

Use OpenRouter models as tools inside Claude Code.

Claudish isn't just a CLI. It's also an MCP server that exposes external AI models as tools.

What does this mean? Claude can call Grok, GPT-5, or Gemini mid-conversation to get a second opinion, run a comparison, or delegate specialized tasks.

Quick Setup

1. Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "claudish": {
      "command": "claudish",
      "args": ["--mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
      }
    }
  }
}

2. Restart Claude Code

3. Use it:

Ask Grok to review this function

Claude will use the run_prompt tool to call Grok.

Available Tools

run_prompt

Run a prompt through any OpenRouter model.

Parameters:

  • model (required) - OpenRouter model ID. Must be specified explicitly.
  • prompt (required) - The prompt to send
  • system_prompt (optional) - System prompt for context
  • max_tokens (optional) - Max response length (default: 4096)

Model IDs:

Common Name Model ID
Grok x-ai/grok-code-fast-1
GPT-5 Codex openai/gpt-5.1-codex
Gemini 3 Pro google/gemini-3-pro-preview
MiniMax M2 minimax/minimax-m2
GLM 4.6 z-ai/glm-4.6
Qwen3 VL qwen/qwen3-vl-235b-a22b-instruct

Example usage:

Ask Grok to review this function
→ run_prompt(model: "x-ai/grok-code-fast-1", prompt: "Review this function...")

Use GPT-5 Codex to explain the error
→ run_prompt(model: "openai/gpt-5.1-codex", prompt: "Explain this error...")

Tip: Use list_models first to see all available models with pricing.

list_models

List recommended models with pricing and capabilities.

Parameters: None

Returns: Table of curated models with:

  • Model ID
  • Provider
  • Pricing (per 1M tokens)
  • Context window
  • Capabilities (Tools, Reasoning, Vision)

search_models

Search all OpenRouter models.

Parameters:

  • query (required) - Search term (name, provider, capability)
  • limit (optional) - Max results (default: 10)

Example:

Search for models with "vision" capability

compare_models

Run the same prompt through multiple models and compare.

Parameters:

  • models (required) - Array of model IDs
  • prompt (required) - The prompt to compare
  • system_prompt (optional) - System prompt

Example:

Compare responses from Grok, GPT-5, and Gemini for: "Explain this regex"

Use Cases

Get a Second Opinion

You're working with Claude, but want GPT-5's take:

Claude, use GPT-5 Codex to review the error handling in this function

Specialized Tasks

Some models excel at specific things:

Use Gemini 3 Pro (it has 1M context) to analyze this entire codebase

Multi-Model Validation

Before making big changes:

Compare what Grok, GPT-5, and Gemini think about this architecture decision

Budget Optimization

Route simple tasks to cheap models:

Use MiniMax M2 to generate basic boilerplate for these interfaces

Configuration

Environment Variables

The MCP server reads OPENROUTER_API_KEY from environment.

In Claude Code settings:

{
  "mcpServers": {
    "claudish": {
      "command": "claudish-mcp",
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

Or export globally:

export OPENROUTER_API_KEY='sk-or-v1-...'

Using npx (No Install)

{
  "mcpServers": {
    "claudish": {
      "command": "npx",
      "args": ["claudish@latest", "--mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

How It Works

┌─────────────┐     MCP Protocol      ┌─────────────┐     HTTP      ┌─────────────┐
│ Claude Code │ ◄──────────────────► │   Claudish  │ ◄───────────► │ OpenRouter  │
│             │     (stdio)           │  MCP Server │               │    API      │
└─────────────┘                       └─────────────┘               └─────────────┘
  1. Claude Code sends tool call via MCP (stdio)
  2. Claudish MCP server receives it
  3. Server calls OpenRouter API
  4. Response returned to Claude Code

CLI vs MCP: When to Use Which

Use Case Mode Why
Full alternative session CLI Replace Claude entirely
Get second opinion MCP Quick tool call mid-conversation
Batch automation CLI Scripts and pipelines
Model comparison MCP Easy multi-model comparison
Interactive coding CLI Full Claude Code experience
Specialized subtask MCP Delegate to expert model

Debugging

Check if MCP server starts:

OPENROUTER_API_KEY=sk-or-v1-... claudish --mcp
# Should output: [claudish] MCP server started

Test the tools: Use Claude Code and ask it to list available MCP tools. You should see run_prompt, list_models, search_models, and compare_models.

Limitations

Streaming: MCP tools don't stream. You get the full response when complete.

Context: The MCP tool doesn't share Claude Code's context. You need to pass relevant info in the prompt.

Rate limits: OpenRouter has rate limits. Heavy parallel usage might hit them.

Next