Netra MCP - What is Netra? | Technical documentation

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

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

Server Details

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

NETRA_MCP_ENDPOINT="https://api.getnetra.ai/mcp"
NETRA_API_KEY="<your-api-key-here>"

NETRA_MCP_ENDPOINT="https://api.eu.getnetra.ai/mcp"
NETRA_API_KEY="<your-api-key-here>"

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

Client Setup

Cursor
Claude Code
Windsurf
Antigravity
Codex

Add this netra entry to your MCP server configuration in mcp.json:

If you’re in the EU region, then use the url https://api.eu.getnetra.ai/mcp.

"netra": {
  "url": "https://api.getnetra.ai/mcp",
  "headers": {
    "x-api-key": "<your-netra-api-key>"
  }
}

Add the Netra MCP server directly from the command line:

If you’re in the EU region, then use the url https://api.eu.getnetra.ai/mcp.

claude mcp add netra --transport http https://api.getnetra.ai/mcp --header "x-api-key: <your-netra-api-key>"

Alternatively, add it via JSON:

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:

claude mcp list

Add this netra entry to your MCP server configuration in mcp_config.json:

If you’re in the EU region, then use the url https://api.eu.getnetra.ai/mcp.

"netra": {
  "url": "https://api.getnetra.ai/mcp",
  "headers": {
    "x-api-key": "<your-netra-api-key>"
  }
}

Add this netra server definition to your MCP configuration in mcp.json:

If you’re in the EU region, then use the url https://api.eu.getnetra.ai/mcp.

"netra": {
  "serverUrl": "https://api.getnetra.ai/mcp",
  "headers": {
    "x-api-key": "<your-netra-api-key>"
  }
}

Add this block to ~/.codex/config.toml:

If you’re in the EU region, then use the url https://api.eu.getnetra.ai/mcp.

[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.

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

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.

Example Workflows

Debug a production regression

Find failing traces

Call netra_query_traces with a time range and filters such as has_error, user_id, or session_id.

Inspect the execution tree

Use netra_get_trace_by_id with a trace ID from the results to retrieve the full span tree.

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.

Set up an evaluation from your IDE

Discover evaluators

Call netra_list_evaluator_library to browse built-in evaluators, then netra_create_evaluator to add one to your project.

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.

Map evaluators

Use netra_map_evaluator_to_dataset to attach evaluators at the dataset level, or set item-level overrides when creating items.

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.

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.

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.

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.

​Server Details

​Client Setup

​Why Netra MCP

​Available Tools

​Observability

​Datasets

​Evaluators

​Test Runs

​Example Workflows

​Debug a production regression

​Set up an evaluation from your IDE

​Troubleshooting

​Next Step

Server Details

Client Setup

Why Netra MCP

Available Tools

Observability

Datasets

Evaluators

Test Runs

Example Workflows

Debug a production regression

Set up an evaluation from your IDE

Troubleshooting

Next Step