# Reported issues for mcp-server by OilpriceAPI

Pod holds 16 of 24 GitHub reports that passed its relevance review. This can include external user reports, maintainer-confirmed bugs, and concrete feature gaps. Treat them as evidence to inspect, not a count of distinct defects.

Back to [mcp-server by OilpriceAPI](/mcp/mcp-server-by-oilpriceapi).

## Most discussed

### [P1][MCP] Expose versioned product facts to connected assistants

## Outcome

Give MCP-connected assistants a first-party, current answer for OilPriceAPI product and integration facts instead of relying on model memory or duplicated package prose.

## Scope

- Expose a read-only `oilpriceapi://product-facts` resource backed by the reviewed public product-facts contract.
- Provide one narrowly named read-only tool for hosts that discover tools but do not automatically load resources.
- Return schema version, contract version/ETag, reviewed date, canonical URLs,

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/50) · 2026-07-18 · closed · 3 comments

### Structured demand telemetry: log tool calls + unanswerable asks (hit/miss)

**Bottom line up front, this is a valid observation but is not part of the economically justified delivery queue.**

_Economic grooming decision (2026-08-04): The item is explicitly parked/rejected, has low inaction risk, and records no near-term economic case. Closed as not planned; reopen only when a named economic or obligation trigger is met._

---

From oilpriceapi-api#4758 experiment 3. The MCP server is a demand-sensing instrument: what agents ask for that we CAN'T answer (unknown codes, 

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/42) · 2026-07-17 · closed · 3 comments

### Verify/refresh Smithery, Glama, PulseMCP listings

Smithery sandbox export exists in code but listing state unverified; Glama/PulseMCP unknown.

**Acceptance:** each listing shows v2.3.0+ (or submission filed where absent).

Sprint item 8 of docs/DISTRIBUTION_CONVERSION_PRD.md (P1).

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/19) · 2026-07-02 · closed · 3 comments

### [P1][Contract] Publish a versioned MCP capability manifest from the tool registry

## Outcome

Publish a versioned, machine-readable MCP capability manifest so the website,
docs, directories, and compatible clients can describe the released package
without hard-coded tool counts or stale configuration claims.

## Contract

The published package must expose a JSON command or artifact containing:

- package name, version, minimum Node version, repository, and source commit;
- supported client configuration template and required environment variables;
- scope/profile names and th

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/47) · 2026-07-17 · closed · 2 comments

### Claude Desktop extension (.mcpb) bundle + directory submission

One-click install surface for non-developers — zero presence today. Build .mcpb bundle, test local install, submit to the Claude Desktop extensions directory.

**Acceptance:** bundle installs clean locally; submission confirmed.

Sprint item 7 of docs/DISTRIBUTION_CONVERSION_PRD.md (P1).

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/18) · 2026-07-02 · closed · 2 comments

### No natural-gas hubs tool — the #1294 discoverability fix never reached the MCP surface

## Verified 2026-08-09

`grep -in 'natural-gas/hubs\|natural_gas_hub' src/index.ts` on origin/main (b1d557f): **no matches**. The MCP server has no tool for `/v1/natural-gas/hubs`, the endpoint api#1294 built specifically because customers could not find our physical hub coverage ("Two customers — one of whom was paying and churned — never found them").

## The third customer who couldn't find it

`cairns.ap@gmail.com` (independent nat-gas researcher, the MCP-widening interview thread): on his *

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/64) · 2026-08-09 · closed · 1 comment

### [P1][DX] Add --version, --list-tools, and doctor/doctor --demo diagnostics

## Goal

Make installation and support diagnosable without starting an opaque stdio session.

## CLI contract

- `npx -y oilpriceapi-mcp --version`
- `npx -y oilpriceapi-mcp --list-tools`
- `npx -y oilpriceapi-mcp doctor`
- `npx -y oilpriceapi-mcp doctor --demo`

## Acceptance criteria

- [ ] `--version` prints package version and exits 0 without opening stdio.
- [ ] `--list-tools` prints stable human output plus a JSON option and respects scope/profile.
- [ ] `doctor` checks Node >=18, package/

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/46) · 2026-07-17 · closed · 1 comment

### [P1][Safety] Default to read-only tools; require explicit scope for account mutations

## Problem

The MCP server registers alert/subscription create/delete tools alongside read tools. Tool annotations help clients, but simply exposing mutation tools increases accidental-action and tool-overload risk.

## Decision

Use explicit tool scopes/profiles. Do **not** add a generic discover/describe/execute tool that can bypass per-tool authorization or obscure the action being approved.

## Acceptance criteria

- [ ] Default scope is read-only, or make read-only the recommended one-comma

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/45) · 2026-07-17 · closed · 1 comment

## Most recent

### Tool descriptions don't state tier requirements — agents discover the paywall by probing

