---
title: "Judgment MCP server"
description: "Give coding agents authenticated access to Judgment project data and tools."
sidebar:
  label: "Judgment MCP server"
seo:
  title: "Judgment MCP Server"
  description: "Connect a coding agent to Judgment with OAuth or an API key, then verify organization and project access."
---

The **Judgment MCP server** gives coding agents authenticated, project-scoped
tools for investigating traces, inspecting evaluations, and performing
approved actions.

## Connect the Judgment MCP server

### Prerequisites

- A Judgment account with access to at least one organization and project.
- Cursor, Claude Code, Windsurf, or Codex with remote HTTP MCP support.
- For the API-key fallback, a key from **Settings → Account & API Key**

1. ### Add the data MCP

    Use browser-based OAuth when your client supports it. The client stores the
    resulting access token; do not add an API key to its configuration.
    During authorization, choose the intended organization and leave **Project**
    set to **All Projects in This Organization** for this tutorial. A
    project-specific grant intentionally hides cross-project discovery tools.

    **Cursor**

    Add the server to `~/.cursor/mcp.json` for every workspace, or
    `.cursor/mcp.json` for this project:

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

    Open Cursor's MCP settings, select **judgment**, and complete **Sign in** in
    the browser when prompted.

    **Claude Code**

    Add the remote HTTP server:

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

    Claude Code opens the browser authorization flow when it first connects.

    **Windsurf**

    Add the server to `~/.codeium/windsurf/mcp_config.json`:

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

    Open Windsurf's MCP settings and complete the browser sign-in prompt for
    **judgment**.

    Cascade can expose at most 100 total tools at one time. If a tool from the
    [MCP reference](/documentation/mcp-and-agent-tools/mcp-tools) is not visible,
    open the Judgment MCP settings and toggle tool availability so the tools
    needed for the task are enabled.

    **Codex**

    Add the remote HTTP server, then start its OAuth login:

    ```bash
    codex mcp add judgment --url https://mcp.judgmentlabs.ai
    codex mcp login judgment
    ```

    Complete authorization in the browser. The equivalent configuration is:

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

2. ### Use an API key only when OAuth is unavailable

    Store the key in an environment variable and configure the client to send it as
    `Authorization: Bearer <key>`. For example, Codex can read the token without
    placing it in `config.toml`:

    ```bash
    export JUDGMENT_API_KEY="<your-api-key>"
    codex mcp add judgment \
      --url https://mcp.judgmentlabs.ai \
      --bearer-token-env-var JUDGMENT_API_KEY
    ```

    Cursor and Windsurf also accept an `Authorization` header in their server JSON.
    Claude Code accepts one with `--header`. Keep the value out of tracked project
    files, shell history, logs, and prompts. See
    [Authentication](/documentation/reference/authentication) for the shared
    credential model.

3. ### Verify organization and project access

    Restart or reload the client after changing its MCP configuration, then ask:

    ```txt
    Use the Judgment MCP tools. Call list_organizations, choose the organization
    named <organization-name>, then call list_projects for its organization_id.
    Return the selected organization_id and the project_id for <project-name>.
    Do not make any changes.
    ```

    Success means the answer contains the real `organization_id` returned by
    `list_organizations` and the real `project_id` returned by `list_projects`.
    If either name is missing, confirm that the signed-in user or API key belongs to
    the intended organization and that the project exists there.

Next, [install the Judgment agent
skill](/documentation/mcp-and-agent-tools/judgment-agent-skill) so the coding
agent knows the recommended investigation workflow, or use the [MCP tools
reference](/documentation/mcp-and-agent-tools/mcp-tools) for exact tool names
and input fields.