Coval MCP Server

The official Model Context Protocol server for Coval - the AI evaluation platform.

This MCP server allows AI assistants like Claude, ChatGPT, Codex, and Cursor to interact with Coval's evaluation APIs, enabling you to:

• Launch and monitor evaluation runs

• Manage AI agents and test sets

• Retrieve evaluation metrics and results

Hosted connector

The hosted connector is the recommended way to use Coval from Claude, ChatGPT, and other remote MCP clients. It uses OAuth, so users sign in to Coval and select the organization the connector can access. No Coval API key is copied into the client.

Standard MCP endpoint: https://mcp.coval.dev/mcp

Claude hosted endpoint: https://mcp.coval.dev/claude/mcp

Claude

1. Open Customize > Connectors. Team and Enterprise owners add the connector first from Organization settings > Connectors.

2. Add a custom web connector using https://mcp.coval.dev/claude/mcp.

3. Select Connect, sign in to Coval, and choose the Coval organization to authorize.

4. Enable the connector in a conversation and ask Claude to use Coval or Sofia.

See Claude's remote MCP connector guide for current plan and administration requirements.

ChatGPT

1. Enable developer mode for your ChatGPT workspace account.

2. From Settings > Apps, create an app using https://mcp.coval.dev/mcp and OAuth.

3. Select Scan Tools, sign in to Coval, and choose the Coval organization to authorize.

4. Create the app, then enable it in a conversation.

See ChatGPT's MCP app guide for current plan and workspace requirements.

Codex

Use Codex 0.144.2 or newer. Current Codex Desktop releases include a compatible client. For the CLI, update before connecting:

npm install -g @openai/codex@latest
codex mcp add coval --url https://mcp.coval.dev/mcp

When the browser opens, sign in to Coval, select the organization Codex should access, and select Allow. Codex Desktop, the Codex CLI, and the IDE extension share MCP configuration on the same machine, so the connection is available across those clients after they restart.

In Codex Desktop, you can also add Coval from Settings > MCP servers as a Streamable HTTP server using https://mcp.coval.dev/mcp, then select Authenticate.

If OAuth returns invalid_scope, first confirm codex --version is 0.144.2 or newer. Older clients registered a dynamic OAuth client without all the scopes they requested during consent. After updating, clear the stale registration and reconnect:

codex mcp logout coval
codex mcp remove coval
codex mcp add coval --url https://mcp.coval.dev/mcp

No API key, manual scope list, or oauth_resource override is required. See Codex's MCP documentation for current client setup details.

Related MCP server: Trustwise MCP Server

Local installation

npx @coval/mcp-server

Use the local stdio server for service accounts, automation, and clients that do not support remote OAuth.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "coval": {
      "command": "npx",
      "args": ["-y", "@coval/mcp-server"],
      "env": {
        "COVAL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "coval": {
      "command": "npx",
      "args": ["-y", "@coval/mcp-server"],
      "env": {
        "COVAL_API_KEY": "your_api_key_here"
      }
    }
  }
}

Get your API key from app.coval.dev/settings

Available Tools

Example Usage

Once connected, you can ask Claude things like:

"Show me my recent evaluation runs"

"List all my agents"

"Run an evaluation of my customer-support-agent against the billing-inquiries test set"

"What are the metrics for run abc123?"

"Use consult_sofia to analyze my latest failed run and recommend the most useful next test."

The same tools, including consult_sofia, are available through every supported endpoint and transport:

• Standard remote Streamable HTTP: https://mcp.coval.dev/mcp using OAuth. This is the recommended connection for ChatGPT, Codex, and other hosted MCP clients.

• Claude remote Streamable HTTP: https://mcp.coval.dev/claude/mcp using the same OAuth flow and tool surface, with Claude-specific risk annotations.

• Local stdio: npx @coval/mcp-server with COVAL_API_KEY, for service accounts and local development.

The hosted connector can access only the Coval organization selected during OAuth consent. Remove the connector from the client or revoke its Coval access when it is no longer needed.

Development

# Install dependencies
npm install

# Build
npm run build

# Test locally with MCP Inspector
npm run inspector

# Run tests
npm test

# Check the public health and OAuth discovery endpoints
npm run check:remote

Environment Variables

Documentation

• Coval Documentation

• MCP Protocol

• API Reference

• Privacy Policy

• Connector directory submission checklist

License

MIT

Support

• GitHub Issues

• Coval Support