Skip to main content
WebMCP tools live in your embedded page, so Ola can use them only while the merchant has your app open. If your app has a backend, you can also host a remote MCP server. Ola connects to it whenever a merchant who installed your app chats with her, and in scheduled tasks too. Your server speaks the standard Model Context Protocol over the Streamable HTTP transport, so any MCP server SDK works.

How a call flows

  1. You set an MCP server URL in the developer editor (Production and Development tabs, like the webhook URL).
  2. When a merchant of a store that has your app installed sends Ola a message, Salesive calls your server: initialize, then tools/list.
  3. Your tools appear to Ola beside her own, named after your app.
  4. When Ola wants one, the merchant sees the same approval card as for WebMCP tools, with Approve, Reject and Always allow.
  5. On approval, Salesive sends tools/call to your server and passes the result back to Ola. The card shows the outcome.
Every request carries a session token that tells you which store and which merchant it is for.

Verifying the session token

Each request to your server has an Authorization: Bearer <token> header. The token is a JWT signed ES256 by Salesive, with the same key and the same claims as the session tokens your embedded page gets from getSessionToken(). Verify it against Salesive’s public keys at https://api.salesive.com/api/v1/oauth/jwks, using the key whose kid matches the token header. No secret is involved, so it works whether or not your app has a webhook secret.
The session tokens page has a version with no dependencies, and the app starter’s server/sessionToken.js does the same checks: call verifySessionToken(token, { purpose: "mcp" }). Then look the shop up in your own install table and use the API token you stored for it at install time. Answer 401 when the token is missing or wrong.
Only accept ES256, and always check aud and purpose. Salesive signs tokens for every app with the same key, so without the aud check another app’s token would pass, and a dashboard session token (purpose: "session") must not be accepted by your MCP server. Never trust a shop header or a tool argument to tell you which store a call is for: use the shop claim.

A minimal server

Approval and channels without a screen

In the dashboard chat, every call needs the merchant’s approval unless they chose Always allow for that tool. The grant is per store installation. Ola also runs where nobody can click a card, such as scheduled tasks. There she only sees tools the merchant marked Always allow, and tools you annotate readOnlyHint: true (and not destructiveHint: true). Those run without asking.
Mark a tool readOnlyHint only if it changes nothing. A tool that writes data while claiming to be read only will get your app removed from the marketplace.
Workflow AI steps never get app tools.

Limits

Tool lists are cached for about five minutes, so a new tool can take that long to appear. A server that fails to answer is skipped for a minute. Each call opens a fresh MCP session, so a stateless server is the simplest fit.

Security model

  • The token says which store and merchant a request is for, and expires in five minutes. Verify it on every request.
  • Salesive never puts your URL, token or secret in front of the model.
  • Your tool results reach Ola marked as untrusted third-party data. Ola will not follow instructions written inside them.
  • A merchant can uninstall your app at any time. From then on Salesive stops calling your server for that store within about 30 seconds, and you should reject tokens for stores you no longer have.

Testing

On the Development tab, set your local URL (for example http://localhost:3000/mcp). Your own test installs use it, and their tokens say env: "development". Salesive’s hosted Ola cannot reach your machine, so use a public tunnel (for example cloudflared or ngrok) with an https address while you test against the real dashboard.

Next steps

WebMCP tools

Tools that run inside your embedded page.

Session tokens

The same key and claims, for requests from your embedded page.