# Refindi AI - public MCP server for lost-item recovery

> Refindi helps guests recover items left at hotels and other venues. This MCP server lets an AI agent explain the service, find the right venue in the public catalogue, prepare a claim (what / where / when / contact) and hand the user a link to the existing Refindi form. The user completes the claim, gives contact details, accepts the terms and pays for shipping later on refindi.com. The server is read-only and public.

Documentation: https://ai.refindi.com/
MCP endpoint: https://ai.refindi.com/mcp
Health: https://ai.refindi.com/health
Website: https://refindi.com/
Privacy policy: https://refindi.com/pl/privacy-policy (EN: https://refindi.com/en/privacy-policy)
Service terms: https://refindi.com/pl/regulamin-serwisu (EN: https://refindi.com/en/service-terms)
Contact: https://refindi.com/pl/kontakt, info@refindi.com

## Connection

- Transport: MCP Streamable HTTP (JSON-RPC over HTTPS POST to /mcp). Stateless; each POST gets a single JSON response.
- Authentication: none for the public read-only tools.
- Protocol: `initialize` returns `instructions` for the agent; `tools/list` returns names, descriptions, input and output schemas; `tools/call` runs a tool.
- Headers: `Content-Type: application/json`, `Accept: application/json, text/event-stream`. Browser clients must send an allowed `Origin`; non-browser clients need no `Origin`.
- Limits: request body up to 64 KB, at most 10 results per search, about 120 requests per minute per client address (HTTP 429 with `Retry-After`).

Client configuration examples:

Generic JSON (Cursor, Windsurf, most desktop clients):
```json
{ "mcpServers": { "refindi": { "type": "http", "url": "https://ai.refindi.com/mcp" } } }
```

Claude Code:
```
claude mcp add --transport http refindi https://ai.refindi.com/mcp
```

Claude.ai / Claude Desktop: Settings -> Connectors -> Add custom connector -> URL `https://ai.refindi.com/mcp` (no authentication).

ChatGPT (developer mode / custom connector): add an MCP server with URL `https://ai.refindi.com/mcp`, no authentication.

Raw check with curl:
```
curl -s https://ai.refindi.com/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
```

## Tools

All tools are read-only (`readOnlyHint: true`, `idempotentHint: true`, no side effects). Every response has `structuredContent` plus a readable `summary`, a `locale` block (`requested`, `content_language`, `link_language`, `fallback`) and a `data` block with `source` and `updated_at`. Errors are returned as tool errors whose text starts with a code: `invalid_input`, `location_not_found`, `temporarily_unavailable`.

### get_service_info(locale?)
Explains how Refindi works: steps, what the user must prepare, public rules on costs (no amounts - the shipping quote is made in the process), delivery, items that cannot be shipped, what happens when nothing is found, limits of this server, supported languages, links to source pages.

### search_locations(query, city?, country?, limit?, locale?)
Finds hotels and other venues in the public catalogue by name - not lost items.
- `query` (string, 2-200 chars): venue name as the user said it, e.g. "Hotel Bristol".
- `city` (string, optional): city filter, e.g. "Warszawa".
- `country` (string, optional): ISO 3166-1 alpha-2 or country name, e.g. "PL".
- `limit` (integer 1-10, default 5).
- Returns `matches[]` with `location_id`, `name`, `city`, `address`, `country`, `kind` (hotel | place | non_partner), `partner`, `location_type`, `claim_start_url`; plus `match_type` (name | city | none), `ambiguous`, `truncated`, `general_claim_url`.
- When `ambiguous` is true, show the candidates and ask the user to choose. No match does not mean the item was not found.

### get_location_details(location_id, locale?)
Public details of one venue (name, address, kind, partner flag) and `how_to_start`. `location_id` must come from `search_locations`. Returns no found items, staff or guest data.

### get_claim_instructions(location_id?, item_category?, locale?)
Checklist of what to collect (`item`, `place`, `when`, `contact`, `delivery_country`), guidance when the user does not remember the venue, and `item_rule` for the given item based on the current Refindi dictionary: `excluded` (cannot be shipped, e.g. passports, cash, insulin), `manual_verification`, `declaration_of_value`, `needs_clarification` (generic word with excluded variants), `no_specific_rule`, `unavailable` (rules could not be checked - do not guess), `not_checked` (no item given).

### get_claim_start_link(location_id?, locale?)
Canonical link to the existing Refindi claim form with the message "Open the link to fill in and send the claim". With a partner hotel's `location_id` the form opens with that venue preselected (`link_type: venue_form`); otherwise the general wizard is returned (`link_type: general_wizard`). It creates nothing, sends no notifications and books no courier. The URL carries no personal data.

## Recommended order

1. `get_service_info` when the user asks what Refindi is or how it works.
2. `search_locations` with the venue name and city. One match: confirm it with the user. Several: let the user choose. None: continue with the general link.
3. `get_claim_instructions` to collect what / where / when / contact and to check special items.
4. `get_claim_start_link` and hand over the link. The user fills in and sends the claim on refindi.com.

Example: "I left black headphones at Hotel Bristol in Warsaw yesterday" -> `search_locations(query="Hotel Bristol", city="Warszawa", locale="en")` -> confirm the candidate -> `get_claim_instructions(location_id=..., item_category="headphones", locale="en")` -> `get_claim_start_link(location_id=..., locale="en")`.

## Languages

- `locale` is a BCP 47 tag ("pl", "en", "de-DE", "nb-NO"...).
- Texts are available in Polish and English; other locales receive English and `locale.fallback: true`.
- Links are returned in the matching site language for the 22 languages of refindi.com (pl, en, de, fr, es, it, nl, pt, no, sv, cs, ar, ja, he, tr, et, lv, lt, sk, hu, fi, da).
- The item dictionary used by `get_claim_instructions` is Polish; English item names usually return `no_specific_rule` with a general caution about documents, cash, weapons and narcotics.

## Data and freshness

- Venue catalogue: public projection of Refindi partner venues (hotels, other partner places) and the non-partner venue register, refreshed about every 10 minutes. Responses carry `data.updated_at`, `data.data_version` and `data.stale` (true when the catalogue could not be refreshed for over an hour). `/health` shows the same status.
- Item rules: the public Refindi item dictionary (`version`, `updated_at` in `item_rule.rules`), refreshed hourly.
- Service texts: written from the public Refindi pages; `data.updated_at` gives the content date.

## Privacy and scope

- Only public venue data and public service rules are served. No found-item inventory, photos, ownership details, guest data, room numbers, private case status or payments.
- Knowing a case id does not grant access to a case; case status is available only through the links in Refindi e-mails.
- No anonymous creation of claims, payments or shipments. The server has no write operations.
- Analytics: tool name, status, error code, duration, result count, data version and locale are logged. Search text, item descriptions, contact data and request bodies are not logged.

## Rules for agents

- Never say an item was found or a claim was submitted; this server cannot know that.
- Do not invent prices, delivery times or guarantees; cite the linked pages.
- Put no personal data or item descriptions into URLs.
- Ask the user to choose when several venues match.