MCP server
Your AI assistant, on your refund desk.
Ask Claude, Cursor or any MCP client about your refunds in plain words. It reads your cases and evidence, and when you allow it, proposes decisions that land in your approval queue.
- Streamable HTTP, JSON-RPC 2.0
- Protocol versions 2025-11-25 and 2026-07-28
- 10 second budget per call
- 11 tools, verified at startup
For merchants
What it does for your team.
Ask, do not dig
Which cases are waiting, what the shopper said, which policy version applied. Answers come from your workspace, not a guess.
Proposals, not actions
Write tools only propose. Every proposal waits in your approval queue for a person.
On the record
Proposals and the human decisions on them go into the same audit trail as every other case.
Tools
Eleven tools, seven of them read-only.
Read tools are on for every workspace API key. Proposal tools stay off until they are turned on for your workspace.
Read tools
| Tool | What it returns |
|---|---|
list_cases | Your cases, filtered and paged. |
get_case | One case with its state, amounts and items. |
dispute.case_timeline | The ordered timeline of a case. |
dispute.evidence_sections | The evidence sections gathered for a dispute. |
dispute.shopper_communications | Messages exchanged with the shopper. |
dispute.policy_version_text | The text of the policy version that applied. |
dispute.prior_transaction_summary | A summary of the shopper's prior transactions. |
Proposal tools
Off by default. They need the External Agent Access add-on (bundled in Scale) and are turned on for your workspace on request.
| Tool | What it returns |
|---|---|
start_case | Proposes opening a new case. |
cancel_case | Proposes cancelling a case. |
submit_evidence | Proposes dispute evidence for review. |
propose_decision | Proposes a decision with a rationale, confidence and citations. |
Access
Your key, your scopes.
Workspace API key
Send it as a bearer token. The key is scoped to one workspace, and effective rate limits are the lower of the key's and your plan's.
OAuth 2.1
Sign in from the client with PKCE (S256), no key to copy. Access tokens last 1 hour, refresh tokens 30 days. Client credentials are not accepted.
| Scope | Grants |
|---|---|
read | Read cases, timelines and evidence. |
intake | Propose starting or cancelling a case. |
approvals | Propose evidence and decisions. |
Setup
Connect in three steps.
01
Create a workspace API key
Create a key in the dashboard under API and webhooks and pick its scopes. Start with read.
02
Add Lumtry to your client
The server speaks MCP over streamable HTTP at the /mcp path of your API host. Pick your client below.
03
Ask about your refunds
Try: which approvals are older than a day, or why order 10442 is waiting.
Replace api-host with your Lumtry API host and keep the key out of shared files.
claude mcp add --transport http lumtry https://<api-host>/mcp \
--header "Authorization: Bearer eqk_live_…"{
"mcpServers": {
"lumtry": {
"url": "https://<api-host>/mcp",
"headers": { "Authorization": "Bearer ${env:LUMTRY_API_KEY}" }
}
}
}{
"mcpServers": {
"lumtry": {
"command": "npx",
"args": ["mcp-remote", "https://<api-host>/mcp", "--header", "Authorization:${LUMTRY_AUTH}"],
"env": { "LUMTRY_AUTH": "Bearer eqk_live_…" }
}
}
}POST /mcp
Authorization: Bearer eqk_live_…
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "propose_decision",
"arguments": {
"refund_case_id": "01J9Z3K4M8Q2V6X0B5N7T1R3Y8",
"recommended_decision": "manual_review",
"rationale": "Carrier scan shows delivery; photo shows damage.",
"confidence": 0.72,
"citations": ["dispute.evidence_sections#delivery"]
},
"_meta": { "idempotencyKey": "prop-10442-1" }
}
}Guardrails
What your agent can never do.
Move money on its own
There is no autonomous decision channel. A person approves every proposal.
Change where a refund goes
An agent can never set a refund destination or override an amount.
Mark a refund complete
Completion only comes from the workflow after a real processor result.
Skip your rules
Proposals still pass your pinned policy and your approval queue.
Questions
MCP questions, answered.
Can an assistant refund a customer by itself?
No. Read tools only read. Proposal tools put a proposal in your approval queue, and a person decides.
Which assistants work?
Any client that speaks MCP over streamable HTTP, including Claude Code, Cursor and Claude Desktop through a bridge.
Do I need OAuth?
No. A workspace API key works as a bearer token. OAuth 2.1 sign-in is available on request.
How do I turn on proposal tools?
They need the External Agent Access add-on, bundled in Scale, and are turned on for your workspace on request. Until then only the seven read tools exist.
Are there rate limits?
Yes. The effective limit is the lower of your key's limit and your plan's ceiling.
What can it see?
Only the workspace the key or token belongs to, within the scopes you granted.
Give your assistant a seat at the refund desk.
Start free, create a key, and connect in minutes. Ask us to turn on proposal tools when you are ready.