MCP Configuration

The Okareo MCP server is hosted at https://tools.okareo.com/mcp. You connect your coding agent to it directly — no install, no Python, no container. Sign-in happens through your browser on first connect; the agent stores the OAuth token from then on.

Prerequisites

• An Okareo account at app.okareo.com.
• An MCP-ready coding agent. The hosted endpoint has been tested with Claude Code, Cursor, Claude Desktop, and VS Code (1.101 or later), and works with most agents that implement the MCP streamable-HTTP transport.

Setup

Each section below shows the recommended OAuth configuration first and the Bearer-token fallback second. Use the fallback only if your coding agent does not yet implement MCP OAuth discovery.

Claude Code

Recommended — add it from the CLI:

claude mcp add --transport http okareo https://tools.okareo.com/mcp

Run this from your project root. The --scope flag controls who gets it:

Scope	Flag	Where it lands
This project, just you (default)	(none)	your local Claude Code config
This project, checked in for the team	--scope project	.mcp.json in the project root
Every project you open	--scope user	your user-level Claude Code config

On first use a browser tab opens to Okareo sign-in; after consent the tools appear in the tool list. Check the connection any time with claude mcp list, and remove it with claude mcp remove okareo.

Equivalent .mcp.json, if you would rather write the file yourself or commit it with the repo:

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

Fallback (Bearer):

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

Set OKAREO_API_KEY in your shell environment. Prefer the env-var form over an inline literal.

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Recommended (OAuth):

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

Restart Claude Desktop. Sign-in is browser-based.

Cursor

Cursor reads MCP servers from a JSON file. Use .cursor/mcp.json in the project to scope Okareo to one repo, or ~/.cursor/mcp.json to have it everywhere. Create the file if it does not exist — Cursor does not create it for you.

Recommended (OAuth):

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

Restart Cursor, then reload the workspace. Okareo should appear in Cursor's MCP settings with its tools listed; if the list is empty, the file is in the wrong place or the JSON did not parse.

Fallback (Bearer):

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

VS Code (1.101 or later)

File: ~/.config/Code/User/mcp.json (Linux/macOS) or per-workspace .vscode/mcp.json.

Recommended (OAuth):

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

Reload the window. The first tool invocation kicks off the OAuth flow.

Fallback (Bearer):

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

Authentication

The hosted endpoint supports two auth paths:

• OAuth (recommended). Browser sign-in to Okareo on first connect.
• Bearer fallback. Set the Authorization: Bearer <OKAREO_API_KEY> header.

Get an Okareo API token from app.okareo.com under Profile → API Keys, or see the API Token reference.

Provider Keys for Models Under Test

Provider API keys (OpenAI, Anthropic, Cohere, etc.) are managed inside Okareo. Use list_available_llms from your coding agent to see which LLMs your organization has configured, and register_generation_model to wire one up as a Model Under Test. There is no need to set provider keys as local environment variables.

Verifying the Connection

After setup, ask your coding agent to list your Okareo scenarios to confirm the MCP server is working:

"List my Okareo scenarios."

If the server is configured correctly, you'll see your existing scenarios. If not, check the Troubleshooting section in the MCP reference.