MCP server reference

Benson runs a remote MCP server, so an AI agent can work in your Benson account: set up a store, read its numbers and make changes after you confirm each one. This page is for developers and for anyone setting up a client by hand. For one-click installs, see the MCP server page.

Clients#

It works with any MCP client that speaks Streamable HTTP and OAuth. These have step-by-step setup:

• Claude
• ChatGPT
• Cursor
• VS Code
• Claude Code
• Codex
• Gemini CLI
• Any MCP client

Endpoint#

https://api.trybenson.com/mcp

• Transport: Streamable HTTP. Send JSON-RPC as POST; responses are JSON. GET and DELETE return 405.
• No session state. Each request stands alone, so there's nothing to resume after a dropped connection.
• Spec versions: clients on the current MCP spec and on the 2025 versions both work.

Authentication#

There are two ways in: OAuth for agents a person signs in to, and agent keys for agents that run on their own.

OAuth#

Add the endpoint to your client and it finds everything else. A request without a token gets 401 with a WWW-Authenticate header that names the protected resource metadata. From there the client reads the authorization server's metadata and starts the sign-in.

• OAuth 2.1 with PKCE. Only S256 code challenges are accepted.
• Client registration: client ID metadata documents (preferred), or dynamic client registration for clients that don't support them yet.
• Public clients. No client secret is needed (token_endpoint_auth_methods_supported includes none).
• Tokens: the access token's audience is the endpoint above. Refresh tokens rotate.

The person signs in to Benson with any of their usual methods, then sees a consent page that names the client and asks for two things: which organization, and what the connection may do.

Scopes#

A member of the organization can only grant benson:read. Owners and admins can grant both. A connection with benson:read alone sees only the reading tools.

One organization per connection#

Each grant is bound to the one organization picked on the consent page, and no tool takes an organization argument. To work in another organization, connect again and pick it. Agencies connect once for each client.

The connection acts as the person who connected it. Their role is checked again on every call, so a member who is removed is cut off on their next call.

Agent keys#

For agents that can't open a browser, like CI jobs, scripts and agent backends, create a key in Settings → AI agents → Agent keys.

• A key starts with bnk_ and is shown once. Benson keeps only its hash.
• It works in one organization, with read or read-and-change access, and can expire after 30, 90 or 365 days, or never.
• It acts as the person who created it, with their role checked on every call. It stops working when it's revoked or expires, or when that person leaves the organization.
• Members can create read keys. Owners and admins can create keys that make changes.

Send it as a bearer token to the same endpoint. It's never accepted in a query string, and it doesn't work on Benson's other APIs.

{
  "mcpServers": {
    "benson": {
      "type": "http",
      "url": "https://api.trybenson.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BENSON_AGENT_KEY}"
      }
    }
  }
}

A headless agent gets the same previews as everyone else. Show the preview to a person, or decide in your own code, before you send the confirmation back.

Tools#

The server lists the tools a connection may use: reading tools for everyone, and the tools that make changes only with benson:write and a role that allows them. Reads change nothing. Asks first tools follow the confirmation protocol below. A plan name means the change needs that plan; reads follow your plan too, and say which plan includes what you asked for.

Each tool takes an optional site (a site ID or a domain). With one store in the organization you can leave it out. Each tool's exact arguments are in its schema in tools/list.

Prompts#

Prompts are ready-made starts that name the tools to use in order. Claude Code and Claude Desktop show them as slash commands.

Confirmation#

Every tool marked Asks first changes nothing on its first call. It answers with a preview and a single-use confirmation token instead:

// tools/call set_blocker_mode (illustrative arguments)
{ "site": "mystore.com", "mode": "block" }

// structuredContent of the result
{
  "status": "needs_confirmation",
  "preview": { /* what changes, on which store, from → to, and who it affects */ },
  "confirmation_token": "cfm_…",
  "expires_at": "2026-10-05T14:10:00Z"
}

The text of the result starts with "Nothing has changed yet." and then describes the change. Your agent shows the person the preview in its own words. Only after they say yes does it call again, with the same arguments and the token:

// tools/call set_blocker_mode, after the person says yes
{ "site": "mystore.com", "mode": "block", "confirmation_token": "cfm_…" }

• The token works once, for the same tool, arguments, connection and organization. Different arguments, an expired token or another connection's token all fail with "Ask again: the change wasn't confirmed."
• Retries are safe. If the confirmed call is retried, it returns the first result without acting twice.
• Plan problems show up front. If the change needs a plan you don't have, the preview says so and no token is issued.
• Clients that support forms may show a Confirm form instead of the token round trip. It's the same rule: nothing changes without a yes.

start_test_session is the one tool that makes something without asking: a short-lived test link. It changes nothing in your store.

What stays in the dashboard#

These never go through the MCP server. Tools that lead there answer with a link to the right dashboard page.

• Billing: choosing a plan, checkout, cancelling
• Deleting a store, purging its data, or deleting the organization
• Rotating site keys, policy keys or edge secrets
• Removing members, changing roles or transferring ownership
• Connecting integrations that need a secret (email platforms, Slack)
• Exporting all of the organization's data

Errors#

Problems with a call come back as a normal tool result marked isError, with a message that says what to do next. Protocol errors are only for unknown tools and malformed requests.

Limits#

Untrusted data#

Some values in results come from shoppers or store staff: UTM values, referrers, page paths, campaign names and copy, discount codes, and member names. In the text of a result they sit inside <untrusted-data> and </untrusted-data>, and long values are clipped. The server's instructions tell agents to treat anything inside as data, never as instructions.

That lowers the risk; it can't remove it. Keep changes behind the confirmation step, and read previews before you say yes.

Revoking access#

• A connection: Settings → AI agents → Disconnect. It stops on its next call.
• An agent key: Settings → AI agents → Agent keys → Revoke. It stops on its next call.
• A person: removing them from the organization stops their connections and keys on the next call.

Owners and admins see every connection in the organization; members see their own. The page also lists each connection's recent tool calls, and changes made through an agent show in your audit log as made "via" that client.

Troubleshooting#

Sign-in loops, or 401 errors#

The connection was disconnected, or its sign-in expired. Reconnect from your client (see below) and finish the consent page; closing it early leaves the client without a token.

No tools, or only reading tools#

The connection can only read. Either "Make changes" was off when you connected, or your role in that organization is Member. Reconnect and allow changes, or ask an owner to change your role.

The wrong organization#

A connection stays with the organization picked when it was made. Disconnect, connect again and pick the other one.

A change didn't happen#

Confirmation tokens last 10 minutes and work once, with the same arguments. Ask your agent to make the change again, and say yes to the new preview.

Reconnecting in each client#