{
  "markdown": "# Okareo MCP Server\n\nThe 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.\n\nFor detailed documentation, see the [Okareo MCP docs](https://docs.okareo.com/docs/mcp/introduction).\n\n## Prerequisites\n\n- An Okareo account at [app.okareo.com](https://app.okareo.com)\n- A copilot that supports MCP servers (Claude Code, Cursor, or VS Code)\n- Python 3.10–3.12 (only for the local install modes; not needed for remote)\n\n---\n\n## Remote MCP (hosted) — recommended\n\nThe fastest way to get started. No local install, no Python, no API key in `.mcp.json`. Browser sign-in handles auth on first connect.\n\n### Recommended (OAuth — Claude Code, Claude Desktop, Cursor, VS Code 1.101+)\n\nAdd to your copilot's MCP config (typically `.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"okareo\": {\n      \"type\": \"http\",\n      \"url\": \"https://tools.okareo.com/mcp\"\n    }\n  }\n}\n```\n\nReload 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.\n\n### Fallback (Bearer header — older clients or headless / CI)\n\nFor 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:\n\n```json\n{\n  \"mcpServers\": {\n    \"okareo\": {\n      \"type\": \"http\",\n      \"url\": \"https://tools.okareo.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${env:OKAREO_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\n### Working across multiple Okareo organizations\n\nIf you have access to more than one Okareo account, simply `Clear Authentication` and then re-authenticate with the account you want to work in. You can always ask which account your are in and have acccess to.\n\n---\n\n## Local install (alternative)\n\nRun the MCP server on your own machine. Useful for offline / airgapped environments and for development.\n\n> Prefer the **[Remote MCP](#remote-mcp-hosted--recommended)** 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.\n\nFor multi-org users, the remote endpoint also exposes [tenant management tools](docs/remote-mcp.md#tenants--working-across-multiple-okareo-organizations) (`list_tenants`, `switch_tenant`).\n\n### Step 1: Set Your API Key\n\n```bash\nexport OKAREO_API_KEY=\"your-api-key\"\n```\n\nAdd this to your `~/.zshrc` or `~/.bash_profile` for persistence.\n\n### Step 2: Configure Your Copilot\n\n#### Claude Code\n\nAdd to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"okareo\": {\n      \"command\": \"uvx\",\n      \"args\": [\"okareo-mcp\"],\n      \"env\": {\n        \"OKAREO_API_KEY\": \"${OKAREO_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\nNo pre-install needed — `uvx` handles it automatically.\n\n#### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"okareo\": {\n      \"command\": \"uvx\",\n      \"args\": [\"okareo-mcp\"]\n    }\n  }\n}\n```\n\nCursor inherits `OKAREO_API_KEY` from your shell environment.\n\n#### Alternative: pip install\n\nIf you don't have `uv` installed:\n\n```bash\npip install okareo-mcp\n```\n\nThen use `\"command\": \"okareo-mcp\"` instead of `\"command\": \"uvx\"` with `\"args\": [\"okareo-mcp\"]`.\n\n---\n\n## Configuration Reference\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OKAREO_API_KEY` | *(required)* | Your Okareo API key |\n| `OKAREO_BASE_URL` | `https://api.okareo.com` | Override for on-prem Okareo backend |\n| `TRANSPORT` | `stdio` | Transport: `stdio` (local) or `sse` (Docker) |\n| `PORT` | `8000` | Port for SSE transport |\n\n---\n\n## Available Tools\n\n### Scenarios\n\n| Tool | Description |\n|------|-------------|\n| `save_scenario` | Save a named scenario from rows of input/result data (idempotent) |\n| `list_scenarios` | List all scenarios in the project with names, IDs, and row counts |\n| `get_scenario` | Retrieve a scenario's metadata and all data rows by name or ID |\n| `create_scenario_version` | Create a new version of an existing scenario with updated data |\n| `preview_delete_scenario` | Preview what will be deleted before removing a scenario |\n| `delete_scenario` | Permanently delete a scenario and all related test data |\n\n### Generation Models\n\n| Tool | Description |\n|------|-------------|\n| `list_available_llms` | Browse available LLMs from the Okareo registry |\n| `register_generation_model` | Register a generation model for testing by selecting an LLM from the registry |\n| `list_generation_models` | List all registered generation models in the project |\n| `get_generation_model` | Read detailed information about a registered generation model |\n| `update_generation_model` | Change the LLM a registered generation model points to |\n| `delete_generation_model` | Remove a registered generation model and all its related test data |\n\n### Tests & Checks\n\n| Tool | Description |\n|------|-------------|\n| `list_checks` | List available quality checks (built-in and custom) for evaluating model outputs |\n| `run_test` | Run a quality test that evaluates a model against a scenario using specified checks |\n| `list_test_runs` | List past test runs with optional filters (model, scenario, simulation-only) |\n| `get_test_run_results` | Load detailed per-row results of a test run or simulation by ID or name |\n| `get_conversation_transcript` | Retrieve the full conversation transcript for a single data point |\n| `reevaluate_test_run` | Re-score a completed test run against a (possibly different) set of checks |\n| `create_or_update_check` | Create or update a quality check by name — model-based, code-based, or audio (upsert) |\n| `generate_check` | Generate a check from a natural-language description, then save it |\n| `get_check` | Retrieve a check's full configuration, including its prompt template or code |\n| `delete_check` | Permanently delete a check by name |\n\n### Simulations (Multi-Turn)\n\n| Tool | Description |\n|------|-------------|\n| `create_or_update_target` | Create or update a Target — generation model, custom endpoint, or voice (OpenAI, Deepgram, Twilio) |\n| `get_target` | Retrieve a Target's configuration by name (all types) |\n| `list_targets` | List all simulation targets (voice and custom_endpoint) in the project |\n| `delete_target` | Remove a simulation target and all its related test data |\n| `create_or_update_driver` | Define a simulated user persona that will interact with your target |\n| `get_driver` | Retrieve a Driver's full configuration including the persona prompt |\n| `list_drivers` | List all Driver personas in the project |\n| `list_driver_voices` | Discover the voices, voice profiles, and languages available for voice drivers |\n| `run_simulation` | Run a multi-turn conversation evaluation (or rerun a previous one with overrides) |\n| `list_simulations` | List past simulation runs with optional filters (target, scenario, limit) |\n\n### Voice Monitoring\n\n| Tool | Description |\n|------|-------------|\n| `ingest_conversations` | Submit completed voice conversations to Okareo for monitoring |\n| `connect_voice_integration` | Connect a voice provider so its traffic flows into Okareo monitoring |\n| `list_voice_integrations` | List the voice provider integrations in your project |\n| `get_voice_integration` | Retrieve a voice provider integration by ID, including its status |\n| `update_voice_integration` | Update a voice provider integration's metadata |\n| `rotate_voice_integration_secret` | Rotate a voice provider integration's secrets |\n| `delete_voice_integration` | Delete a voice provider integration by ID |\n| `get_voice_webhook_url` | Get the inbound webhook endpoint for a voice provider |\n\n### Projects\n\n| Tool | Description |\n|------|-------------|\n| `list_projects` | List every project you can work in — id, name, tags, archive state — with the active one marked |\n| `select_project` | Choose the project to work in for this conversation |\n| `create_project` | Create a new project |\n| `update_project` | Rename a project, or replace its tags |\n| `archive_project` | Hide a project from the project picker. Reversible; nothing is deleted |\n| `unarchive_project` | Restore an archived project to the picker |\n| `clone_project` | Copy an existing project's scenarios into a new project (dry-run first) |\n\n> Okareo has no project **delete** — in the app, the API, or here. Archiving is\n> the removal, and it only hides the project from the picker: its scenarios,\n> runs, and dashboards stay intact and every tool still works against it.\n\n### Analytics & Dashboards\n\n| Tool | Description |\n|------|-------------|\n| `query_analytics` | Query Okareo's product analytics to understand evaluation trends |\n| `list_dashboards` | List the analytics dashboards in your project |\n| `get_dashboard` | Retrieve a dashboard's full configuration by name |\n| `save_dashboard` | Create or update an analytics dashboard by name (upsert) |\n| `reorder_dashboards` | Set the display order of dashboards |\n| `delete_dashboard` | Delete a dashboard by name |\n\n### Tenant Management (remote MCP only)\n\n| Tool | Description |\n|------|-------------|\n| `list_tenants` | List every Okareo organization you have access to in this MCP session |\n| `switch_tenant` | Change which Okareo organization subsequent tool calls operate against |\n\n### Documentation & Templates\n\n| Tool | Description |\n|------|-------------|\n| `get_docs` | Query the Okareo documentation system for conceptual or user-legible explanations |\n| `get_templates` | Retrieve prompt templates for common Okareo patterns (works offline) |\n| `get_reps_baseline` | Serve REPS agent-evaluation baseline material (scenario banks, drivers, checks, eval configs) from the latest tagged okareo-tools release |\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `okareo-mcp: command not found` | Not installed or not in PATH | Run `pip install -e .` (dev) or use `uvx okareo-mcp` (user) |\n| Server exits with API key error | `OKAREO_API_KEY` not set | Export it: `export OKAREO_API_KEY=\"...\"` |\n| `pip install` fails on Python 3.13+ | Okareo SDK requires Python <3.13 | Use Python 3.10–3.12 |\n| Copilot can't connect (Docker) | Wrong URL | Ensure URL ends with `/sse` and port matches |\n| Cursor doesn't pick up API key | Cursor launched from Dock, not terminal | Launch Cursor from terminal: `cursor .` |\n\n---\n\n## Contributing\n\nThis repository is a curated public mirror; the canonical source is maintained by Okareo. We welcome issues and consider community pull requests — see [CONTRIBUTING.md](CONTRIBUTING.md) for how proposed changes are reviewed and ported.\n\n## License & Trademarks\n\nThe Okareo MCP server source code is licensed under the [Apache License 2.0](LICENSE) (see also [NOTICE](NOTICE)).\n\n\"Okareo\", the Okareo logo, and Okareo product names are trademarks of Okareo, Inc. and are **not** covered by the Apache 2.0 license. See [TRADEMARK.md](TRADEMARK.md) for permitted use.\n",
  "bytes": 11016,
  "sha": "1fdbc2265bad080daf41d34debb70da13215f28a8625d03e1f1133c158ab292e",
  "repo_slug": "okareo-ai/okareo-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_okareo_okareo_55ce471d/readme"
}