Opti

Your providers. Your preferred models. One MCP connection.

Opti delegates tasks from Codex, Claude, or another MCP client to the provider and model you choose. For example, keep your host agent for orchestration, send a coding question to your coding model, generate images through an Images API, and send research to a search-capable specialist.

The local control panel replaces manual JSON editing for everyday setup. Routing itself runs locally without an extra LLM classification call. There is no universal “best” model or promised cost saving: you control the choices, and provider API usage is billed separately from host-agent subscriptions.

Start

Requires Node.js 20 or later.

npm install
npm run build
npm run ui

Open the local control panel.

1. Click Provider in the header, choose a service from the dropdown, and enter your API key. For a custom service, also enter its name and base URL.

2. Opti automatically fetches the models available through that provider's API. Lists refresh when you open the page or save the provider again, including pagination where supported.

3. In each task row, choose a provider and model. The choice saves immediately. With one connected provider, its model list is already selected for all unconfigured rows.

The UI is a single wide page. There is no sidebar, dashboard, playground, or separate setup page. Existing fallbacks are preserved when the primary model changes; advanced routing settings remain editable in JSON. If a provider cannot list models, the row explains the error and lets you enter an exact model ID manually. API modes are inferred for new routes; existing explicit modes are preserved. OpenAI text routes use Responses, image routes use Images, and OpenAI deep research uses background research. Other research routes use Chat and require a search-capable model. Configure apiMode in JSON for custom Responses or research endpoints.

MCP connection examples are below. The UI listens on 127.0.0.1:4310. Set OPTIM_UI_PORT to change the port. It is a local administration app, not a public hosted service. MCP clients do not need the UI process to stay running.

Related MCP server: Multi-Model Orchestrator

Providers and API modes

Presets: OpenAI, NVIDIA NIM, Anthropic, Google Gemini, OpenRouter, DeepSeek, Groq, Perplexity, Mistral, MiniMax, xAI, and Ollama.

Custom connections can use OpenAI-compatible or Anthropic-compatible APIs. For a service called Nimbus, for example, enter its documented base URL, authentication, and exact model ID; Opti does not assume which service or endpoint that name refers to. Other protocols need a new adapter. Model availability and supported capabilities depend on your provider account.

Deep research can also use Chat with a provider model that performs its own search, such as Perplexity's sonar-deep-research. Selecting the research task does not give an ordinary chat model browsing tools. NVIDIA models use the Chat API; the preset does not imply that every NVIDIA model supports images or native research.

Model discovery retrieves the provider's /models list; some services do not expose it. Enter an exact model ID manually in that case. The list is not a capability test. It includes the IDs returned by the API rather than a static list of model names. Use the full API ID your provider exposes for Astra, Sol, Nemotron, or any other model, rather than assuming the display name is an API ID.

Routing behavior

• Six task types: coding, reasoning, planning, agentic, image_generation, and deep_research.

• An explicit taskType takes precedence. Otherwise, local keyword rules detect the task; use a hint for ambiguous or mixed requests.

• Routes use saved preference order by default. Disabled providers and providers without credentials or base URLs are skipped.

• Optional provider and model inputs restrict selection to matching entries in that task route.

• Fallbacks stay within the chosen task and your configured order. No provider receives a hard-coded preference bonus.

• Explicit authentication, unavailable endpoint/model, and rate-limit rejections can advance to a fallback. Timeouts, network errors, HTTP 5xx, and ambiguous responses stop rather than potentially duplicating paid work. Check provider status before resubmitting.

• Prompts and credentials are not included in activity records. Available token usage is shown; actual prices and savings are not estimated.

• Graphify integration is preserved for coding and repository requests. Deep research includes it only when a repository/graph path is supplied; images never include it.

strategy: "balanced" remains available in JSON for users who maintain legacy capability/cost/speed scores. Those are manually configured heuristic scores, not measured prices or live benchmarks. The UI changes the primary model while preserving existing fallbacks; keep strategy: "ordered" for predictable primary/fallback selection.

