Claimify MCP

What this is

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.

Claimify exposes the same data as this API over MCP at https://api-staging.sappo.xco.agency/claimify/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-staging.sappo.xco.agency/claimify/docs/mcp.json.

Connect

Endpoint	`https://api-staging.sappo.xco.agency/claimify/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`

Claude Code, Cursor and other config-file clients

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-claimify": {
            "type": "http",
            "url": "https://api-staging.sappo.xco.agency/claimify/mcp",
            "headers": {
                "Authorization": "Bearer mak_your_token_here"
            }
        }
    }
}

From the command line

claude mcp add --transport http sappo-claimify https://api-staging.sappo.xco.agency/claimify/mcp --header "Authorization: Bearer mak_your_token_here"

Claude Desktop

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.

Any other MCP client

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.

What the assistant is told

The server sends these instructions to the client when it connects, so the assistant knows what it can do before it calls anything:

Claimify MCP server for accessing claim data from Shopify stores.

The store is identified automatically from your API token.

Available tools:
- `list_claims`: List claims with optional status/archived filters and pagination
- `get_claim`: Get a specific claim by ID with customer, order, and line item details
- `get_claim_stats`: Get claim statistics broken down by status
- `list_customers`: List customers with pagination
- `list_orders`: List orders with optional cancelled filter and pagination

Tools

5 tools, read from the server itself. Every tool reads; none of them changes your data.

list_claims

List claims for a Shopify store. Returns paginated claims with customer, order, and line item details.

Argument	Type	Description
`page`	`integer`	Page number (default: 1)
`page_size`	`integer`	Items per page, max 100 (default: 25)
`status`	`string`	Filter by status (PENDING, APPROVED, REJECTED, etc.)
`archived`	`boolean`	Filter by archived state

get_claim

Get a single claim by ID for a Shopify store, including full customer, order, and line item details.

Argument	Type	Description
`id` required	`string`	Claim ID

get_claim_stats

Get claim statistics for a Shopify store: total count broken down by status, and counts for archived/active claims.

Takes no arguments.

list_customers

List customers for a Shopify store using Claimify.

Argument	Type	Description
`page`	`integer`	Page number (default: 1)
`page_size`	`integer`	Items per page, max 100 (default: 25)

list_orders

List orders for a Shopify store using Claimify.

Argument	Type	Description
`page`	`integer`	Page number (default: 1)
`page_size`	`integer`	Items per page, max 100 (default: 25)
`cancelled`	`boolean`	Filter by cancelled status

Try it

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 claims.	`list_claims`
Give me the details of a claim.	`get_claim`
Give me the details of the claim stats.	`get_claim_stats`
Show me the customers.	`list_customers`
Show me the orders.	`list_orders`

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 Claimify tools” and ask again.

When a tool fails

Status	Code	What to do
401	`MISSING_TOKEN`	Send an `Authorization: Bearer mak_…` header. This code also appears when the header is present but does not start with `Bearer` — a bare token or a `Token …` prefix is not accepted.
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 `Retry-After` header before retrying, and keep each client under 60 requests per 60 seconds. Fetch more records per request instead of making more requests.
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.