> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnetra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Netra MCP

> Connect Netra's remote MCP server to Cursor, Windsurf, Antigravity, or Claude Code to query traces, manage datasets and evaluators, and run evaluations directly from your IDE.

Netra exposes a remote MCP server so you can pull observability context and run evaluation workflows directly in your editor or agent workspace.

<video autoPlay={true} muted={true} loop={true} playsInline={true} className="w-full aspect-video rounded-xl" src="https://mintcdn.com/netra/66fG4i83m457hVIl/videos/netra-mcp.mp4?fit=max&auto=format&n=66fG4i83m457hVIl&q=85&s=c86df9ec84b891c8c947c92e020757df" data-path="videos/netra-mcp.mp4" />

<Note>
  Choose the MCP endpoint that matches your Netra data region, then replace the
  API key placeholder with your own project API key.
</Note>

## Server Details

* Region-specific MCP endpoints:
* Auth header: `x-api-key`

<CodeGroup>
  ```bash US Region theme={null}
  NETRA_MCP_ENDPOINT="https://api.getnetra.ai/mcp"
  NETRA_API_KEY="<your-api-key-here>"
  ```

  ```bash EU Region theme={null}
  NETRA_MCP_ENDPOINT="https://api.eu.getnetra.ai/mcp"
  NETRA_API_KEY="<your-api-key-here>"
  ```
</CodeGroup>

Use the endpoint that matches the region where your Netra project is hosted.

## Client Setup

<Tabs>
  <Tab title="Cursor">
    Add this `netra` entry to your MCP server configuration in `mcp.json`:

    <Note>
      If you're in the EU region, then use the url `https://api.eu.getnetra.ai/mcp`.
    </Note>

    ```json theme={null}
    "netra": {
      "url": "https://api.getnetra.ai/mcp",
      "headers": {
        "x-api-key": "<your-netra-api-key>"
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    Add the Netra MCP server directly from the command line:

    <Note>
      If you're in the EU region, then use the url `https://api.eu.getnetra.ai/mcp`.
    </Note>

    ```bash theme={null}
    claude mcp add netra --transport http https://api.getnetra.ai/mcp --header "x-api-key: <your-netra-api-key>"
    ```

    Alternatively, add it via JSON:

    ```bash theme={null}
    claude mcp add-json netra '{"type": "http", "url": "https://api.getnetra.ai/mcp", "headers": {"x-api-key": "<your-netra-api-key>"}}'
    ```

    To verify the server was added correctly:

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>

  <Tab title="Windsurf">
    Add this `netra` entry to your MCP server configuration in `mcp_config.json`:

    <Note>
      If you're in the EU region, then use the url `https://api.eu.getnetra.ai/mcp`.
    </Note>

    ```json theme={null}
    "netra": {
      "url": "https://api.getnetra.ai/mcp",
      "headers": {
        "x-api-key": "<your-netra-api-key>"
      }
    }
    ```
  </Tab>

  <Tab title="Antigravity">
    Add this `netra` server definition to your MCP configuration in `mcp.json`:

    <Note>
      If you're in the EU region, then use the url `https://api.eu.getnetra.ai/mcp`.
    </Note>

    ```json theme={null}
    "netra": {
      "serverUrl": "https://api.getnetra.ai/mcp",
      "headers": {
        "x-api-key": "<your-netra-api-key>"
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Add this block to `~/.codex/config.toml`:

    <Note>
      If you're in the EU region, then use the url `https://api.eu.getnetra.ai/mcp`.
    </Note>

    ```toml theme={null}
    [mcp_servers.netra]
    enabled = true
    url = "https://api.getnetra.ai/mcp"

    [mcp_servers.netra.http_headers]
    x-api-key = "<your-netra-api-key>"
    ```

    Codex also supports managing MCP servers from the CLI, but custom HTTP headers like `x-api-key` should be set in the config file.
  </Tab>
</Tabs>

## Why Netra MCP

Integrate Netra's observability and evaluation workflows directly into your development environment. The Netra MCP server enables your AI coding assistant to query traces, inspect sessions, create datasets and evaluators, and launch test runs without leaving the IDE. By bridging the gap between telemetry, quality validation, and your code, it helps you debug regressions and validate agent behavior as you build.

## Available Tools

The Netra MCP server exposes **21 tools** scoped to the project associated with your API key. Tools are grouped by capability below.

### Observability

| Tool                        | Description                                                                               |
| --------------------------- | ----------------------------------------------------------------------------------------- |
| `netra_get_trace_by_id`     | Retrieve all spans for a given trace ID                                                   |
| `netra_query_traces`        | Query traces with filters, sorting, and cursor-based pagination                           |
| `netra_get_session_details` | Retrieve session-level totals and all traces in a session (by `session_id` or `trace_id`) |

### Datasets

