Agent Subscriptions with MCP

Status: ✅ Available | 🤖 For AI agents & assistants

This guide shows how an AI agent — running through the OilPriceAPI MCP server (oilpriceapi-mcp) — sets up recurring commodity monitoring: it fetches a market brief, creates a persistent subscription ("watch"), and polls for new events. The event model is poll-based, not push — there is no always-on connection, so the agent calls a poll tool periodically to stay current.

The MCP server

oilpriceapi-mcp is a Model Context Protocol server that exposes OilPriceAPI as agent tools. Run it with npx and point it at your API key:

{
  "mcpServers": {
    "oilpriceapi": {
      "command": "npx",
      "args": ["-y", "oilpriceapi-mcp"],
      "env": { "OILPRICEAPI_KEY": "YOUR_API_KEY" }
    }
  }
}

This config works with any MCP-compatible host (Claude Desktop, Claude Code, and other MCP clients). Because it is a standard MCP server, it can also be consumed from agent frameworks that support MCP — for example LlamaIndex (via its MCP tool adapter) and LangChain (via its MCP adapter) — so the same tools are available whether the agent runs in a desktop assistant or inside a Python/JS agent framework.

Tools used in this recipe

All five require an API key (OILPRICEAPI_KEY).

The poll-based event model

                create watch                  every interval
   agent ───────────────────────▶  OilPriceAPI ───────────────▶ records WatchEvent
                                       │                          (snapshot + deltas)
   agent ◀──── poll events (since=cursor) ◀─────────────────────────┘
       │
       └─ persists cursor, repeats on its own schedule

1. The agent creates a watch for one or more commodities at an interval.
2. OilPriceAPI snapshots those commodities every interval and records an event with the snapshot and per-code deltas. Events are not pushed.
3. The agent polls opa_get_subscription_events, passing the since cursor from the previous poll, to retrieve only new events. The poll does not count against the monthly request quota and has its own rate lane (60/min).
4. The agent persists the returned cursor and repeats on whatever schedule it chooses.

This is fundamentally different from a price alert (threshold-crossing) — a watch always emits an event every interval, giving the agent a running log it can reason over.

Recipe: set up recurring monitoring

1. Get a brief to decide what to monitor

The agent asks for a market read first:

"Give me a morning brief on Brent, WTI, and US natural gas."

The agent calls opa_get_market_brief with codes: ["brent","wti","us gas"] and narrative: true. It receives latest prices, 24h changes, 1-month forecasts, and a plain-English summary it can relay to the user. (See Get Market Brief.)

2. Create a recurring watch

"Keep watching Brent and WTI every hour."

The agent calls opa_create_price_subscription:

{
  "codes": ["BRENT_CRUDE_USD", "WTI_USD"],
  "interval": "1h",
  "name": "Crude desk hourly"
}

The MCP server resolves the friendly interval (1h → 3600 seconds), POSTs to /v1/subscriptions, and automatically stamps attribution headers X-OPA-Source: mcp and X-OPA-Tool: opa_create_price_subscription. The watch is now persistent and tied to the user's account.

3. Poll for what changed

Later (on the agent's own cadence) it calls opa_get_subscription_events with the last cursor:

{ "since": 42 }

It receives any new events — each with a price snapshot and per-code deltas vs the previous snapshot — plus a new cursor to use on the next poll. (See Poll events.)

4. Manage watches

• opa_list_subscriptions — show everything the user is monitoring (and find a watch id).
• opa_delete_subscription — stop/remove a watch by id.

Plan gates

Watches are available on all tiers, with limits that scale by plan. The full feature set is advertised on Professional and Scale.

When a limit is exceeded the API returns the exact limit and an upgrade URL (BRIEF_CODE_LIMIT, WATCH_LIMIT, or a VALIDATION_ERROR for an interval below the floor), which the agent can surface to the user. Free tier deliberately includes the narrative brief and one hourly watch as the agent on-ramp.

Attribution

Watches created through the MCP server carry source: "mcp" and the tool_name that created them, so agent-driven usage is distinguishable from dashboard or direct-API usage in analytics. When calling the REST API directly, set X-OPA-Source and X-OPA-Tool yourself (see Create a subscription).

Related

• Get Market Brief - Endpoint reference
• Subscriptions / Watches - Endpoint reference
• Price Alerts - Threshold-crossing notifications
• Webhooks - Push delivery and signature verification