AI and MCP Controls

This page explains how your organization controls AI, MCP and API access in PetroBench.

Key points

• Off by default: AI features, MCP, the REST API and webhooks stay off until your organization asks for them.
• Not required: Well management and rod-lift simulation are deterministic engineering calculations. They work the same with AI off.
• Tied to a person or division: Every connection is created by a named user or admin, sees only what its owner can see, and can be revoked at any time.
• No model training: PetroBench does not use customer data to train AI models.

Off by default

If your security policy is to keep AI disabled, no action is required. That is the default state, and nothing changes unless your organization asks for it.

API, MCP and webhook access depend on your plan. Your order form lists what is included.

Ways to connect

Enabling access for your organization does not connect anything by itself. Every connection needs an explicit step by a person in your organization, and each one is tied to a user or a division.

A token or connected app never sees more than its owner can see in the web app. It follows the same role, division and organization boundaries.

Personal API tokens

Users create personal tokens under Settings > API Tokens.

• Scopes: The user picks what the token can do, for example read wells, write wells, read simulations or run simulations. Only scopes the user's role and plan allow are offered.
• Expiry: Tokens expire after 7, 30, 90 or 365 days. There is no token without an expiry.
• IP allowlist: On plans that include it, a token can be limited to a list of IP addresses.
• Last used: Each token shows when it was last used.
• Revoke: The user can revoke a token at any time. It stops working on the next request.

Connected apps (OAuth)

MCP clients such as Claude and ChatGPT connect through a standard OAuth 2.1 sign-in with PKCE. The user signs in to PetroBench and sees a consent screen that lists what the app is asking for. The default MCP scope is read-only: read wells, simulations and equipment.

• Read scopes are always on. Write scopes, such as write wells or run simulations, start unticked. The user ticks each one on purpose.
• The consent screen only offers scopes the user's role and plan allow. The server checks this again when it issues the token.
• The audit log records the scopes the user granted.
• Acting on behalf of another user is never available over OAuth.
• To change scopes, disconnect the app and connect it again.
• Only approved client domains can receive a sign-in redirect.
• Users see every connected app under Settings > Connected Apps.
• Disconnect revokes all access and refresh tokens for that app at once.

Service tokens

Service tokens are for integrations that should not depend on one person's account. They belong to a division, not to a user.

• Who can create them: Division Admins and HQ Admins, under API & Integrations > API Console > Service Tokens.
• Permissions: Chosen at creation. A service token can only receive permissions the division is licensed for.
• Expiry: 30, 90 or 365 days. Admins receive reminder emails 30 days and 7 days before a token expires.
• IP allowlist: A service token can be limited to known IP addresses. A request from an unknown address pauses the token until an admin resumes it.
• Limits: Up to five active service tokens per division.
• Rotate and revoke: Rotating issues a new secret with the same name, permissions and IP list, and revokes the old one. Revoking stops the token on the next request.
• Seats: Service accounts do not count as user seats.
• Audit trail: The calling system can name the person it acts for. PetroBench records that person in the audit log when they are an active user in your organization, and records the division's service account otherwise.

Webhooks

Webhooks send an HTTPS request to your system when something happens in PetroBench, so you do not need to poll the API.

• Who can manage them: Division and HQ Admins, under API & Integrations > API Console > Webhooks.
• Events: Simulation completed or failed, well created, updated, archived or equipment changed, report and export ready, import completed, user invited or removed, and API token created, revoked or paused. The full list is in the webhook reference.
• Signing: Every delivery carries an X-PetroBench-Signature header, an HMAC-SHA256 signature over the timestamp and body, plus an X-PetroBench-Timestamp header. Verify both before you trust a delivery. When you rotate the secret, the old secret stays valid for one day so you can switch without downtime.
• Retries: A failed delivery is retried up to eight times with increasing delays over about 24 hours. Redirects are not followed.
• Auto-disable: A webhook that keeps failing for three days is disabled, and admins are notified.
• Delivery log: Each delivery is logged with its request and response, and admins can resend a delivery from the console.

Rate limits

API and MCP requests are rate limited per token and per division, with monthly quotas that depend on your plan. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers so clients can back off before they hit the limit.

Switching access off

• One user: The user revokes their tokens or disconnects an app under Settings. Admins can use Kill access on a user, which deletes all of that user's tokens and ends their sessions.
• One integration: An admin revokes the service token or disables the webhook in the API Console.
• The whole organization: Contact your PetroBench account team to switch MCP, the API, webhooks or AI features off. Existing tokens and connected apps stop working once access is switched off.

Every token change and connected app authorization is recorded in the audit log.

Your data and model training

PetroBench does not use customer data to train AI models. When AI features are enabled, model providers process only the data needed to answer a request, under contracts that prohibit them from training on it.

When you connect your own AI client over MCP, the data that client receives is governed by your agreement with that provider. See the Privacy Policy for details.

FAQs

Related

• MCP for Agents: how to connect an MCP client once MCP is enabled
• API Tokens and Connected Apps: user guides
• Authentication & Access: SSO, MFA, sessions and audit logs
• Trust FAQs