| Tool                              | Description                                                     |
| --------------------------------- | --------------------------------------------------------------- |
| `netra_create_dataset`            | Create a new evaluation dataset (single-turn or multi-turn)     |
| `netra_list_datasets`             | List evaluation datasets in the current project                 |
| `netra_create_dataset_item`       | Add a test case item to a dataset                               |
| `netra_create_dataset_items_bulk` | Add multiple test case items in one operation                   |
| `netra_get_dataset_items`         | Retrieve dataset items and their evaluator mappings             |
| `netra_update_dataset_item`       | Update a dataset item's input, metadata, or evaluator overrides |
| `netra_map_evaluator_to_dataset`  | Map an evaluator to a dataset at the dataset level              |

### Evaluators

| Tool                                  | Description                                                          |
| ------------------------------------- | -------------------------------------------------------------------- |
| `netra_get_default_llm_configuration` | Get the organization's default LLM provider and model for evaluators |
| `netra_list_evaluators`               | List evaluators configured in the current project                    |
| `netra_list_evaluator_library`        | List built-in evaluators from Netra's evaluator library              |
| `netra_get_evaluator`                 | Get detailed configuration for a specific evaluator                  |
| `netra_create_evaluator`              | Create an evaluator from the library or with a custom configuration  |

### Test Runs

| Tool                               | Description                                              |
| ---------------------------------- | -------------------------------------------------------- |
| `netra_create_test_run`            | Create a single-turn test run against a dataset          |
| `netra_create_multi_turn_test_run` | Create a multi-turn conversational test run (simulation) |
| `netra_list_test_runs`             | List test runs for the current project                   |
| `netra_get_test_run_summary`       | Get high-level pass rates and scores per evaluator       |
| `netra_get_test_run_details`       | Get per-item evaluation results for a test run           |

<Tip>
  MCP tools handle evaluation **setup** (datasets, evaluators, test run creation) and **result inspection**. Your agent must still be executed — typically via `Netra.evaluation.run_test_suite()` for single-turn evaluations or `Netra.simulation.run_simulation()` for multi-turn simulations — before evaluators score outputs and results appear in `netra_get_test_run_summary` / `netra_get_test_run_details`.
</Tip>

## Example Workflows

### Debug a production regression

<Steps>
  <Step title="Find failing traces">
    Call `netra_query_traces` with a time range and filters such as `has_error`, `user_id`, or `session_id`.
  </Step>

  <Step title="Inspect the execution tree">
    Use `netra_get_trace_by_id` with a trace ID from the results to retrieve the full span tree.
  </Step>

  <Step title="Review the full session">
    Call `netra_get_session_details` with the `session_id` or `trace_id` to see cost, token, and error totals across the conversation.
  </Step>
</Steps>

### Set up an evaluation from your IDE

<Steps>
  <Step title="Discover evaluators">
    Call `netra_list_evaluator_library` to browse built-in evaluators, then `netra_create_evaluator` to add one to your project.
  </Step>

  <Step title="Create a dataset">
    Call `netra_create_dataset` with the appropriate `turnType` (`single` or `multi`), then add items with `netra_create_dataset_item` or `netra_create_dataset_items_bulk`.
  </Step>

  <Step title="Map evaluators">
    Use `netra_map_evaluator_to_dataset` to attach evaluators at the dataset level, or set item-level overrides when creating items.
  </Step>

  <Step title="Create a test run">
    Call `netra_create_test_run` (single-turn) or `netra_create_multi_turn_test_run` (multi-turn) to allocate a test run against your dataset. This registers the run but does **not** execute your agent or trigger evaluators on its own.
  </Step>

  <Step title="Execute your agent">
    Run the agent under evaluation so Netra can capture outputs and traces for each dataset item:

    * **Single-turn**: Process each item's input through your agent. Use `Netra.evaluation.run_test_suite()` to run the full loop automatically, or execute your agent locally with Netra tracing enabled and submit results against the test run.
    * **Multi-turn**: Use the `userMessages` array returned by `netra_create_multi_turn_test_run` — each entry includes a `testRunItemId`, `turnId`, and opening `userMessage`. Respond as your agent for each scenario and continue the conversation until every item completes. Use `Netra.simulation.run_simulation()` to automate the turn loop.
  </Step>

  <Step title="Review results">
    After your agent has finished processing all items, call `netra_get_test_run_summary` and `netra_get_test_run_details` to retrieve evaluator scores. Evaluators run only once agent execution completes and traces are linked to each test run item.
  </Step>
</Steps>

## Troubleshooting

* Ensure your JSON/TOML configs are properly formatted
* Confirm the MCP server is reachable at your region-specific MCP endpoint
* Verify your API key is correct and has not expired
* Restart the client after making config changes

## Next Step

After saving your config, restart the client and confirm the `netra` MCP server shows up in the available tools or MCP server list.