cpal - your pal Claude

An MCP server that lets any AI consult Claude.

The inverse of gpal — where gpal lets Claude consult Gemini, cpal lets Gemini (or any MCP client) consult Claude.

Features

• 🧠 Opus by default — deep reasoning (Fable/Sonnet/Haiku available)
• 💭 Extended thinking — explicit chain-of-thought for complex analysis
• 🔧 Autonomous exploration — Claude reads files and searches your codebase
• 📸 Vision — analyze images and PDFs
• 💬 Stateful sessions — conversation history preserved across calls
• 📦 Batch API — fire-and-forget processing at 50% cost discount
• 🔢 Token counting — free endpoint to estimate costs before sending
• 🎛️ Effort control — tune output effort from "low" to "max"
• 📚 1M context — opt-in extended context window (beta, requires Anthropic API tier 4+)

Install

Requires uv.

git clone https://github.com/tobert/cpal &&cd cpal
uv tool install .

API Key (choose one)

Option A: Key file (recommended)

mkdir -p ~/.config/cpal && chmod 700 ~/.config/cpal
echo"sk-ant-...">~/.config/cpal/api_key && chmod 600 ~/.config/cpal/api_key

Option B: Environment variable

export ANTHROPIC_API_KEY="sk-ant-..."

If both are set, --key-file takes priority over the environment variable.

Configure

Pick the method that matches your MCP client:

Gemini CLI

gemini mcp add cpal --scope user -- cpal --key-file ~/.config/cpal/api_key

Claude Code

Useful for getting a second opinion from a different Claude instance, or delegating tasks to a specific model tier (e.g. using Opus for deep analysis while running Claude Code on Sonnet).

claude mcp add cpal --scope user -- cpal --key-file ~/.config/cpal/api_key

Manual (Cursor, etc.)

Add to your MCP config (~/.cursor/mcp.json, etc.):

{
"mcpServers": {
"cpal": {
"command": "cpal",
"args": ["--key-file", "/home/you/.config/cpal/api_key"]
}
}
}

Or with env var:

{
"mcpServers": {
"cpal": {
"command": "cpal",
"env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
}
}
}

Usage

Your AI host calls these MCP tools automatically based on your prompts. The examples below show the tool signatures — you don't call them directly, you just ask your AI to consult Claude.

"Ask Claude to review src/server.py for bugs" triggers consult_claude(query="...", file_paths=[...])

"Have Claude design a caching strategy" triggers consult_claude(query="...")

Cost note: Opus is the default model and the most expensive. Use model="haiku" or model="sonnet" for lower costs.

Tool Reference

# Basic (uses Opus)consult_claude(query="Design a caching strategy for this API")
# Extended thinking is enabled by default (extended_thinking=True)# Control the thinking budget (default 10000, max ~100000)consult_claude(query="Analyze this algorithm", thinking_budget=50000)
# Disable thinking for simple queriesconsult_claude(query="What does this function do?", extended_thinking=False)
# Visionconsult_claude(query="What's wrong with this UI?", media_paths=["screenshot.png"])
# Different modelsconsult_claude(query="Hardest problem", model="fable") # most capable, premium costconsult_claude(query="Hard problem", model="opus") # deep reasoningconsult_claude(query="Quick check", model="haiku") # fast & cheap# Multi-turn conversationconsult_claude(query="Explain the auth flow", session_id="review-123")
consult_claude(query="What about edge cases?", session_id="review-123") # continues# Effort control — tune output depth (low, medium, high, max)consult_claude(query="Quick summary", effort="low")
consult_claude(query="Exhaustive analysis", effort="max")
# 1M context window (beta, tier 4+, premium pricing above 200K tokens)consult_claude(query="Analyze this large codebase", context_1m=True)
# Per-call tool call cap (override the default 1000)consult_claude(query="Quick scan", max_tool_calls=50)

Utility Tools

# List available models and their resolved IDslist_models()
# Count tokens before sending (free — no API cost)count_tokens(query="Review this code: ...", model="opus")
count_tokens(query="...", file_paths=["src/server.py"]) # includes file content

How It Works

MCP Client (Gemini, Cursor, etc.)
│
▼ MCP
┌─────────┐
│ cpal │ ──▶ Anthropic API ──▶ Claude
└─────────┘
│
cpal gives Claude these tools to
autonomously explore your codebase:
• list_directory
• read_file
• search_project

Custom System Prompts

Customize what Claude "knows" about you, your project, or your workflow by composing system prompts from multiple sources.

Config file (~/.config/cpal/config.toml):

