Skip to content
Developers
Get an API token

EVA MCP server

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

View MarkdownOpen in Claude(opens in a new tab)

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.

The server is in preview and not yet available on company hosts. Until it is, use the REST API.

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

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.

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

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

{
"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.

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.

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.

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

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.

{
"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": {}
}
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.

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