# MCP server and Claude skill

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

> Ask questions of Novi Forecasts from Claude, through the MCP server's 25 tools or the Claude skill.

Ask Claude about your forecasts in plain words and get the numbers and a chart, with where they came from. Use the MCP
server's 25 tools, or the Claude skill, which teaches Claude when to use each tool and how to chart the result.

| Surface | Status |
| --- | --- |
| Claude skill, for Claude Code | [Available] |
| Hosted MCP server at `/forecasts/api/mcp` | [Preview] |
| Claude Desktop extension | [Preview] |

> **Preview:**
> The hosted MCP server is in preview and not yet available on company hosts. The Forecasts app's API page lists the
> skill and extension downloads.

## How it works

- Tools act as you. They read, or start a plan or an export; `save_forecast_source` saves a forecast file once you agree. No tool deletes.
- Each answer carries its provenance: dataset, as-of date, models, request id and API version.
- The transport is Streamable HTTP.

## Tools

| Tool | What it answers |
| --- | --- |
| `describe_dataset` | The dataset: basin, formations, as-of date, models and what they can do. Call it first |
| `find_wells` | Existing wells by name, operator, formation, area or unit, filtered by ranges and sorted by any field |
| `well_facets` | Counts of wells by operator, formation, county and other values, with each numeric field's range and histogram |
| `get_well` | One well's header, production, spacing and the model's stored prediction against its actuals |
| `type_curve` | A type curve from existing wells' actual production: counts, mean and quantiles by day |
| `completion_defaults` | Default completion designs (fluid and proppant per ft) by formation |
| `forecast_wells` | Forecasts for drawn wells, for one or more completion designs, with EUR |
| `explain_forecast` | The top drivers behind a forecast, per stream, against a typical well and its analogs' production |
| `model_card` | What each model saw in training and how accurate it is on wells it never saw |
| `fill_layout` | Parallel wells across a polygon at a given spacing and azimuth |
| `read_areas` | Unit or lease boundaries from GeoJSON, a zipped shapefile or KML, each with a polygon to fill |
| `fill_areas` | Wells of one lateral length over a file's areas, areas that share an edge laid as one piece of land |
| `summarize_unit` | What a unit holds: acres, existing wells by formation and operator, grid ranges and completions |
| `read_inventory` | Planned wells from a CSV or GeoJSON lines, ready to forecast, with why any rows were left out |
| `gun_barrel` | A cross-section of drawn and existing wells: spacing across, TVD and each formation's top |
| `start_plan` | Starts a plan that forecasts many wells; returns its id |
| `get_plan` | A plan's status, totals per design and per pad and zone, ranked wells, failed wells and nearby PDP wells |
| `list_plans` | Your recent plans, or your team's, newest first |
| `export_plan` | Exports a done plan as files and returns a download link |
| `price_scenarios` | Simulated half-cycle economics for well scenarios on a price deck |
| `compare_forecasts` | Two plans, scenarios or designs, or a saved forecast source against a plan |
| `read_forecast_sources` | Reads a booked forecast file without storing it, or lists and opens saved forecast sources |
| `save_forecast_source` | Saves a read forecast file as a forecast source, after asking you |
| `list_model_sets` | The model sets the server serves |
| `get_conventions` | Units, the BOE ratio, the P-level convention and how to present results |

Two resources come with them: `novi://conventions` (the conventions as Markdown) and `novi://dataset` (the dataset
card `describe_dataset` returns).

## Connect [Preview]

The endpoint is `https://<your-company>.novilabs.io/forecasts/api/mcp`. Signing in with your Novi login needs the Access
MCP permission, which your company's Novi administrator grants.

**claude.ai and Claude Desktop**

1. In Claude, open **Settings**, then **Connectors**, and add a custom connector with the endpoint URL. On a Team or
   Enterprise plan, an owner adds it first.
2. Connect, and sign in with your Novi login.

**Claude Code**

Add the server, then run `/mcp` to sign in with your Novi login.

```sh
claude mcp add --transport http --scope user novi-forecasts https://<your-company>.novilabs.io/forecasts/api/mcp
```

Or send an API token instead:

```sh
claude mcp add --transport http --scope user novi-forecasts https://<your-company>.novilabs.io/forecasts/api/mcp \
  --header "Authorization: Bearer <your-token>"
```

**Claude Desktop extension**

1. Download `novi-forecasts.mcpb` from the Forecasts app's API page and open it in Claude Desktop to install it.
2. Set its **Forecasts API base URL** to `https://<your-company>.novilabs.io/forecasts` and its **Novi API token** to a token
   from Settings, API tokens.

The extension runs the same tools on your computer with your token, and says when a newer version is out.

## The Claude skill [Available]

The skill (`novi-forecasts`) is for Claude Code. It holds when to use each tool, the conventions, the field
dictionary, every export column and chart templates: type curve, cumulative, gun barrel, stick map, ranked table, plan
histogram and design delta.

<Screenshot name="api-page-claude-setup" alt="The Use it in Claude section of the Forecasts API page: how to install the Claude skill, and download buttons for the skill zip and the Claude Desktop extension." width={808} height={530} caption="The skill and the Claude Desktop extension download from the API page in the Forecasts app." />

1. Download `novi-forecasts-skill.zip` from the Forecasts app's API page.
2. Unzip it so `SKILL.md` sits at `~/.claude/skills/novi-forecasts/SKILL.md`.
3. Start a new Claude Code session.

Without the MCP server, the skill answers from an attached export zip (the default export's monthly volumes, EUR, wells
and designs), or calls the REST API with your token: reads and documented `POST` calls, never `DELETE`.

## Your first question

Ask: **What data is behind Novi Forecasts?** Claude names the dataset and its as-of date, and whether forecasts carry
Low and High bands. Then try a type curve, a spacing question or a plan.
