Agents
Connect AI agents and automations to PetroBench through the hosted MCP server or the REST API. Access is opt-in and off by default.
Connect AI clients, scripts and internal systems to your PetroBench wells and simulations. Choose the hosted MCP server for AI clients, or the REST API for custom integrations.
Connect Claude, ChatGPT, Gemini or any MCP-compatible tool to your wells and simulations. Token scopes control what it can do.
Call REST endpoints from scripts, pipelines and internal systems with scoped tokens.
What you can build
An agent is any program that works with PetroBench on your behalf: an AI client answering an engineer's question, a nightly job that keeps well data current, or an internal tool that runs simulations and posts the results elsewhere.
| Who | Typical setup | Example |
|---|---|---|
| Production and optimization engineers | Claude, ChatGPT or Gemini connected over MCP | "Compare the last two simulations on this well and explain the change in rod loading" |
| Data and IT teams | Scheduled jobs on the REST API with a service token | Sync wells, rod strings and pumping units from your system of record every night |
| Operations and reporting | BI tools or a data warehouse reading from the API | Pull simulation results into your production dashboards |
| Integration developers | Webhooks plus the API | Start downstream work as soon as a simulation finishes or a well changes |
Building blocks
| Component | What it does | Learn more |
|---|---|---|
| MCP server | Hosted server at app.petrobench.com/mcp that exposes PetroBench as tools for AI clients | MCP for Agents |
| REST API | Versioned JSON API at app.petrobench.com/api/v1 with an OpenAPI specification | API for Agents |
| Personal API tokens | Tokens a user creates for their own scripts and clients. They act as that user | API Tokens |
| Connected apps | OAuth sign-in from an AI client, approved by the user on a consent screen | Connected Apps |
| Service tokens | Division-owned tokens for shared integrations that should not depend on one person | Service tokens |
| Webhooks | Signed HTTPS callbacks when simulations finish, wells change and other events happen | Webhooks |
MCP and the REST API use the same sign-in, scopes, permissions and rate limits. A task you can do with one, you can usually do with the other.
Access is opt-in
MCP and the REST API are off by default. Nothing can connect to your organization until you ask for it.
| Control | How it works |
|---|---|
| Organization | Your PetroBench account team enables MCP and API access at your organization's request. It can be switched off again at any time |
| User | Each user connects on their own, with a personal token or by approving a connected app. Enabling access for the organization connects nothing by itself |
| Permissions | A connection only sees what its owner can see in the web app. Write tools appear only for connections with write scopes |
| Revocation | Users revoke tokens and disconnect apps under Settings. Admins can use Kill access on a user and revoke division service tokens |
| Audit | Token changes and connected app approvals are recorded in the audit log |
See AI and MCP Controls for the full security detail your IT team may ask for.
How access works
Every request, from an AI client or a script, goes through the same checks:
- Organization: Is MCP or API access enabled for this organization, and does the plan include it?
- Credential: Is the token or OAuth grant valid, not expired, not revoked, and inside its IP allowlist if it has one?
- Scope: Does the credential carry the scope this action needs, such as
wells:readorsimulations:run? - Role: Can the owner see this well or record in the web app?
- Rate limit: Is the token and division within its limits?
Only when all five pass does PetroBench run the action. The request is then logged with the user, token and result.
Scopes
Scopes limit what a token or connected app can do. Grant only the scopes an agent needs.
wells:readFind wells and read their equipment, geometry, production and data qualityTools:find-wellsFind wells by name, API number, tag or filters, or find similar and duplicate wellsget-wellRead a well's identity and status, with optional engineering details and performanceget-well-equipmentRead the installed pumping unit, rods, tubing, pump, anchor and casingget-well-geometryRead the wellbore, casing, perforations and directional surveyget-well-productionRead production history, trends, water cut and fluid shotsquery-equipmentBrowse the pumping unit and rod catalogfleet-wellsCompare metrics across several wellsorg-dashboardRead fleet totals such as wells by statusdetect-data-gapsList wells missing key data such as a survey or productionvalidate-well-dataCheck whether a well has the data it needs to simulatemanage-webhooksList webhooks and their deliveries. Creating or changing them needs wells:writewells:writeCreate and update wells and their equipment, import well files and merge duplicatesTools:manage-wellCreate, update, archive or delete a wellset-well-detailsUpdate engineering inputs such as water cut, oil API and pressuresset-well-rodsReplace the rod stringset-well-tubingReplace the tubing stringset-well-pumping-unitSet the pumping unitset-well-casingReplace the casingset-well-perforationsReplace the perforation intervalsset-well-performanceUpdate pump depth and bottomhole pressure inputsset-directional-surveyAdd a directional survey so the well can be simulatedmanage-field-dataAdd, edit or delete fluid shots and production rowsimport-well-fileImport a single well file such as a legacy design file, CSV or Excelmanage-importRun a bulk import of many well filesmanage-well-mergePreview and merge duplicate wells into oneassign-wellsAssign wells to a group or region in bulksimulations:readRead, compare and interpret simulations and their resultsTools:query-simulationsSearch and filter simulations across your wellsget-simulationRead a simulation's configuration and statusget-simulation-resultsRead the output metrics and results of a simulationinterpret-simulation-resultsPull out the key engineering findings from a completed simulationanalyze-simulationRead rod stress and other detailed diagnostics for a simulationcompare-simulationsCompare two or more simulations side by sidemanage-comparisonsRead and manage saved comparison sets on a wellget-well-simulation-setupRead the default simulation inputs for a wellvalidate-simulation-inputsCheck proposed simulation inputs before a runmanage-simulation-versionsRead a simulation's version historyget-simulation-logRead the run log of a simulationpoll-jobCheck the status of a running simulationsimulations:writeCreate and update simulationsTools:manage-simulationCreate, update, duplicate or delete a simulationsync-installed-equipmentCopy a well's installed equipment into its installed simulationsimulations:runBuild and run simulationsTools:execute-simulationBuild, run and iterate on a rod-pump simulation in one steporganization:readRead your account, usage, people, regions and groupsTools:manage-accountRead your account, API limits and usage, and switch organizationmanage-contactsList people in your organization and on a wellmanage-regionsRead regions in your organization. Changes need organization:writemanage-well-groupsRead well groups. Changes need organization:writemanage-user-groupsRead user groups. Changes need organization:writemanage-shareRead and manage who a well or simulation is shared withlist-databridge-sync-logsRead the history of data syncs from your source systemsorganization:writeManage tags and organization defaults, and resync wells from your source systemsTools:manage-tagsCreate tags and assign them to wellsupdate-organization-defaultsChange organization-wide default settingsresync-wellPull a well again from your source system nowreset-well-from-snapshotRoll a synced well back to its last saved source snapshot
Write and run scopes depend on your plan and may need to be enabled for your organization.
Choose MCP or the API
| MCP | REST API | |
|---|---|---|
| Best for | AI clients such as Claude, ChatGPT, Gemini and Grok | Custom integrations, scheduled jobs and data pipelines |
| Who drives it | A person asking questions in an AI client | Your code |
| Sign-in | OAuth approval in the client, or a personal token | Personal token, service token or OAuth |
| Scopes | Chosen on the consent screen | Set by the token's scopes |
| Long-running jobs | The client polls for you | You poll or use webhooks |
| Guide | MCP for Agents | API for Agents |
Most teams start with MCP in an AI client, then use the REST API when they need scheduled jobs or finer control over requests.
Get started
MCP and API access require an SME or Enterprise license.
Request access
Ask your PetroBench account team to enable MCP and API access for your organization.
Decide who connects
Agree which users need access and with which scopes. For shared integrations, ask a Division or HQ Admin to create a service token.
Connect as yourself
Approve the connection from your AI client, or create a personal API token with only the scopes you need, such as wells:read and simulations:read.
Follow the guide for your client
Continue with MCP for Agents or API for Agents.
Good practice
- Start read-only: Give new agents read scopes first, and add write or run scopes once you trust the workflow.
- Keep a person in the loop: Have the agent propose changes to wells or equipment, and let an engineer confirm them.
- Use service tokens for shared work: A job that belongs to a team should not stop working when one person leaves.
- Set expiry and IP limits: Choose the shortest token lifetime that works, and restrict service tokens to your network.
- Name the person behind the call: Service tokens can send the email of the person they act for, so the audit log shows who triggered each action.
- Review access regularly: Check Last used on tokens and connected apps, and revoke what nobody uses.