Connect an AI assistant directly to your Floaty data.
The Model Context Protocol (MCP) is an open standard that lets an AI assistant call tools on a server instead of guessing from text: you connect the assistant once, it discovers which tools exist, and then it can answer "how many claims are still pending?" by actually querying your store rather than inventing a number. Claude Desktop, Claude Code and a growing list of other clients speak it.
Floaty exposes the same data as this API over MCP at https://api.sappo.xco.agency/floaty/mcp,
authenticated with the same mak_ token in the same
Authorization header. No separate signup, no second credential.
The tool list, the exact client configuration to paste, and the errors to
expect are on the MCP guide, with a
machine-readable copy at
https://api.sappo.xco.agency/floaty/docs/mcp.json.
| Endpoint | https://api.sappo.xco.agency/floaty/mcp |
|---|---|
| Transport | Streamable HTTP (POST) |
| Header | Authorization: Bearer mak_… |
| Token | Open the app in your Shopify admin, go to Settings → API Access, and create a token. The full token is shown once, at creation time; afterwards only its first 12 characters are stored in readable form. If that card is locked, API access is not included in your current plan and the app will not create a token until the plan changes. At most three tokens can be active at once, so revoke one you no longer use before creating another. |
| Protocol versions | 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 |
Add this to the client's MCP configuration file — .mcp.json for
Claude Code — replacing the placeholder with the token you created in the app:
{
"mcpServers": {
"sappo-floaty": {
"type": "http",
"url": "https://api.sappo.xco.agency/floaty/mcp",
"headers": {
"Authorization": "Bearer mak_your_token_here"
}
}
}
}claude mcp add --transport http sappo-floaty https://api.sappo.xco.agency/floaty/mcp --header "Authorization: Bearer mak_your_token_here"Claude Desktop adds a remote server under Settings → Connectors → Add custom connector rather than from a configuration file, and it authenticates through the server's own flow instead of a header you type. This endpoint expects the Bearer token above, so use a client that lets you set the header: Claude Code, Cursor, or any client with a configuration file.
Point it at the endpoint above as a streamable-HTTP MCP server and have it send
the Authorization header on every request. The store is
identified from the token, so there is nothing else to configure.
The server sends these instructions to the client when it connects, so the assistant knows what it can do before it calls anything:
Buttons and click analytics for the authenticated shop.
The store is identified automatically from your API token.
Available tools:
- `list_buttons`: List floating buttons
- `get_button`: Get one button by id
- `list_analytics`: List button clicks
Every `list_` tool takes `page` and `page_size` (25 by default, 100 at most) and
returns the page plus `meta.total`. Every `get_` tool takes the record `id`.
Everything is read-only: changes are made in the app, never through this server.3 tools, read from the server itself. Every tool reads; none of them changes your data.
List floating buttons for the authenticated shop.
| Argument | Type | Description |
|---|---|---|
page
|
integer |
Page number, starting at 1 |
page_size
|
integer |
Page size, maximum 100 |
Get one button by id for the authenticated shop.
| Argument | Type | Description |
|---|---|---|
id
required |
string |
Record id |
List button clicks for the authenticated shop.
| Argument | Type | Description |
|---|---|---|
page
|
integer |
Page number, starting at 1 |
page_size
|
integer |
Page size, maximum 100 |
Once the server is connected, you do not call these tools yourself — you ask in words and the assistant picks the tool. Each row below is a question that reaches the tool beside it, so you can check the connection works and see the shape of an answer.
| Ask | Tool it reaches |
|---|---|
| Show me the buttons. | list_buttons |
| Give me the details of a button. | get_button |
| Show me the analytics. | list_analytics |
The assistant reads the store from your token, so none of these needs a shop name in it. If it answers without calling a tool, it is guessing: say “use the Floaty tools” and ask again.
| Status | Code | What to do |
|---|---|---|
| 401 | MISSING_TOKEN |
Send an |
| 401 | INVALID_TOKEN |
Check the token was copied in full, is still listed as active in Settings → API Access, and has not passed its expiry date. Create a new token if in doubt. The same code is returned when the store is suspended. |
| 403 | PLAN_REQUIRED |
The token is valid, but this app sells API access on named plans only and this store is not on one of them. The plans that carry it are listed under Authentication above; change the plan in the app and the same token starts working — there is no need to create a new one. |
| 404 | APP_NOT_FOUND |
The app handle in the path is not one Sappo serves. Use the handle this documentation was generated for, and check for a typo or a stray path segment. |
| 429 | RATE_LIMITED |
Wait the number of seconds in the |
| 503 | API_NOT_AVAILABLE |
The app is served but its store of API tokens has not been created yet, so no token can be checked. Nothing is wrong with your request: retry later, and tell support if it lasts. |
The MCP endpoint also has its own rate limit, separate from the REST API's
per-token budget: 60 requests per
60 seconds per
client address. Over it, the endpoint answers 429
with Too Many Attempts. — Laravel's own throttle
response, not the API error envelope, so it carries no error.code —
and the headers
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.
An assistant that reports a tool "not found" is usually connected to the wrong app's endpoint. Compare the tool name it tried against the list above.