# EVA MCP server

Source: https://developers.novilabs.com/eva/mcp/

> Ask an AI assistant to benchmark, chart and map wells in Novi EVA, with 13 read-only tools.

Ask an assistant such as Claude to rank basins or operators, build type curves, chart production and map a cohort in Novi EVA. Every tool is read-only and sees only the data your account can see in EVA. See [Good prompts](#good-prompts).

The server is in preview and not yet available on company hosts. Until it is, use the [REST API](https://developers.novilabs.com/eva/api/).

## Server URL

```text
https://<your-company>.novilabs.io/eva/api/mcp
```

Use the host you use for Novi apps in the browser. The transport is Streamable HTTP.

## Sign-in

Sign in with your Novi login from Claude (claude.ai and Claude Desktop), Claude Code or OpenAI Codex; API keys and personal tokens don't work. You need **Access EVA**, **Access MCP** and membership in the company whose host you use. Steps: [Connect Claude](https://developers.novilabs.com/eva/connect-claude/).

The sign-in works only for EVA on your company host. When it expires, your assistant asks you to sign in again. If an administrator removes either permission, access stops within about two minutes.

## Tools

### Data

| Tool | Purpose | Key inputs |
|---|---|---|
| `get_data_guide` | How to read the data, before a custom query | `topic`: `querying`, `units`, `percentiles`, `production`, `forecasts`, `benchmarking` |
| `search_columns` | Exact column references by name, path, category or note. Every query word must match | `query` (empty browses), `category`, `operation`, `limit` (default 20, max 50), `cursor` |
| `describe_columns` | Units, definitions and the operations each column supports | `references` (up to 25) |
| `resolve_values` | Exact stored text values with well counts: `Reeves` finds `Reeves, TX`. Never picks an ambiguous match for you | `column`, `query`, `filter`, `limit` (default 10, max 25) |
| `group_by` | Well counts per value of a text or integer column, with optional `sum`, `avg`, `min`, `max` or `median` measures. Omit `column` for cohort totals | `filter`, `column`, `measures` (up to 4), `normalize_by`, `sort`, `limit` (default 100, max 500), `min_wells_counted`, `benchmark`, `options` |
| `fetch_data` | Individual well rows, sorted by well identifier | `filter`, `columns` (1 to 50), `entity_keys` (up to 500), `normalize_by`, `limit` (default 100, max 500), `cursor`, `options` |
| `create_radius_filter` | A polygon filter of a given radius around the center of a reference set of wells | `reference_filter`, `radius_miles` (above 0, up to 100) |

### Charts

| Tool | Purpose | Key inputs |
|---|---|---|
| `get_chart` | Production charts: one chart, up to 8 charts over one filter (`charts[]`), or up to 8 named cohorts with one chart spec (`cohorts[]`) | `filter`, `chart_type` or `preset`, `product`, `group_by`, `statistics`, `chart_setting`, `volume_years`, `include_png`, `include_series`, `limit` |
| `get_chart_guide` | What each chart type plots, P-levels, averaging, survivor bias, units and settings | none |

| Setting | Values |
|---|---|
| `chart_type` | `MonthlyRateTime`, `MonthlyRateCum`, `CumTime`, `RateDate`, `TotalRateDate` |
| `product` | `oil`, `gas`, `water`, `boe`, `fluid`, `gor`, `cgr`, `wgr` |
| `preset` | `type_curve` (P10 High, P50 Mid and P90 Low on, survivor bias on, cutoff 50) or `stacked_area` (`TotalRateDate`) |
| `chart_setting` | `survivorBias`, `cutoff`, `shutInMonths`, `showForecast`, `forecastMode`, `normalizeBy`, `useWeightedRatioAverage`, `movingAverageDays` |
| `user_forecast_settings` | Forecast sources you are licensed for |
| `volume_years` | `{from, to}`, inclusive, up to 20 years, on `RateDate` or `TotalRateDate`. Each group then carries `volume_by_year` in `volume_unit` |

### Maps

| Tool | Purpose | Key inputs |
|---|---|---|
| `get_map` | A well map from a full filter, colored by group | `filter`, `group_by`, `palette`, `reverse_color`, `format` (`tiles`, `png`, `geojson`, `auto`), `geometry` (`points`, `trajectories`), `delivery` |
| `get_map_tile` | One map tile, for clients without the map viewer | `map_id`, `z`, `x`, `y`, `representation` |
| `get_map_legend` | Group titles, counts and colors, a page at a time | `map_id`, `cursor`, `limit` (up to 200) |
| `get_map_guide` | Map filtering, radius, palette, geometry and expiry rules | none |

In clients that support MCP Apps, such as Claude, `get_chart` and `get_map` draw inline. Other clients get a PNG (`include_png`, default true, for charts; `format: png` for maps) and the data.

## Filters

Every data, chart and map tool takes the complete filter inline; saved EVA filters are not used.

```json
{
  "filter": {
    "query": {
      "operator": "and",
      "predicates": [
        { "id": "basin", "type": "Property", "property": "Header.Basin", "operator": "in", "value": ["Permian"] },
        { "id": "vintage", "type": "Property", "property": "Dates.Vintage_Year", "operator": "between", "value": [2022, 2025] }
      ],
      "children_nodes": []
    }
  },
  "columns": ["Header.ResourcePlay", "Header.Operator_Short", "Well_Design.HzLength_m"],
  "options": { "units": "hybrid", "app_default_filters": true },
  "limit": 100
}
```

- `query.operator` is `and` or `or`; nest groups in `children_nodes`. Up to 100 predicates, each with a unique `id`.
- Text: `in` and `nin` with 1 to 100 strings. Numbers and dates (`YYYY-MM-DD`): `between` (lower bound included, upper excluded), `lt`, `gte`.
- `Polygon`: one closed WGS84 ring of 4 to 1,024 points, 2,048 across the query.
- `options.app_default_filters: true` adds producing (`HasProduction=Y`) horizontal wells (`HORIZONTAL`, `U_TURN_HORIZONTAL`) and says so. Maps never add these.

Common references you can use without a search: `Header.FieldCounty` (values like `Lea, NM`), `Header.StateProvince`, `Header.Country` (`US`), `Header.Basin` (`Permian`), `Header.ResourcePlay` (`Delaware`, `Midland`), `Header.Operator_Short`, `Header.Direction`, `Dates.Vintage_Year`, `Well_Design.HzLength_m`, `Production_Summary.Cumulative12MonthsOil`.

## Pagination

`fetch_data` returns `next_cursor` when more rows match. Send the same inputs again with `cursor` set to that value.

- A cursor works only with the inputs it came from, for 10 minutes. Otherwise you get `INVALID_CURSOR`: start again without a cursor.
- Pages are not a snapshot. Data can change between pages.

`search_columns` and `get_map_legend` also take a `cursor` from their previous page.

## Results

Data tools return `schema_version`, `data`, `returned_count`, `matched_count`, `applied_options`, `warnings`, `truncated`, `next_cursor`, `coverage` and `freshness`. Check `truncated` and `warnings` before you rely on a result.

## Conventions

| Topic | Convention |
|---|---|
| Units | `options.units`: `hybrid` (default), `si` or `imperial`. Hybrid: lateral length in metres, oil and BOE in Mbbl, gas in MMcf. Results label their units |
| Cohort years | A bare year means production vintage (`Dates.Vintage_Year`), not completion year |
| Well identifiers | `Header.EntityName`: the API10 for US wells, the UWI or local identifier elsewhere |
| Production windows | `Cumulative12Months*` and `Cumulative24Months*` use the first 12 or 24 producing months; shorter histories return null |
| Oil | Stored cumulative oil is reported oil only. Chart oil includes condensate |
| P-levels in charts | `p10` is High, `p50` Mid (the median), `p90` Low: the exceedance convention, the reverse of Novi Forecasts |

## Good prompts

Ask for one result, name the cohort, and say which basis you want.

- "Rank US basins by median first-12-month oil per 1,000 ft for wells online 2022 through 2024."
- "Show oil production for horizontal Permian wells online 2020 through 2026, by operator and by first-production year."
- "How much gas did Delaware wells produce in 2025, by operator? Give exact yearly volumes, not estimates."
- "Build a type curve with High (P10), Mid (P50) and Low (P90) for horizontal Midland wells online in 2023."
- "Map horizontal wells in Reeves County, TX, colored by first-production year."
- "Count wells within 10 miles of the center of horizontal wells in Loving County, TX, by operator."

The first prompt uses `group_by` with `benchmark`: public production, hybrid units, the first 12 producing months of reported oil, horizontal producing wells with laterals of at least 1,000 m, per 1,000 ft, sorted by median.

  **Benchmark call**
```json
{
  "filter": {
    "query": {
      "operator": "and",
      "predicates": [
        { "id": "country", "type": "Property", "property": "Header.Country", "operator": "in", "value": ["US"] },
        { "id": "vintage", "type": "Property", "property": "Dates.Vintage_Year", "operator": "between", "value": [2022, 2025] }
      ],
      "children_nodes": []
    }
  },
  "column": "Header.Basin",
  "benchmark": {}
}
```
  
  **Two charts, one filter**
```json
{
  "filter": {
    "query": {
      "operator": "and",
      "predicates": [
        { "id": "basin", "type": "Property", "property": "Header.Basin", "operator": "in", "value": ["Permian"] },
        { "id": "vintage", "type": "Property", "property": "Dates.Vintage_Year", "operator": "between", "value": [2020, 2027] },
        { "id": "direction", "type": "Property", "property": "Header.Direction", "operator": "in", "value": ["HORIZONTAL", "U_TURN_HORIZONTAL"] }
      ],
      "children_nodes": []
    }
  },
  "charts": [
    { "chart_type": "TotalRateDate", "product": "oil", "group_by": { "column": "Header.Operator_Short", "bin": { "MaxBins": 20, "MaxBinsSortOrder": "WellCount" } }, "include_png": false, "include_series": false, "limit": { "max_series": 50 } },
    { "chart_type": "TotalRateDate", "product": "oil", "group_by": { "column": "Dates.Vintage_Year" }, "include_png": false, "include_series": false, "limit": { "max_series": 50 } }
  ]
}
```
  

## Limits

| Limit | Value |
|---|---|
| Request body | 1 MiB |
| `fetch_data` rows per page | 500 (default 100) |
| `group_by` groups | 500 (default 100) |
| Charts or cohorts per `get_chart` call | 8 |
| Series per chart (`limit.max_series`) | 50 |
| `volume_years` span | 20 years |
| Radius filter | 100 miles |
| Mappable wells in GeoJSON | 100,000 |
| Data tool deadline | 30 seconds |
| `fetch_data` cursor lifetime | 10 minutes |
| `map_id` lifetime | 5 minutes, or your token's expiry if sooner |

A few of your data tool calls run at once; more wait briefly. Too many calls, or too large a result, returns `LIMIT_EXCEEDED`.

## Errors

A tool error is JSON: `{"code", "message", "retryable", "field"}`.

| Code | Meaning | What to do |
|---|---|---|
| `LIMIT_EXCEEDED` | Too many calls in flight, or a result too large | Retry later if `retryable` is true; otherwise narrow the request |
| `DEADLINE_EXCEEDED` | The call ran past its deadline | Retry, or narrow the filter |
| `DEPENDENCY_ERROR` | Novi could not read the data just then | Retry later. A failed read is never reported as zero |
| `INVALID_CURSOR` | The cursor expired or the inputs changed | Start again without a cursor |
| `VALIDATION_ERROR` | An input is invalid; `field` names it | Fix the input |
| `UNSUPPORTED_OPERATION` | The column does not support that filter, grouping or measure | Check the operations `describe_columns` lists |
| `ACCESS_DENIED` | A column, value or part of the cohort is outside your subscription | Do not retry with guessed columns; ask your Novi admin about access |

> **Note:**
> Not on the MCP server today: shapefile filters, your organization's columns, saved filters, raw monthly series and bulk exports. Use the [REST API](https://developers.novilabs.com/eva/api/) for organization columns and production arrays.
