MCP Server

The Judgment MCP server exposes your production data — traces, sessions, behaviors, judges, projects, and automations — directly to AI-powered code editors via the Model Context Protocol. This lets your AI assistant query real production data, analyze agent performance, create and manage behaviors and automations, and use those insights to optimize your code — all without leaving your editor.

Setup

Connect the MCP Server

The Judgment MCP server supports two authentication methods:

• OAuth 2.1 + PKCE (recommended) — Your editor opens a browser window where you sign in and authorize access. After completing the flow, your editor holds an access token automatically — no API keys or headers needed.
• API Key — Pass your Judgment API key as a Bearer token.

{
  "mcpServers": {
    "judgment-mcp": {
      "url": "https://mcp.judgmentlabs.ai"
    }
  }
}

{
  "mcpServers": {
    "judgment-mcp": {
      "url": "https://mcp.judgmentlabs.ai",
      "headers": {
        "Authorization": "Bearer <YOUR_JUDGMENT_API_KEY>"
      }
    }
  }
}

claude mcp add judgment-mcp \
  --transport http \
  https://mcp.judgmentlabs.ai

claude mcp add judgment-mcp \
  --transport http \
  --url https://mcp.judgmentlabs.ai \
  --header "Authorization: Bearer <YOUR_JUDGMENT_API_KEY>"

{
  "mcpServers": {
    "judgment-mcp": {
      "serverUrl": "https://mcp.judgmentlabs.ai"
    }
  }
}

{
  "mcpServers": {
    "judgment-mcp": {
      "serverUrl": "https://mcp.judgmentlabs.ai",
      "headers": {
        "Authorization": "Bearer <YOUR_JUDGMENT_API_KEY>"
      }
    }
  }
}

[mcp_servers.judgment-mcp]
url = "https://mcp.judgmentlabs.ai"

codex mcp add judgment-mcp \
  -- npx -y mcp-remote https://mcp.judgmentlabs.ai

[mcp_servers.judgment-mcp]
url = "https://mcp.judgmentlabs.ai"
bearer_token_env_var = "JUDGMENT_API_KEY"

codex mcp add judgment-mcp \
  -- npx -y mcp-remote https://mcp.judgmentlabs.ai \
  --header "Authorization: Bearer <YOUR_JUDGMENT_API_KEY>"

Add the Best Practices Skill

To help your AI assistant use the MCP server effectively, add the Judgment MCP best practices skill. This teaches your assistant optimal patterns like batching queries, using full-text search first, and deduplicating results.

mkdir -p .cursor/skills/judgment-mcp
curl -fLo .cursor/skills/judgment-mcp/SKILL.md \
  https://docs.judgmentlabs.ai/skills/mcp-server-best-practices.md

mkdir -p .claude/skills/mcp-server-best-practices 
curl -fLo .claude/skills/mcp-server-best-practices/SKILL.md \
  https://docs.judgmentlabs.ai/skills/mcp-server-best-practices.md 

mkdir -p .windsurf/skills/judgment-mcp 
curl -fLo .windsurf/skills/judgment-mcp/SKILL.md \
  https://docs.judgmentlabs.ai/skills/mcp-server-best-practices.md 

mkdir -p .codex/skills/judgment-mcp
curl -fLo .codex/skills/judgment-mcp/SKILL.md \
  https://docs.judgmentlabs.ai/skills/mcp-server-best-practices.md

What You Can Do

Once connected, your AI assistant can query and manage Judgment data through natural language. Here are some examples:

• "Show me the slowest traces from the last 24 hours"
• "Find traces where users asked about billing"
• "What behaviors were detected in session X?"
• "List all automations configured for this project"
• "Show me traces with errors that cost more than $0.10"
• "Create a binary behavior that checks whether responses are on-topic"
• "Re-evaluate all traces in the project with the Relevance judge"
• "Add a 'reviewed' tag to trace XYZ"
• "Create an automation that alerts when error rate exceeds 10%"
• "Write a memory file with key facts the agent should remember across sessions"
• "List all agent memory entries for this project"
• "Run a test on the last 50 traces with my Accuracy judge"
• "Show me the test results for my latest experiment run"
• "Add these traces to the golden-path dataset"
• "Create a new dataset called 'edge-cases' and add these examples to it"

Use Production Data to Optimize Your Code

Beyond querying data, the MCP server enables a powerful workflow: use real production insights to improve your agent code. Your AI assistant can:

1. Find failing patterns — search traces for errors, high latency, or unexpected behaviors, then fix the underlying code
2. Analyze behavior trends — check which behaviors are firing most often and adjust your prompts or logic accordingly
3. Optimize costs — identify expensive traces and refactor the agent flows that produce them
4. Debug sessions — walk through an entire user session's traces to understand where things went wrong

Available Tools

The MCP server provides 72 tools organized into fourteen categories. Every tool except list_organizations takes an organization_id argument that selects the organization the call operates on.

Organizations

Projects

Traces

Sessions

Behaviors

Judges

Prompts

Agents

Agent Threads

Datasets

Tests

Automations

Agent Memory

Documentation