---
name: afeleaks-mcp
description: Use whenever the user asks about AFE Leaks — querying US upstream oil & gas data (wells, costs, production, type curves, EUR, permits, completions, vendors), SEC financial data for public E&P operators (financials, reserves, hedges, exec comp, guidance, credit), or routing to the right AFE Leaks MCP tool. Covers tool families, operator-name aliases (EOG/DVN/OXY/etc.), basin/play filtering on og_data, coverage caveats, and multi-tool workflow recipes.
---

# AFE Leaks MCP — Companion Skill

> Drop this file into any AI client to teach it how to use the AFE Leaks MCP server effectively. Works with Claude.ai Projects, Claude Code, Cursor, Codex, and any LLM that accepts system instructions.

**Last verified:** 2026-05-22 against `https://mcp.afeleaks.com` (36 tools, plus MCP resources & prompts).
**Authoritative tool reference:** https://afeleaks.com/api-documentation#mcp-server

---

## How to install this file

| Host | Where it goes |
|---|---|
| **Claude.ai** | Project → "Project knowledge" → add file |
| **Claude Code** | Save as `~/.claude/skills/afeleaks/SKILL.md` |
| **Cursor** | Save as `.cursor/rules/afeleaks-mcp.md` in your repo |
| **Codex** | Append to `AGENTS.md` at the workspace root |
| **Any LLM** | Paste into the system prompt before your first question |

