# MCP server for refunds: connect your AI assistant

> Connect an AI assistant or your own agent to your refund workspace through the Model Context Protocol. Read cases and propose actions, never move money.

- Canonical URL: https://lumtry.com/developers/mcp
- Last updated: 2026-09-24

- 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

## 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.

## 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.

Off by default. They need the External Agent Access add-on (bundled in Scale) and are turned on for your workspace on request.

Proposal tools are in preview, so treat every result as a draft to review, never a settled answer.

- Your cases, filtered and paged.
- One case with its state, amounts and items.
- The ordered timeline of a case.
- The evidence sections gathered for a dispute.
- Messages exchanged with the shopper.
- The text of the policy version that applied.
- A summary of the shopper's prior transactions.
- Proposes opening a new case.
- Proposes cancelling a case.
- Proposes dispute evidence for review.
- Proposes a decision with a rationale, confidence and citations.

## 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.
- Read cases, timelines and evidence.
- Propose starting or cancelling a case.
- Propose evidence and decisions.

## Connect in three steps.

Replace api-host with your Lumtry API host and keep the key out of shared files.

- **Create a workspace API key**: Create a key in the dashboard under API and webhooks and pick its scopes. Start with read.
- **Add Lumtry to your client**: The server speaks MCP over streamable HTTP at the /mcp path of your API host. Pick your client below.
- **Ask about your refunds**: Try: which approvals are older than a day, or why order 10442 is waiting.

## 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.

## 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.

#### 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.

## Related

- [Home](https://lumtry.com/index.md): Decide refunds by a versioned policy, send the exceptions to your team in Slack or the dashboard, and keep every step on the record. Start free.
- [Developers](https://lumtry.com/developers.md): Send signed refund webhooks to your tools, call the REST API and let your AI assistant work with Lumtry cases over MCP. Explore the developer tools.
- [Pricing](https://lumtry.com/pricing.md): Lumtry plans by case volume and seats, from Free to Enterprise, with add-ons and capped outcome fees. Start free or hear when billing opens.
- [Trust](https://lumtry.com/trust.md): How Lumtry secures merchant data, keeps AI inside a deterministic refund policy, lists every sub-processor and explains data flow and retention. Review it.
- [llms.txt](https://lumtry.com/llms.txt)