How a call flows
- You set an MCP server URL in the developer editor (Production and Development tabs, like the webhook URL).
- When a merchant of a store that has your app installed sends Ola a message,
Salesive calls your server:
initialize, thentools/list. - Your tools appear to Ola beside her own, named after your app.
- When Ola wants one, the merchant sees the same approval card as for WebMCP tools, with Approve, Reject and Always allow.
- On approval, Salesive sends
tools/callto your server and passes the result back to Ola. The card shows the outcome.
Verifying the session token
Each request to your server has anAuthorization: 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.
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.
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 annotatereadOnlyHint: true (and not destructiveHint: true). Those run without
asking.
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 examplehttp://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.

