Okareo MCP Server

Okareo MCP Server

The Okareo MCP server exposes Okareo's evaluation capabilities as MCP tools, allowing AI coding assistants to create and manage scenarios, register models, run evaluations, and execute multi-turn simulations directly from your editor.

For detailed documentation, see the Okareo MCP docs.

Prerequisites

• An Okareo account at app.okareo.com
• A copilot that supports MCP servers (Claude Code, Cursor, or VS Code)
• Python 3.10–3.12 (only for the local install modes; not needed for remote)

---

Remote MCP (hosted) — recommended

The fastest way to get started. No local install, no Python, no API key in .mcp.json. Browser sign-in handles auth on first connect.

Recommended (OAuth — Claude Code, Claude Desktop, Cursor, VS Code 1.101+)

Add to your copilot's MCP config (typically .mcp.json):

{
  "mcpServers": {
    "okareo": {
      "type": "http",
      "url": "https://tools.okareo.com/mcp"
    }
  }
}

Reload the copilot. It will open a browser to Okareo sign-in once; thereafter the copilot stores the token itself. Your .mcp.json contains no secrets.

Fallback (Bearer header — older clients or headless / CI)

For clients that haven't shipped the MCP OAuth flow yet, paste your API key as a bearer header. Prefer the env-var form over an inline literal:

{
  "mcpServers": {
    "okareo": {
      "type": "http",
      "url": "https://tools.okareo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:OKAREO_API_KEY}"
      }
    }
  }
}

Working across multiple Okareo organizations

If your Okareo account belongs to more than one organization (tenant), the remote MCP exposes two conversational tools so you don't have to leave the copilot to switch:

• list_tenants — show every organization you have access to. Marks which one this session is currently operating against.
• switch_tenant(tenant_id) — change the active organization for subsequent tool calls in this session.

The selection is session-scoped: it lasts as long as the MCP connection stays alive. If you close and reopen the copilot, ask the LLM to re-switch (or just re-issue switch_tenant from the resumed conversation). Tenant selection requires the OAuth path; on the API-key fallback path both tools return tenant_selection_requires_oauth because each API key is already pinned to one organization.

---

Local install (alternative)

Run the MCP server on your own machine. Useful for offline / airgapped environments and for development.

Prefer the Remote MCP section above unless you have a specific reason to install locally (airgapped, custom build, development on this repo). The remote endpoint requires no install and stays current automatically.

For multi-org users, the remote endpoint also exposes tenant management tools (list_tenants, switch_tenant).

Step 1: Set Your API Key

export OKAREO_API_KEY="your-api-key"

Add this to your ~/.zshrc or ~/.bash_profile for persistence.

Step 2: Configure Your Copilot

Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "okareo": {
      "command": "uvx",
      "args": ["okareo-mcp"],
      "env": {
        "OKAREO_API_KEY": "${OKAREO_API_KEY}"
      }
    }
  }
}

No pre-install needed — uvx handles it automatically.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "okareo": {
      "command": "uvx",
      "args": ["okareo-mcp"]
    }
  }
}

Cursor inherits OKAREO_API_KEY from your shell environment.

Alternative: pip install

If you don't have uv installed:

pip install okareo-mcp

Then use "command": "okareo-mcp" instead of "command": "uvx" with "args": ["okareo-mcp"].

---

Configuration Reference

---

Available Tools

Scenarios

Generation Models

Tests & Checks

Simulations (Multi-Turn)

Voice Monitoring

Analytics & Dashboards

Tenant Management (remote MCP only)

Documentation & Templates

---

Troubleshooting