Polybrain MCP Server

# Polybrain MCP Server An MCP (Model Context Protocol) server for connecting AI agents to multiple LLM models. Supports conversation history, model switching, and seamless Claude Code integration. ## Features - Multi-model support (OpenAI, OpenRouter, custom endpoints) - Conversation history management - Switch models mid-conversation - Extended thinking/reasoning support (configurable by provider) - Pure MCP protocol (silent by default) - Automatic server management ## Installation ```bash npm install -g polybrain # or pnpm add -g polybrain ``` ## Quick Setup ### 1. Configure Models **Option A: YAML (recommended)** Create `~/.polybrain.yaml`: ```yaml models: - id: "gpt-4o" modelName: "gpt-4o" baseUrl: "https://api.openai.com/v1" apiKey: "${OPENAI_API_KEY}" provider: "openai" - id: "gpt-5.1" modelName: "openai/gpt-5.1" baseUrl: "https://openrouter.io/api/v1" apiKey: "${OPENROUTER_KEY}" provider: "openrouter" ``` Set env vars: ```bash export OPENAI_API_KEY="sk-..." export OPENROUTER_KEY="sk-or-..." ``` **Option B: Environment variables** ```bash export POLYBRAIN_BASE_URL="https://api.openai.com/v1" export POLYBRAIN_API_KEY="sk-..." export POLYBRAIN_MODEL_NAME="gpt-4o" ``` ### 2. Coding Agent Integration #### Claude Code Run the following command to add Polybrain to Claude Code: ```bash claude mcp add -s user -t stdio polybrain -- polybrain ``` #### OpenAI Codex Open `~/.codex/config.toml` and add: ```toml [mcpServers.polybrain] command = "polybrain" ``` ## Usage You can now ask your coding agent to consult specific models. For example: > "Ask deepseek what's the best way to install python on mac" Or: > "What models are available from polybrain?" ## Configuration Reference ### Environment Variables - `POLYBRAIN_BASE_URL` - LLM API base URL - `POLYBRAIN_API_KEY` - API key - `POLYBRAIN_MODEL_NAME` - Model name - `POLYBRAIN_HTTP_PORT` - Server port (default: 32701) - `POLYBRAIN_LOG_LEVEL` - Log level (default: info) - `POLYBRAIN_DEBUG` - Enable debug logging to stderr - `POLYBRAIN_CONFIG_PATH` - Custom config file path ### YAML Config Fields ```yaml httpPort: 32701 # Optional truncateLimit: 500 # Optional logLevel: info # Optional models: # Required - id: "model-id" # Internal ID modelName: "actual-model-name" # API model name baseUrl: "https://api.url/v1" # API endpoint apiKey: "key or ${ENV_VAR}" # API key provider: "openai" # Optional: provider type for reasoning support ``` ### Supported Providers The `provider` field enables provider-specific features like extended thinking/reasoning. If not specified, reasoning parameters will not be passed to the API (safe default). | Provider | Reasoning Support | Valid Values | |----------|-------------------|--------------| | OpenAI | YES | `"openai"` | | OpenRouter | VARIES | `"openrouter"` | **Examples:** - Use `provider: "openai"` for OpenAI API models (GPT-4, o-series) - Use `provider: "openrouter"` for OpenRouter proxy service (supports 400+ models) - Omit `provider` field if your endpoint doesn't support reasoning parameters **Example with reasoning:** ```yaml models: - id: "gpt-o1" modelName: "o1" baseUrl: "https://api.openai.com/v1" apiKey: "${OPENAI_API_KEY}" provider: "openai" # Enables reasoning support - id: "gpt-5.1" modelName: "openai/gpt-5.1" baseUrl: "https://openrouter.io/api/v1" apiKey: "${OPENROUTER_KEY}" provider: "openrouter" # Enables reasoning support ``` To use reasoning, set `reasoning: true` in the chat tool call. If the model and provider support it, you'll receive both the response and reasoning content. ## Development ### Setup ```bash pnpm install ``` ### Build ```bash pnpm build ``` ### Lint & Format ```bash pnpm lint pnpm format ``` ### Type Check ```bash pnpm type-check ``` ### Development Mode ```bash pnpm dev ``` ## Project Structure ``` src/ ├── bin/polybrain.ts # CLI entry point ├── launcher.ts # Server launcher & management ├── http-server.ts # HTTP server ├── index.ts # Main server logic ├── mcp-tools.ts # MCP tool definitions ├── conversation-manager.ts ├── openai-client.ts ├── config.ts ├── logger.ts └── types.ts ``` ## Debugging Enable debug logs to stderr: ```json { "mcpServers": { "polybrain": { "command": "polybrain", "env": { "POLYBRAIN_DEBUG": "true" } } } } ``` ## Restart Server After changing configuration in `~/.polybrain.yaml`, restart the HTTP backend server: ```bash polybrain --restart ``` This kills the background HTTP server. The next time you use polybrain, it will automatically start a fresh server with the updated configuration. ## License MIT