MCP for Agents
Connect Claude, ChatGPT, Gemini, Grok or any MCP-compatible tool to the PetroBench MCP server
PetroBench MCP
A hosted Model Context Protocol server. Connect your AI client to PetroBench wells and simulations without writing integration code.
What it is
A hosted MCP endpoint at app.petrobench.com/mcp, with the same sign-in and scopes as the REST API.
What it does
Gives AI clients tools to read wells, simulations and equipment. Write tools appear only for tokens with write scopes.
- AI clients
Claude, ChatGPT, Gemini, Grok and any MCP-compatible tool
- Scope-gated tools
Token scopes control which tools appear
- OAuth or token
OAuth 2.1 approval, personal API tokens or service tokens
MCP access is off by default. Your PetroBench account team enables it at your organization's request. See Access is opt-in.
https://app.petrobench.com/mcpWhat it is
The Model Context Protocol (MCP) is an open standard that lets AI clients use tools from other systems. PetroBench hosts an MCP server, so an AI client such as Claude or ChatGPT can look up wells, read equipment and review simulations in PetroBench while you work, without you copying data between windows.
You do not install or run anything on your side. You point your client at the endpoint above and sign in.
How it works
Your client connects
Your AI client connects to https://app.petrobench.com/mcp and you sign in, either by approving the connection in your browser (OAuth) or with a personal API token.
PetroBench lists the tools you may use
The server only offers tools that match your token's scopes and your role. A connection without write scopes never sees write tools.
You ask a question
The AI client decides which tools to call, for example to find a well and then read its rod string.
PetroBench checks and answers
Every call is checked against your permissions, runs against your organization's data, and returns structured results. Long jobs such as simulations return a job ID that the client polls until the result is ready.
Each call counts toward your organization's rate limits and is recorded with your user and token, like any other API request.
Use cases
“Show me the rod string and pumping unit on well Smith 12-4”
Searches for the well, then reads its details and equipment.
wells:read“Which wells in the Permian region have a pump deeper than 9,000 ft?”
Lists wells with filters and reads the details of each match.
wells:read“Summarize the last simulation on this well and flag anything over 90% loading”
Reads the latest simulation and its results, then summarizes them.
simulations:read“What counterweight change would balance this unit?”
Runs the counterweight balance recommendation for the well.
simulations:read“Update the tubing on this well to 2 7/8 in and rerun the simulation”
Updates the tubing, starts a simulation, polls the job and reports the result.
wells:write, simulations:run, simulations:read“Import this well file and show me what changed”
Starts an import, previews the changes and applies them after you confirm.
wells:write“Why did last night's data sync skip this well?”
Reads the data sync logs and, if you ask, resyncs the well.
organization:read, organization:write
AI clients can make mistakes. Review any change before you confirm it, and keep write access to the users who need it.
Install in your client
Pick your AI app and follow the steps. You sign in with your PetroBench account, so you do not need a token. Any other MCP-compatible tool connects the same way: add the endpoint above as a remote server and sign in.
Available on Plus, Pro, Business, Enterprise and Edu, on chatgpt.com in the browser. ChatGPT signs in with OAuth, so you do not need a token.
Plus and Pro
- Open Settings and turn on Developer mode.
- Add a new app, name it PetroBench, and paste
https://app.petrobench.com/mcpas the server URL. - Choose OAuth, create the app, and sign in to PetroBench when asked.
- In a chat, pick the PetroBench app from the + menu, or type @ and select it.
Business, Enterprise and Edu
- A workspace admin adds the app under Workspace settings > Apps > Create, pastes
https://app.petrobench.com/mcp, and publishes it to the workspace. - Members then select PetroBench in a chat and sign in to PetroBench the first time they use it.
Use a service token (pb_svc_…) for shared agents. It belongs to a division, not a person, so it keeps working when staff leave. See Service tokens.
What the agent can do
To allow writes, tick the write scopes you want on the PetroBench consent screen when you connect, for example write wells or run simulations. Write tools appear only for tokens that carry the matching write scopes. To change scopes later, disconnect under Settings > Connected Apps and connect again. Token scopes control which tools appear. A token without simulations:read never sees simulation tools.
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
Full tool lists: Wells & field data, Simulations, Diagnostics, Account.
OAuth clients
Claude, ChatGPT, Gemini and any MCP-compatible tool that supports OAuth 2.1 can sign in with it instead of a static token. The user approves the connection on a consent screen, and can disconnect it at any time under Settings > Connected Apps. Device-code and consent flows are documented under Authentication (requires docs login).