mcp-openrouter: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies (uses uv)
uv sync

# Install with dev dependencies
uv sync --dev

# Install MCP server for Claude Code
claude mcp add openrouter --scope user -- uv run --directory /path/to/mcp-openrouter mcp-openrouter

# Run the server (uses AgentBridge)
uv run mcp-openrouter

# Run tests (live gateway tests are opt-in)
uv run pytest tests/

# Run a single test
uv run pytest tests/test_tools.py::TestChatTool::test_chat_returns_string -v

# Lint with ruff
uv run ruff check src/
uv run ruff format src/

Configuration

Environment variables (an optional gateway token is injected from Infisical; non-secret defaults may remain in .env):

Variable	Description
AGENTBRIDGE_API_KEY	Optional gateway access token
DEFAULT_TEXT_MODEL	Default model for chat tool (e.g., anthropic/claude-sonnet-4)
DEFAULT_IMAGE_MODEL	Default model for generate_image tool (e.g., google/gemini-3-pro-image-preview)
DEFAULT_CODE_MODEL	Default model for code-related tasks
DEFAULT_VISION_MODEL	Default model for vision tasks
DEFAULT_EMBEDDING_MODEL	Default model for embed tool (e.g., mistralai/mistral-embed-2312)

When default models are configured, the model parameter becomes optional in tool calls.

Architecture

This is an MCP (Model Context Protocol) server built with FastMCP that exposes OpenRouter's API as tools.

Key components:

• src/mcp_openrouter/server.py - MCP server with tool definitions (chat, generate_image, embed, list_models, find_models)
• src/mcp_openrouter/client.py - OpenRouterClient class handling API requests with retry logic
• src/mcp_openrouter/config.py - Configuration management for default models

Flow: MCP tools in server.py → get_client() → OpenRouterClient methods → AgentBridge API

Entry point: mcp-openrouter CLI command runs server:main() which starts the FastMCP server.