MCP clients

npm start starts the stdio MCP server, not the browser UI. A terminal waiting for input is expected. MCP output goes to stdout; diagnostic logs go to stderr.

For Codex, add this configuration with the absolute paths for your installation:

[mcp_servers.opti]
command = "node"
args = ["C:/path/to/optim/dist/index.js"]
tool_timeout_sec = 660

[mcp_servers.opti.env]
OPTIM_CONFIG_PATH = "C:/Users/you/.optim/config.json"

For Claude Desktop or Claude Code, merge this entry into your existing MCP configuration:

{
  "mcpServers": {
    "opti": {
      "command": "node",
      "args": ["/absolute/path/to/optim/dist/index.js"],
      "env": { "OPTIM_CONFIG_PATH": "/absolute/path/to/.optim/config.json" }
    }
  }
}

Restart/reconnect the client after adding MCP. Route edits are read on the next request without restarting.

Example input:

{ "prompt": "Research battery recycling with primary sources.", "taskType": "deep_research" }

You can say “Use Opti to do deep research on …” or “Use Opti to generate an image of …” in your host agent. Opti also exposes an MCP prompt named opti. A client may show it as a slash command, but /opti, /opti:opti, or another spelling is client-specific; registering an MCP server does not guarantee a universal slash command.

The host agent retains file access, terminal commands, and tool execution. The agentic route delegates model analysis; it does not start an autonomous tool-using agent or replace the host's model.

Images and research

Image generation returns MCP image content when the provider returns base64, or an image URL when the provider returns a URL. The host MCP client displays the result when it supports image content. Timeout: 180 seconds.

Native background research returns a jobId. Call opti_result with that ID, at least 10 seconds apart, until completed. Jobs are recorded next to the settings file and can be retrieved from another MCP process through opti_result. Do not resubmit the prompt to check progress. Changing a provider's endpoint prevents retrieval until the original endpoint is restored. Retrieval remains subject to the provider's retention policy. Chat-based research is synchronous with a ten-minute timeout.

Local configuration and credentials

Default settings: ~/.optim/config.json. Override with OPTIM_CONFIG_PATH; use the same absolute path in the UI and MCP processes. Activity metadata is stored in an activity/ directory beside that file.

Keys entered in the UI are stored as plaintext in this local file. Opti requests owner-only file permissions on POSIX; on Windows the file inherits your account's directory ACLs. They are omitted from browser responses and MCP results. To keep keys out of the file, use environment variables instead. An explicitly configured environment variable takes precedence over a saved key. Blank key fields preserve a saved key. To remove a key, clear it in the local JSON configuration; this does not unset an environment variable.

The server rejects cross-origin requests and unexpected Host headers, requires a session token for API actions, and checks configuration revisions before writing. Provider redirects are not followed with credentials. Only HTTPS provider endpoints are accepted, except HTTP on loopback for local models.

Existing project .env credentials and src/config/models.json are still supported. A saved UI route overrides the legacy JSON list for that task, including an explicitly empty list. Keys and base URLs in saved provider entries take precedence except for an explicit apiKeyEnv; provider presets also recognize their documented environment variables.

An editable example with no keys is provided in opti.config.example.json. Copy it to your chosen settings location and replace model IDs with the IDs available to your account. The UI can configure everything without this file.

Development and verification

npm run typecheck
npm test
npm run test:ui

Integration tests use local mock APIs and a real MCP stdio client. Browser tests cover automatic model discovery, immediate saving, fallback preservation, and the compact layout. They use headless Microsoft Edge by default; set OPTIM_BROWSER_CHANNEL=chromium after npx playwright install chromium on machines without Edge. Screenshots are written to the ignored artifacts/ directory. No test requires an API key or incurs provider charges.

Implementation references: Codex MCP, OpenAI deep research, OpenAI images, NVIDIA NIM, Gemini compatibility, and Perplexity Sonar.