Manual & per-client setup

Wire it up your way

Auto-setup covers most clients. For VS Code, Claude Desktop, or project-only configs ... here's every way to connect. The launch command is always the same:

$ npx --yes omni-vision-pro@latest serve
✓ Auto setup supported ... Codex CLI, desktop & IDE
$ codex mcp add omni-vision-pro -- npx --yes omni-vision-pro@latest serve

Or add this to ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.omni-vision-pro]
command = "npx"
args = ["--yes", "omni-vision-pro@latest", "serve"]
startup_timeout_sec = 120
tool_timeout_sec = 1200
enabled = true

Restart or start a new session, then check /mcp.

✓ Auto setup supported ... project & user config

Add to a project opencode.json / opencode.jsonc, or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "omni-vision-pro": {
      "type": "local",
      "command": ["npx", "--yes", "omni-vision-pro@latest", "serve"],
      "enabled": true,
      "timeout": 600000
    }
  }
}

On Windows, ~ means your user folder. Restart OpenCode and run opencode mcp list.

✓ Auto setup supported ... user & project scope
$ claude mcp add --scope user --transport stdio omni-vision-pro -- npx --yes omni-vision-pro@latest serve

Project scope from the project root (entries live in .mcp.json):

$ claude mcp add --scope project --transport stdio omni-vision-pro -- npx --yes omni-vision-pro@latest serve

Verify with claude mcp list.

✓ Auto setup supported + one-click install link

Put this in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "omni-vision-pro": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "omni-vision-pro@latest", "serve"]
    }
  }
}

Reload the window, then open Settings > Tools & MCP and enable the server if needed.

ℹ Manual setup ... run MCP: Add Server from the Command Palette, or create .vscode/mcp.json:
{
  "servers": {
    "omni-vision-pro": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "omni-vision-pro@latest", "serve"]
    }
  }
}

Start it from the inline action, run MCP: List Servers, and approve the trust prompt.

ℹ Manual setup ... add to claude_desktop_config.json:
{
  "mcpServers": {
    "omni-vision-pro": {
      "command": "npx",
      "args": ["--yes", "omni-vision-pro@latest", "serve"]
    }
  }
}

Windows: %APPDATA%\Claude\claude_desktop_config.json · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Completely quit & reopen Claude Desktop after saving.

Troubleshooting

Stuck? Here's the fix

Clipboard import cannot find the key

Copy only the Gemini/OpenAI key, then run provider set --from-clipboard again.

A key was added but OCR is still active

Run provider status, then provider on, and restart/reload the AI client.

The wrong AI provider is being used

Run provider, choose the provider you want, then restart/reload the AI client.

The client cannot find npx

Install Node.js 20.10+, restart the client, or replace npx with its full path such as C:\Program Files\nodejs\npx.cmd.

The server is installed but not visible

Run doctor, restart/reload the client, then approve the server or project trust prompt.

An image attachment is not found

Attach the image in the same request, or pass its inline data URL. No special copy folder is needed.

OCR takes too long

The first OCR request starts a local worker. Keep client tool timeouts above 90 seconds; image arrays run sequentially.

Gemini reports a retired model

Set GEMINI_MODEL=gemini-2.5-flash in the private .env.

Code or ZIP access is denied

If OMNI_ALLOWED_ROOTS is set, include the intended project folder, restart the client, and try again.

A config entry looks wrong

Setup preserves unrelated settings and creates backups before changing JSON/JSONC client files.

Skip the manual work ... one command

Let the installer detect, configure and verify everything for you.

See the guided setup