The MCP server connection itself is separate from this file — see the [API documentation](https://afeleaks.com/api-documentation#mcp-server) for `claude mcp add` / `codex mcp add` setup.

---

## What this MCP exposes

**Data:** US upstream oil & gas — ~770K wells across 11 states (TX, NM, OK, ND, CO, WY, UT, MT, KS, LA, WV), with a cost-data slice of ~100K wells, plus SEC/XBRL filings for ~146 public companies (curated standardized coverage for ~24 active E&P tickers).

**Two databases under the hood:**
- `afeleaks` + `og_dataverse` — upstream operations (wells, costs, production, completions, permits, surveys, etc.)
- `xbrl` — SEC filings, standardized financials, reserves, hedges, exec comp, guidance, credit

You do not pick a database — each tool routes itself. The split matters because well-level questions and corporate-financial questions have entirely different filtering vocabularies.

**Billing:** Every response carries a `_usage` envelope reporting tokens and credits charged. Credits scale with payload size. `get_mcp_credit_balance` is free and never bills.

---

## Tools — 6 families + 1 utility, 36 total

### Well discovery & metadata (7)
- `search_operators` — fuzzy operator-name resolution with cost-data coverage counts. **Call this FIRST whenever the user names an operator with anything other than the exact stored spelling.**
- `search_wells` — find API numbers by prefix, lease, or operator (full universe, not cost-limited)
- `lookup_well` — single-well detail: metadata + costs + production + EUR in one call
- `query_dataverse_wells` — broad discovery across the full ~770K well universe
- `query_dataverse_permits` — permit lifecycle, depths, horizontal/directional flags
- `query_well_locations` — lat/lng + WKT geometry for mapping
- `get_basin_info` — basin / play value discovery on `og_data`. Call with no args to list the distinct `og_data.basin` and `og_data.play` values present in the DB (with well counts); pass `basin_name` to drill into the states / counties / plays under that basin.

### Costs (4)
- `query_well_costs` — aggregated AFE vs Actual (both avg + median in one call), with `group_by`
- `query_cost_details` — line-item breakdowns (drilling, completion, casing, stimulation, cement, …)
- `query_vendor_costs` — vendor-level cost detail. Pass `disposal_only=true` + `group_by='ownership_class'` for third-party vs operator-affiliated disposal analysis.
- `compare_costs` — side-by-side comparisons across operators, basins, years, reservoirs

### Production & performance (4)
- `query_production` — oil/gas/water by well (cumulative, monthly avg, or peak)
- `query_well_eur` — estimated ultimate recovery + decline-curve parameters
- `build_type_curve` — synthesize a normalized type curve from a well selection
- `query_well_tests` — IP / well-test results (initial rates, choke, pressure)

### Completion & engineering (5)
- `query_completion_metrics` — fluid, proppant, stages from FracFocus + frac summaries
- `query_completion_raw` — raw completion filings (perf interval, TVD/MD, frac company, choke, text)
- `query_formations` — formation tops, reservoir depths
- `query_casing` — casing program detail (string, OD, weight, grade, cement)
- `query_surveys` — directional survey data (inclination, azimuth, MD/TVD)

### Corporate financials — SEC / XBRL (12)
- `query_financials` — curated IS/BS/CF + calculations for standardized coverage
- `list_financial_metrics` — discover the catalog of standardized metric names (use when filters return zero rows)
- `query_financial_reserves` — proved reserves, PUD/PDP, standardized measure, reserve reconciliation
- `query_operational_metrics` — production volumes, realized prices, LOE, GPT, per-BOE unit costs
- `query_property_metrics` — acreage, well counts, DUCs, drilled/completed activity
- `query_guidance_metrics` — forward-looking guidance by basin + target period
- `query_credit_metrics` — debt, revolver/RBL, notes, covenants, ratings, liquidity (latest snapshot)
- `query_hedges` — derivative book (swaps, collars, floors, sold puts, basis swaps), tranche-level
- `query_cost_disclosures` — public well-cost disclosures from filings (different from proprietary `query_well_costs`)
- `query_executive_comp_incentives` — proxy-disclosed comp KPIs, performance periods, weightings
- `search_xbrl_companies` — find any of ~146 companies in the SEC universe
- `query_xbrl_raw` — raw XBRL query against any SEC filing (escape hatch for custom facts)

### Synthesis & knowledge (3)
- `query_vault_knowledge` — query AFE Leaks research vault (notes, write-ups, analyses)
- `create_corporate_profile` — auto-synthesize a full corporate profile (chains many tools)
- `create_well_dossier` — bounded multi-section view of ONE well in a single call (metadata, map-ready location, line-item costs, production, well tests, EUR, casing, surveys, formations, optional completion/FracFocus). Resolves by `api_number` or `lease_name`+`well_number`. Use this instead of manually chaining single-purpose well tools. `detail_level` (brief/standard/deep) controls row limits; `sections` narrows what's returned.

### Account utility (1, free)
- `get_mcp_credit_balance` — current MCP credit balance (does not consume credits)

---

## "Which tool when" cheat sheet

| Question type | Tool |
|---|---|
| Well costs (total, D&C split) | `query_well_costs` |
| Cost line items (casing, stim, cement) | `query_cost_details` |
| Vendor spend / service-provider analysis | `query_vendor_costs` |
| IP rates, well tests, flow rates | `query_well_tests` |
| Production (cumulative, monthly) | `query_production` |
| Formation depths, landing zones | `query_formations` |
| Casing design (sizes, grades) | `query_casing` |
| Wellbore trajectory, DLS | `query_surveys` |
| Single-well EUR / decline parameters | `query_well_eur` |
| Broad Dataverse well search | `query_dataverse_wells` |
| Permit data / lifecycle | `query_dataverse_permits` |
| FracFocus / completion metrics | `query_completion_metrics` |
| Raw completion filings | `query_completion_raw` |
| Cross-group cost comparisons | `compare_costs` |
| Standardized financial statements | `query_financials` |
| Public cost guidance / cost-per-foot | `query_cost_disclosures` |
| Exec comp / proxy KPIs | `query_executive_comp_incentives` |
| Hedge book / derivatives | `query_hedges` |
| Reserves disclosures | `query_financial_reserves` |
| Production volumes, prices, LOE, GPT | `query_operational_metrics` |
| Acreage, well counts, DUCs | `query_property_metrics` |
| Forward-looking guidance | `query_guidance_metrics` |
| Debt, ratings, covenants | `query_credit_metrics` |
| Raw SEC XBRL / unsupported metrics | `search_xbrl_companies` → `query_xbrl_raw` |
| Corporate profile / peer memo | `create_corporate_profile` |
| Operator name resolution | `search_operators` (always call first) |
| Find a well by API/lease/operator | `search_wells` |
| Single well detail (quick) | `lookup_well` |
| In-depth single-well dossier | `create_well_dossier` |
| Basin/play discovery | `get_basin_info` |

**Routing rule for financials:** route by subject area first. Use `create_corporate_profile` for broad multi-section work. Use the dedicated tool (reserves / guidance / cost disclosures / exec comp / operational / property / hedges / credit) for one specific subject. Fall back to `search_xbrl_companies` → `query_xbrl_raw` only when the curated tools return nothing.

---

## Beyond tools — MCP resources & prompts

The server also exposes two non-tool MCP surfaces. Support varies by client (Claude Desktop and Claude Code surface both; some clients only show tools). If your client supports them, prefer them — they cut planning cost.

### Resources (read-only context, **never debited**)
Inspect these *before* querying to plan better and avoid wasted calls. They are not tools and do not consume credits.

| URI | What it gives you |
|---|---|
| `afeleaks://profile/data-summary` | Condensed dataset coverage summary |
| `afeleaks://profile/tool-routing` | The full tool-routing guide |
| `afeleaks://schema/ops` | Operations DB (afeleaks) schema summary |
| `afeleaks://schema/fin` | Financial DB (xbrl) schema summary |
| `afeleaks://schema/og-dataverse` | og_dataverse schema + full-universe coverage |
| `afeleaks://catalog/rag-corpus` | Vault/RAG corpus coverage for `query_vault_knowledge` |
| `afeleaks://catalog/basins-plays` | Basin/play catalog + legacy basin aliases |
| `afeleaks://catalog/financial-metrics` | Catalog of standardized financial metric names |
| `afeleaks://docs/credit-usage` | How credit metering and `_usage` work |

**Tip:** reading `afeleaks://catalog/basins-plays` is the zero-credit way to learn valid basin/play strings — equivalent to `get_basin_info` but free. Same for `afeleaks://catalog/financial-metrics` vs `list_financial_metrics`.

### Prompts (one-call guided workflows)
Repeatable analyst recipes that chain the right tools and standardize the output.

| Prompt | Produces |
|---|---|
| `permit_activity_report` | Ranked permit-activity report (Dataverse permit summaries) |
| `corporate_profile_memo` | Analyst memo from `create_corporate_profile` + optional vault citations |
| `type_curve_eur_benchmark` | Type-curve / EUR / cost benchmark around an anchor well or location |
| `well_dossier` | In-depth single-well view (wraps the `create_well_dossier` tool) |

---

## Vocabulary

### Operator aliases (tickers → search terms)
The MCP resolves these automatically inside `search_operators`, but knowing them speeds up your prompts.

| Ticker | Search as | Notes |
|---|---|---|
| APA | Apache | |
| AR | Antero | |
| CHRD | Chord | (Whiting + Oasis merger) |
| CIVI | Civitas | Colorado DJ Basin |
| CNX | CNX | |
| COP | ConocoPhillips | |
| CRK | Comstock | |
| CTRA | Coterra | (Cabot Oil + Cimarex merger) |
| DVN | Devon | |
| EOG | EOG | |
| EQT | EQT | |
| EXE | Expand Energy | (Chesapeake + Southwestern merger — `CHK` and `SWN` resolve to Expand) |
| FANG | Diamondback | |
| MTDR | Matador | |
| NOG | Northern | |
| OVV | Ovintiv | |
| OXY | Occidental | |
| PR | Permian Resources | |
| RRC | Range Resources | |
| SM | SM Energy | |
| XOM | ExxonMobil | |

**Defunct / no longer independent — do not use as examples:**
- Pioneer Natural Resources (PXD) — acquired by Exxon May 2024
- Hess (HES) — Chevron acquisition pending
- Marathon Oil (MRO) — acquired by ConocoPhillips Nov 2024
- Callon (CPE) — acquired by APA April 2024
- Endeavor — acquired by Diamondback Sep 2024
- Earthstone (ESTE) — acquired by Permian Resources Nov 2023
- Whiting (WLL) — merged into Chord (CHRD)

### Basin / play filtering — how it actually works

**Source of truth:** `og_data.basin` and `og_data.play` are first-class columns on the well table. Upstream tools filter on them directly with `ILIKE '%<value>%'` (substring, case-insensitive). There is no state-and-county join behind the scenes.

**Always start with `get_basin_info`** (no args) to see the exact distinct values stored in `og_data.basin` and `og_data.play`, with well counts. Pass a `basin_name` to drill into the states/counties/plays under that basin. Use the returned strings verbatim (or a distinctive substring of them) when filtering.

**Common natural-language references the user may type:**

| User says | What it usually means in the data |
|---|---|
| "Permian" | An umbrella term — usually best filtered as `play=Wolfcamp` / `play=Bone Spring` / `play=Spraberry`, or as Delaware + Midland basins. Confirm with `get_basin_info`. |
| "Delaware" / "Delaware Basin" | Western Permian sub-basin (TX: Reeves, Loving, Ward, Culberson, Pecos; NM: Lea, Eddy) |
| "Midland" / "Midland Basin" | Eastern Permian sub-basin (TX: Midland, Martin, Upton, Reagan, Glasscock, Howard) |
| "Bakken" | Williston Basin (ND core + a slice of MT) |
| "DJ" / "DJ Basin" | Denver-Julesburg (Weld County CO is the core) |
| "STACK" | Sooner Trend Anadarko Canadian/Kingfisher (OK) |
| "SCOOP" | South Central Oklahoma Oil Province (Grady, Garvin, Stephens, McClain, Carter) |
| "Haynesville" | East TX panhandle (Panola, Harrison, Shelby) + NW Louisiana (Caddo, Bossier, De Soto, Red River, Sabine) |
| "Marcellus" / "Utica" | Appalachia (WV is the slice we cover) |
| "Eagle Ford" | South TX. Distinct from "Austin Chalk" even though the geology overlaps — they're different stored play values. |

These are *hints for resolving user speech*, not definitions of how filtering works. If the user names a basin and you're not sure it matches the stored value, call `get_basin_info` rather than guessing.

---

## Coverage caveats

- **Cost data ≠ full well universe.** ~100K wells have cost data; ~770K wells have basic metadata. Most cost-data tools (`query_well_costs`, `query_cost_details`) are restricted to the cost-data slice. Use `query_dataverse_wells` to see the full universe.
- **AFE ≠ Actual.** `query_well_costs` and `query_cost_details` both have a `cost_type` parameter (AFE, Actual, Both, None). AFE is forecast budget; Actual is what was spent. They are not always reconciled.
- **Lateral length is `perf_interval` on `og_data`.** Most filtering uses this column. Be careful with units (feet).
- **Production has two flavors.** "Allocated monthly production" (`query_production`, sourced from `prod_data`) is allocated to API. Raw lease-level RRC production is a separate, larger universe — different tools.
- **XBRL standardized covers ~24 tickers** (EOG, DVN, OXY, CRK, SM, PR, CIVI, MTDR, FANG, CTRA, COP, AR, EQT, RRC, CNX, EXE, plus others added over time). `search_xbrl_companies` + `query_xbrl_raw` reach all ~146 in the SEC universe.
- **Hedge book is replace-the-book per filing date.** Each `(ticker, as_of_date)` is a complete snapshot. Don't try to time-series across as_of_date by stacking rows.
- **Credit metrics is a latest-snapshot table.** It's NOT a time series. Pivoting by `enddate` is wrong — render flat with `enddate` as a per-row "As of" column.
- **Guidance metrics IS time-series-friendly.** Unlike credit, pivoting by `target_period` is meaningful.

---

## Workflow recipes

### "What does Operator X spend in Basin Y?"
1. `search_operators(name_partial="X")` → confirm canonical spelling + cost-data well count
2. `query_well_costs(operator=..., basin=...)` with `group_by="year"` for the trend
3. Optionally `query_cost_details` to drill into drilling vs completion vs facilities

### "Pull a full company profile for Ticker"
1. `create_corporate_profile(ticker=...)` — one call, chains many tools
2. Synthesize the analyst narrative yourself; do not dump the JSON

### "Build an in-depth view of a single well"
1. `create_well_dossier(api_number=...)` (or `lease_name`+`well_number` if the API is unknown) — one bounded call returns metadata, location, costs, production, tests, EUR, casing, surveys, formations, and completion context
2. Start at `detail_level="standard"`; go `"deep"` only if you need the largest payloads. Narrow `sections=[...]` to keep credits down when you only need a few
3. Don't hand-chain `lookup_well` + `query_cost_details` + `query_production` + … for this — the dossier is the purpose-built shortcut

### "Compare two operators on per-foot cost in the Delaware Basin"
1. `search_operators` for each name to confirm spelling
2. `compare_costs` with both operators and `basin=Delaware`. The tool returns both total well cost and cost-per-foot internally — no separate normalization argument is needed.
3. Cross-check with `query_cost_disclosures` for what each one publicly claimed

### "Build a type curve for the Haynesville at 2-mile+ laterals"
1. `search_wells` or `query_dataverse_wells` to find candidate APIs (state=TX/LA, `play` matching Haynesville — call `get_basin_info` first if you're unsure whether Haynesville lives in `og_data.basin` or `og_data.play`; filter by `perf_interval ≥ 10000` for ≥2-mile laterals)
2. `build_type_curve` with the API list
3. `query_well_eur` on a sample to sanity-check decline parameters

### "What's the 2026 hedge book for Operator X?"
1. `search_xbrl_companies` if the ticker isn't already known
2. `query_hedges(ticker=X, aggregation="list")` for contract-level detail, or `aggregation="summary"` for peer comparison
3. Cross-reference with `query_guidance_metrics(ticker=X, target_period="2026_fy")` for the production volumes being hedged against

### "Has any public operator disclosed cost-per-foot in this basin?"
1. `query_cost_disclosures(basin=...)` — public disclosures only, distinct from proprietary AFE data
2. Optionally `compare_costs` for the proprietary side to triangulate

---

## Credits guidance

- **Narrow filters are cheap, broad scans are expensive.** Specify operator, basin, date range whenever you can. A `query_well_costs` over "all Delaware wells since 2020" is bigger than "Diamondback Delaware wells 2023".
- **Use `aggregation="summary"` before `"list"`.** Summary returns aggregate rows; list returns one row per well. Start with summary, then drill down with list only when needed.
- **`get_mcp_credit_balance` is free.** Ask "what's my MCP credit balance?" anytime — it never bills.
- **Duplicate calls don't double-charge.** Each invocation has an idempotency key; retries from flaky clients reuse the original debit.
- **`_usage.credits_charged` is in the response.** Watch it — if a query is unexpectedly expensive, narrow the filter and re-ask.

---

## Common pitfalls

- **Don't ask for raw SQL.** The MCP exposes typed, parameter-based tools deliberately. There is no `query_sql` tool.
- **Don't assume a ticker maps to an operator name 1:1.** Operator names in the well database are the legal entity that filed the permit (often a subsidiary). Always go through `search_operators`.
- **Don't pivot `credit_metrics` by date.** It's a latest snapshot, not a time series. See coverage caveats.
- **Don't use Pioneer, Hess, Marathon, Callon, or other delisted/acquired tickers as examples.** See vocabulary.
- **Don't compute aggregates client-side when a tool will do it.** `query_well_costs` returns avg + median in one shot. Don't fetch all wells and average them locally — that wastes tokens and credits.

---

*This file is published at https://afeleaks.com/skills/afeleaks-mcp.md. Re-download periodically — the tool surface and ticker coverage evolve.*