Optibot MCP Server

The Optibot MCP (Model Context Protocol) server connects Optibot’s code review engine to AI-enabled editors and tools that support the MCP standard — including Claude Desktop, Cursor, Windsurf, and Claude Code.

Once installed and configured, you can trigger code reviews, compare branches, review diffs, and manage API keys using natural language prompts directly inside your AI editor.

How It Works

The MCP server runs locally on your machine and exposes Optibot’s capabilities as tools. When you ask your AI editor to “review my changes” or “compare this branch,” the editor calls the appropriate MCP tool, which sends the code to Optibot’s review engine and streams the results back into your editor session. Agent-mode reviews are the exception: review_agent has no progress stream, so the server polls for the result and returns it in one piece.

Available actions through MCP:

• Review uncommitted local changes, a branch diff, or a patch file
• Run an agent-mode review that returns structured findings a coding agent can act on
• Detect merge conflicts as part of a branch review
• List, switch, and inspect your organizations
• Run and inspect supply-chain security scans, and manage their configuration
• Manage Optibot API keys, and mint a long-lived key for CI
• Check authentication, the active organization, and your review quota

Requirements

• Node.js 22 or later. The server declares "node": ">=22.0.0", and older versions fail at runtime.
• An Optibot account at agents.getoptimal.ai.

Install

The setup blocks below launch the server with npx, which downloads it on demand and picks up each new release, so no install step is needed.

To install it once and pin that copy instead:

npm install -g @optimalai/optibot-mcp

If you do, replace "command": "npx" and its args with "command": "optibot-mcp" in the configuration below.

Setup

Claude Desktop

Add the following to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "optibot": {
      "command": "npx",
      "args": ["-y", "@optimalai/optibot-mcp"],
      "env": {
        "OPTIBOT_API_KEY": "optk_your_key_here"
      }
    }
  }
}

Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json or via Cursor Settings → MCP):

{
  "mcpServers": {
    "optibot": {
      "command": "npx",
      "args": ["-y", "@optimalai/optibot-mcp"],
      "env": {
        "OPTIBOT_API_KEY": "optk_your_key_here"
      }
    }
  }
}

Windsurf

Add this to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "optibot": {
      "command": "npx",
      "args": ["-y", "@optimalai/optibot-mcp"],
      "env": {
        "OPTIBOT_API_KEY": "optk_your_key_here"
      }
    }
  }
}

Claude Code

Run this in your terminal (no config file needed):

claude mcp add optibot -e OPTIBOT_API_KEY=optk_your_key_here -- npx -y @optimalai/optibot-mcp

The -e flag stores the key in the MCP server configuration, so it is there whenever Claude Code spawns the server. Exporting OPTIBOT_API_KEY in your shell afterwards does not work: Claude Code starts the server as a child process, and a variable set in the terminal after it is already running never reaches it.

Authentication

You have two authentication options:

Option 1: API Key (recommended) Set the OPTIBOT_API_KEY environment variable in your MCP configuration as shown above. Generate an API key at agents.getoptimal.ai → Settings → API Keys.

Option 2: Browser Login If no API key is set, run optibot login in your terminal. This opens a browser window for OAuth login via your Optibot account. After completing the flow, the MCP server uses the stored credentials automatically.

How to Use

Once the MCP server is running and your editor is connected, use natural language:

Available Tools

The server registers 23 tools. Your editor calls them for you when you ask in natural language, but the names are useful when you want to invoke one directly or read a tool log.

Reviews

Organizations

OPTIBOT_API_KEY takes precedence over ~/.optibot/config.json, and the setup blocks above put the key in your MCP configuration. While it is set, switch_organization re-scopes and saves a token that nothing reads back, so the switch does not take effect. An optk_ key is in any case permanently bound to the organization that was active when it was created. To act as a different organization, create a key for it and put that key in your MCP configuration. The CLI refuses outright in the same situation; see Organizations & Account Status.

Authentication and API keys

Security scans

Agent review mode

review_agent is for when the caller is a coding agent that already holds the working copy and wants structured findings to act on, rather than prose written for a person. It returns a findings array where each entry carries a file, a line range, a severity, a category, a confidence score, and often a suggested fix, alongside a one-paragraph summary and an overall pass or fail.

Two optional inputs let you give the reviewer context it would otherwise have to ask for:

The tool is single-shot. When a result reports missing context, it names the files it wanted, and your editor calls the tool again with those paths in relatedPaths. The server does not loop on your behalf. The Optibot CLI does, if you would rather it handled the rounds for you.

Two timeouts bound the call. The service stops an agent review at its own ten-minute limit, and the MCP server gives up polling after fifteen minutes and returns an error rather than waiting indefinitely.

Two details worth knowing before you act on a result:

• A finding’s id labels it inside one response and is not stable between runs. To recognise a finding you have seen before, compare its file, line range, and category.
• A suggestedFix is model output derived from the reviewed code. Show it to the user and get their agreement before applying it.