# Files loaded in order and concatenatedsystem_prompts = [
"~/.config/cpal/CLAUDE.md",
]
# Inline text appended after filessystem_prompt = "常に日本語で回答してください (Always respond in Japanese)"# Set to false to fully replace the built-in prompt with your owninclude_default_prompt = true

Paths support ~ and $ENV_VAR expansion, so you can use $WORKSPACE/CLAUDE.md etc.

CLI flags (repeatable, concatenated in order):

# Append additional prompt files
cpal --system-prompt /path/to/project-context.md
# Multiple files
cpal --system-prompt ~/CLAUDE.md --system-prompt ./PROJECT.md
# Replace the built-in prompt entirely
cpal --system-prompt ~/my-prompt.md --no-default-prompt

Composition order:

1. Built-in cpal system prompt (unless include_default_prompt = false or --no-default-prompt)
2. Files from system_prompts in config.toml
3. Inline system_prompt from config.toml
4. Files from --system-prompt CLI flags

Check what's active via resource://server/info — it shows which sources contributed and the total prompt length.

Security

• All file access is sandboxed to the directory where cpal was started
• Path traversal and symlink attacks are blocked
• Sessions are isolated per session_id
• File size limits: 10MB text, 20MB media
• Secret-file denylist: Built-in patterns block reads of common secret files (.env*, *.pem, *.key, *_key, id_rsa*, .git/config, etc.) across all read surfaces. Extend the list via denied_path_patterns in ~/.config/cpal/config.toml — config patterns add to built-ins, they never replace them. The .env file is never auto-loaded for the API key; use --key-file or ANTHROPIC_API_KEY.
• Note: the read-only git tool can still reveal whole-repository commit history (e.g. git log or git show without a path argument), even when cpal is started in a subdirectory of a larger repository, because git operates on the full repository from any subdirectory.

Batch API

These are MCP tools your AI host can call — same as consult_claude, but for async bulk processing at 50% cost discount. Batches complete within 24 hours.

# Submit a batch (any tier works — including Fable)create_batch(queries=[
{"custom_id": "review-1", "query": "Review this code: ..."},
{"custom_id": "review-2", "query": "Review this other code: ..."},
], model="fable")
# Check statuslist_batches()
get_batch(batch_id="msgbatch_...")
# Get results when doneget_batch_results(batch_id="msgbatch_...")
# Cancel a processing batchcancel_batch(batch_id="msgbatch_...")

No delete API — Anthropic does not provide an endpoint to delete batch results. Batches are automatically purged after 29 days.

No tool use — batch queries are single-shot (no agentic file exploration). Parameters like file_paths and media_paths are not available in batch mode — paste content directly into the query string.

MCP Resources

Read-only introspection endpoints for MCP clients that support resources:

URI	Description
resource://server/info	Server version, capabilities, and feature list
resource://models	Available models with IDs, descriptions, and defaults
resource://config/limits	Safety limits (file sizes, search caps, session TTL)
resource://sessions	List all active sessions
resource://session/{session_id}	Details for a specific session (message count, preview)
resource://tools/internal	Tools Claude uses for autonomous exploration

Models

Model aliases are resolved automatically to the latest version per tier via the Anthropic API. Use list_models() to see current mappings. Fallback IDs if the API is unreachable:

Alias	Fallback ID	Best For
fable	claude-fable-5	Most capable — frontier intelligence, premium cost
opus	claude-opus-4-8	Deep reasoning, hard problems (default)
sonnet	claude-sonnet-4-6	Balanced reasoning, code review
haiku	claude-haiku-4-5	Fast exploration, quick questions

Claude can make up to 1000 autonomous tool calls per query by default. Override globally with the CPAL_MAX_TOOL_CALLS environment variable, or per-call with max_tool_calls=N on consult_claude.

Notes

• Sessions are in-memory — history is lost when the server restarts. Sessions are eligible for expiry after 1 hour of inactivity; cleanup runs when the active session count exceeds 100.
• Models cost money — Opus is the default and the most expensive. See Anthropic pricing. Use haiku or sonnet for lower costs.
• Vision — Supports PNG, JPEG, GIF, WebP, and PDF (max 20MB).
• 1M context — Requires Anthropic API tier 4+. Premium pricing applies above 200K tokens. The standard context window is 200K tokens; pass context_1m=True to access the 1M window via the beta endpoint.

Development

uv sync --all-extras
uv run pytest tests/test_tools.py -v # unit tests (free)

⚠️ Running pytest tests/ with ANTHROPIC_API_KEY set will run integration tests that cost money. See CLAUDE.md for details.

License

MIT