Okareo MCP Server

The Okareo MCP (Model Context Protocol) server is hosted at https://tools.okareo.com/mcp. Any MCP-ready coding agent — Claude Code, Claude Desktop, Cursor, VS Code (1.101+), Cline, Gemini Code Assist, GitHub Copilot, Windsurf, and more — can connect to it without installing anything. Sign in through your browser on first connect; the agent stores the OAuth token thereafter.

Your coding agent can analyze your project, generate test scenarios from your codebase, run evaluations, simulate multi-turn conversations, ingest voice traffic for monitoring, query analytics, and compare results — all from natural-language prompts.

See the MCP User Guide for a walkthrough of key use cases, or jump straight to Configuration for setup instructions.

Getting Started

See the Configuration page for setup instructions for each coding agent.

If you are familiar with mcp registration, the configuration block is a simple http endpoint.

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

Key Use Cases

Create Scenarios from Your Codebase

Ask your coding agent to analyze your project and produce test scenarios. It can read your code, understand your domain, and generate realistic input/result pairs as Okareo scenarios — no manual data entry required.

Set Up Drivers for Multi-Turn Simulations

Define simulated user personas that interact with your system. Drivers can include voice and language settings for voice-mode simulations. The agent can create drivers with specific behaviors, frustration levels, or domain expertise tailored to your application's user base.

Run Simulations and Evaluations

Execute multi-turn simulations and single-turn evaluations. The agent orchestrates the full flow: creating targets, registering models, selecting checks, and running tests.

Monitor Voice and Chat Conversations

Pipe completed voice calls or chat sessions into Okareo for ongoing monitoring. Use a connected provider integration (Retell, Twilio, Vapi, ElevenLabs) or ingest transcripts directly.

Analyze and Compare Results

Retrieve detailed results from test runs and simulations, query analytics, and curate dashboards. The agent can compare runs side-by-side, identify regressions, and surface patterns across evaluation scores and conversation transcripts.

Available Tools

The MCP server exposes Okareo's core capabilities as tools your coding agent can call:

Category	Tools	Description
Scenarios	save_scenario, list_scenarios, get_scenario, create_scenario_version, preview_delete_scenario, delete_scenario, move_scenario (dry-run first)	Create, version, and manage test datasets, and move a scenario — with its simulations and results — to another project
Models	list_available_llms, register_generation_model, list_generation_models, get_generation_model, update_generation_model, delete_generation_model	Browse the LLM registry and register Models Under Test
Checks	create_or_update_check (with tags), generate_check, calibrate_check (with inspect_only), list_checks (with all_versions), get_check (versioned), delete_check	Define evaluation criteria — prompt-based, code-based, AI-generated, or versioned — and dry-run a draft check against a finished run before saving it
Tests	run_test, list_test_runs, get_test_run_results, get_conversation_transcript, reevaluate_test_run	Run evaluations, inspect results, fetch individual transcripts, and re-score finished runs against new checks
Simulations	create_or_update_target, get_target, list_targets, delete_target, create_or_update_driver, get_driver, list_drivers, list_driver_voices, run_simulation, list_simulations	Define targets and driver personas (including voice-configured drivers), execute multi-turn conversations, and manage simulation lifecycle
Voice Monitoring	ingest_conversations, connect_voice_integration, list_voice_integrations, get_voice_integration, update_voice_integration, rotate_voice_integration_secret, delete_voice_integration, get_voice_webhook_url	Submit completed conversations for monitoring and wire up provider integrations (Retell, Twilio, Vapi, ElevenLabs)
Analytics & Dashboards	query_analytics, list_dashboards, get_dashboard, save_dashboard, reorder_dashboards, delete_dashboard	Query the underlying analytics cubes and curate dashboard views
Projects & Organizations	list_projects, select_project, create_project, update_project, archive_project, unarchive_project, clone_project (dry-run first), list_tenants, switch_tenant (OAuth only)	Choose, create, rename, archive, and clone projects — archiving hides, never deletes — and see which organization the session is signed in to; switching organizations happens at sign-in
Docs & Templates	get_docs, get_templates, get_reps_baseline	Query Okareo documentation, retrieve prompt templates for checks, and fetch REPS agent-evaluation baseline material (scenario banks, drivers, checks, eval configs)

Authentication

The hosted endpoint supports two authentication paths:

• OAuth (recommended). Browser sign-in on first connect.
• Bearer fallback. Authorization: Bearer <OKAREO_API_KEY> header. Pinned to a single Okareo organization.

See Configuration → Authentication for details and per-agent snippets.

Rate Limits

The hosted endpoint is throttled per credential at 60 requests/minute/organization by default. Tool calls that exceed the limit return a 429 response with a retry_after field. If your traffic profile warrants a higher limit, contact Okareo support.

Troubleshooting

Symptom	Cause	Fix
The agent prompts for "OAuth client_id"	The agent does not yet implement MCP OAuth discovery	Use the Bearer-header fallback shown on the Configuration page.
OAuth browser shows "redirect URI not allowed"	Stale browser session against an older config	Clear browser cookies for tools.okareo.com and retry.
Tool calls return 429	Per-credential throttle tripped	Wait for the retry_after window. If persistent, contact support — your traffic profile may warrant a higher limit.
register_generation_model reports the LLM is not available	Provider key for that LLM is not configured in your org	Use list_available_llms to confirm which LLMs are wired up in your Okareo organization.