Skip to main content

Agent Tools (WebMCP)

The card element can register a WebMCP tool, enter_card, so a browser agent can fill in the card for the shopper. The tool runs inside the Basis Theory iframe: card data the agent sends goes from the browser to Basis Theory without passing through your page, and the tool returns only whether the card is complete, its brand, and its last four digits.

For a short integration guide, start with Accept Cards from Browser Agents. It covers both an existing Basis Theory checkout and an agent-only element beside another processor's shopper form. This page is the SDK/tool reference.

WebMCP is an experimental browser API. Chrome supports it behind the chrome://flags/#enable-webmcp-testing flag and through an origin trial. In browsers without WebMCP, agentTools does nothing.

Enabling agent tools​

Set agentTools: true when you create the card element.

const card = bt.createElement('card', { agentTools: true });
await card.mount('#card');
OptionTypeDefaultDescription
agentToolsbooleanfalseRegisters the enter_card tool inside the card iframe. Set it at creation: update({ agentTools: false }) removes the tool and true restores it, but update({ agentTools: true }) on a card created without it throws a ConfigurationError. The React CardElement recreates its element when the prop changes.

The enter_card tool​

enter_card takes the card as it is printed. Every field is optional, so an agent can resend only the field it needs to correct.

InputTypeDescription
numberstringCard number. Spaces are allowed.
expirationstringExpiration date, such as 12/30 or 12/2030.
cvcstringSecurity code.

The iframe writes the values into its inputs and runs the same handlers as typing, so formatting, validation, change events, and tokenization work the same way they do for a shopper. The tool returns the card's state and never the values it was given:

{ "complete": true, "brand": "Visa", "last4": "4242", "errors": [] }

When a field is invalid, complete is false and errors lists each problem with its field, code, and message. If the element is disabled or readOnly, the tool makes no changes and returns the error code CARD_INPUT_LOCKED. Calls run one at a time, so each result reflects only the values sent in that call.

Browser support​

A cross-origin iframe can register WebMCP tools only when the page grants it the tools permission. The SDK adds allow="payment *; tools" to the card iframe when agentTools is on and the browser supports the permission. In Chrome, the permission is part of the WebMCP origin trial; where the trial or flag is not enabled, the SDK leaves it out so Chrome does not log a console warning.

A page that sends Permissions-Policy: tools=() disables WebMCP for every frame, including the card iframe.

On an https page, enter_card is registered with exposedTo set to your page's origin. Agents that discover tools from the page, such as browser extensions or an agent embedded in your site, only see a cross-origin frame's tools when they are exposed this way. On an http page, such as a local development server, the tool is still registered but is visible only to the browser itself.

Security​

  • Card data an agent enters travels from the browser to the Basis Theory iframe. Your page's scripts never receive it, and the tool result contains only the completion state, brand, last four digits, and errors.
  • The agent handles the full card number when it calls enter_card, so the agent and its platform are responsible for how they store and transmit it.
  • Because the tool is exposed to your page's origin, scripts on your page can call enter_card too. They can only write card data they already have, and they receive the same masked result.

Testing​

Chrome DevTools has a WebMCP pane that lists a page's tools, runs them with parameters you enter, and logs each call.

  1. In Chrome, enable chrome://flags/#enable-webmcp-testing and chrome://flags/#devtools-webmcp-support, then relaunch.
  2. Open your checkout page, open DevTools, select the Application panel, and choose WebMCP in the sidebar.
  3. Under Available Tools, select enter_card, enter 4242424242424242 as the number, 12/30 as the expiration and 123 as the CVC, and click Run tool. The card fills, and your change handler sees isValid: true.
  4. Select your payment tool, such as submit_payment, and click Run tool. Under Invoked Tools, the call shows Completed and its output, and your page receives a token id or your processor's response.

Learn more​

Last updated on