EVA MCP server
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.
The server is in preview and not yet available on company hosts. Until it is, use the REST API.
Server URL
Section titled “Server URL”https://<your-company>.novilabs.io/eva/api/mcpUse the host you use for Novi apps in the browser. The transport is Streamable HTTP.
Sign-in
Section titled “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.
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_ |
How to read the data, before a custom query | topic: querying, units, percentiles, production, forecasts, benchmarking |
search_ |
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_ |
Units, definitions and the operations each column supports | references (up to 25) |
resolve_ |
Exact stored text values with well counts: Reeves finds Reeves,. Never picks an ambiguous match for you |
column, query, filter, limit (default 10, max 25) |
group_ |
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_, sort, limit (default 100, max 500), min_, benchmark, options |
fetch_ |
Individual well rows, sorted by well identifier | filter, columns (1 to 50), entity_ (up to 500), normalize_, limit (default 100, max 500), cursor, options |
create_ |
A polygon filter of a given radius around the center of a reference set of wells | reference_, radius_ (above 0, up to 100) |
Charts
Section titled “Charts”| Tool | Purpose | Key inputs |
|---|---|---|
get_ |
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_ or preset, product, group_, statistics, chart_, volume_, include_, include_, limit |
get_ |
What each chart type plots, P-levels, averaging, survivor bias, units and settings | none |
| Setting | Values |
|---|---|
chart_ |
MonthlyRateTime, MonthlyRateCum, CumTime, RateDate, TotalRateDate |
product |
oil, gas, water, boe, fluid, gor, cgr, wgr |
preset |
type_ (P10 High, P50 Mid and P90 Low on, survivor bias on, cutoff 50) or stacked_ (TotalRateDate) |
chart_ |
survivorBias, cutoff, shutInMonths, showForecast, forecastMode, normalizeBy, useWeightedRatioAverage, movingAverageDays |
user_ |
Forecast sources you are licensed for |
volume_ |
{from,, inclusive, up to 20 years, on RateDate or TotalRateDate. Each group then carries volume_ in volume_ |
| Tool | Purpose | Key inputs |
|---|---|---|
get_ |
A well map from a full filter, colored by group | filter, group_, palette, reverse_, format (tiles, png, geojson, auto), geometry (points, trajectories), delivery |
get_ |
One map tile, for clients without the map viewer | map_, z, x, y, representation |
get_ |
Group titles, counts and colors, a page at a time | map_, cursor, limit (up to 200) |
get_ |
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
Section titled “Filters”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.operatorisandoror; nest groups inchildren_nodes. Up to 100 predicates, each with a uniqueid.- Text:
inandninwith 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: trueadds 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
Section titled “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
Section titled “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
Section titled “Conventions”| Topic | Convention |
|---|---|
| Units | options.: 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.), not completion year |
| Well identifiers | Header.: 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
Section titled “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.
{ "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": {}}{ "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
Section titled “Limits”| Limit | Value |
|---|---|
| Request body | 1 MiB |
fetch_ rows per page |
500 (default 100) |
group_ groups |
500 (default 100) |
Charts or cohorts per get_ call |
8 |
Series per chart (limit.) |
50 |
volume_ span |
20 years |
| Radius filter | 100 miles |
| Mappable wells in GeoJSON | 100,000 |
| Data tool deadline | 30 seconds |
fetch_ cursor lifetime |
10 minutes |
map_ 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
Section titled “Errors”A tool error is JSON: {"code", "message", "retryable", "field"}.
| Code | Meaning | What to do |
|---|---|---|
LIMIT_ |
Too many calls in flight, or a result too large | Retry later if retryable is true; otherwise narrow the request |
DEADLINE_ |
The call ran past its deadline | Retry, or narrow the filter |
DEPENDENCY_ |
Novi could not read the data just then | Retry later. A failed read is never reported as zero |
INVALID_ |
The cursor expired or the inputs changed | Start again without a cursor |
VALIDATION_ |
An input is invalid; field names it |
Fix the input |
UNSUPPORTED_ |
The column does not support that filter, grouping or measure | Check the operations describe_ lists |
ACCESS_ |
A column, value or part of the cohort is outside your subscription | Do not retry with guessed columns; ask your Novi admin about access |