## Customer-sourced (cairns.ap@gmail.com, MCP thread 2026-08-08)

> Put plan requirements in the tool descriptions. Agents read schemas, not pricing pages — if get_storage doesn't say which tier it needs, every agent that sees it will try it. That alone would have saved my session the probe.

## Verified against production, 2026-08-09

**His session (api_requests, user 9a130e9a):** 2026-07-21 and 07-31, `client_type=sdk-mcp` — an agent enumerating the tool list on a free-tier key hit `past_year`

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/63) · 2026-08-09 · closed · 0 comments

### [Q1] get_fuel_surcharge MCP tool (parity+ w/ NexusFeed; needed for Aug-1 #3898 review)

Parent: OilpriceAPI/oilpriceapi-api#4767 · **EM quadrant: Q1 (urgent + important — hard date Aug 1)** · PRD attached to parent.

## Task

Add a `get_fuel_surcharge` tool to the OPA MCP server (v2.4.x).

- `get_fuel_surcharge(carrier?)` → current published fuel-surcharge % per carrier (all carriers when omitted), effective date, matched diesel band, underlying DOE diesel price, source + retrieved_at. Calls the public `/v1/fuel-surcharge` endpoints.
- Urgency: the Aug-1 MCP monetization review (oi

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/43) · 2026-07-17 · closed · 0 comments

### GitHub settings hardening checklist

Generated from a GitHub settings audit on 2026-07-16.

Use this as a working checklist. If this repository is no longer maintained, archive it and close this issue instead of applying every hardening item.

## Branch And Merge Controls
- [ ] Protect `main` with a branch rule or ruleset: require pull requests, passing CI checks when available, conversation resolution, and block force pushes/deletions.
- [ ] For production/customer-facing repos, apply branch/ruleset requirements to admins as well 

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/41) · 2026-07-16 · closed · 1 comment

### Karl's action batch: account-gated distribution steps (~20 min)

**Bottom line up front, this is a valid observation but is not part of the economically justified delivery queue.**

_Economic grooming decision (2026-08-04): The item is explicitly parked/rejected, has low inaction risk, and records no near-term economic case. Closed as not planned; reopen only when a named economic or obligation trigger is met._

---

Consolidated checklist of the human-required steps left from the 2026-07-02 distribution sprint — everything automatable is already done (v2.4.0

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/28) · 2026-07-02 · closed · 1 comment

### Deprecate stale io.github.karlwaldman/oilpriceapi registry listing (v1.0.3)

While closing #14 we found the second isLatest=true entry is a *different server name*: io.github.karlwaldman/oilpriceapi v1.0.3 (published Dec 2025, personal namespace, points at the archived karlwaldman/oilpriceapi repo). It competes with the official io.github.OilpriceAPI/mcp-server listing in registry search.

Fix requires auth for the io.github.karlwaldman namespace — either `mcp-publisher login github` (device flow, Karl interactive) then deprecate/delete, or a one-off OIDC workflow in any

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/23) · 2026-07-02 · closed · 1 comment

### Extend tier-limit upgrade nudges to all tool error paths

Watches already return per-tier limit messages on gate errors. Extend the pattern: every 402/403/429 surfaced by any tool includes the exact limit hit + upgrade link. Ships inside v2.4.0.

**Acceptance:** simulated 429/403 on each tool family shows limit + link.

Sprint item 5 of docs/DISTRIBUTION_CONVERSION_PRD.md (P1).

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/17) · 2026-07-02 · closed · 0 comments

### v2.4.0: keyless demo mode via /v1/demo/prices + teaser errors

Keyless MCP users currently hit a hard 401 — yet /v1/demo/prices already exists (keyless, live Brent/WTI/diesel/gasoline) and src/index.ts never references it.

- No OILPRICEAPI_KEY → price-read tools serve /v1/demo/prices with footer: demo data, limited set, free key at oilpriceapi.com/auth/signup?utm_source=mcp-demo
- Tools without demo coverage (history, futures, alerts, watches) → teaser error: what the tool does + sample output + signup link, never a bare 401
- Startup without key logs a fr

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/16) · 2026-07-02 · closed · 0 comments

### CI: publish to MCP registry atomically with npm publish

Registry staleness happened because npm publish is automated (publish.yml, OIDC) but registry publish is manual. Add an mcp-publisher step (github-oidc login) to publish.yml so both happen on every release, plus a version check that server.json matches package.json. Include a workflow_dispatch backfill path.

**Acceptance:** dry-run/backfill run green; next release publishes both registries with no manual step.

Sprint item 2 of docs/DISTRIBUTION_CONVERSION_PRD.md (P0).

[Read the thread](https://github.com/OilpriceAPI/mcp-server/issues/15) · 2026-07-02 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/OilpriceAPI/mcp-server/issues).