Model Context Protocol
Let an assistant find and send the gift
GiftRoam exposes a small, tool-only MCP server at mcp-stage.giftroam.com. Claude, ChatGPT and any MCP client can search the catalog, check delivery to a country and date, and hand the user a secure checkout link. The assistant never collects an address and never charges a card — the human confirms and pays on this site.
Zero PII in the conversation
The tool schemas have no name, street, phone or email fields. The chat only carries product, country, date and an optional gift message.
Signed, short-lived links
create_checkout returns a single-purpose URL that expires in 30 minutes and can be revoked. All details and payment happen on checkout.giftroam.com.
Status by token only
After payment the buyer receives an order token. get_order_status accepts only that token and returns coarse, PII-free status.
Tools
| Tool | Input | Output |
|---|---|---|
| search_gifts | country, query?, occasion?, budget_min/max?, limit, cursor | Shortlist with price, delivery days, image, tags |
| get_gift_details | gift_id, country | Full description, contents, delivery window, restrictions |
| check_delivery | country, city?, date_needed?, gift_id? | Feasible? earliest/latest, warnings (PO Box, hotel, holidays) |
| create_checkout | gift_id, country, delivery_date?, gift_card_text?, idempotency_key | Signed 30-minute checkout URL + no-PII summary |
| get_order_status | order_token | Coarse status, ETA, next action — never address/phone/payment |
| list_my_orders | limit? (signed-in connection) | The user’s own orders with status + tokens — requires OAuth (orders:read) |
Interactive cards in chat
The server is also an MCP App: in ChatGPT, Claude and other hosts that render apps, results appear as gift cards with photos, final prices and delivery times; tapping a card opens the full details (gallery, what’s inside, delivery window), and “Send this gift” creates the secure checkout link right there — with a hand-off to this site for the address and payment. Order status and “my orders” render as a tracker. Hosts without app support get the same information as text.
Connect
Streamable HTTP, stateless, no session or API key required (guest mode). Public tools need no auth; get_order_status requires the buyer’s order token. Two resources — giftroam://countries and giftroam://occasions — list valid destinations and occasion slugs.
https://mcp-stage.giftroam.com/mcp
claude mcp add --transport http giftroam https://mcp-stage.giftroam.com/mcp
{
"mcpServers": {
"giftroam": { "type": "http", "url": "https://mcp-stage.giftroam.com/mcp" }
}
}Signed in (optional) — same URL
The endpoint above works for guests and, once the user links their GiftRoam account, also returns their own orders (list_my_orders). It speaks standard MCP authorization — OAuth 2.1 with PKCE and dynamic client registration, discovered from /.well-known/oauth-protected-resource — and declares per-tool securitySchemes, so clients such as ChatGPT can start anonymously and show “connect account” only when a signed-in tool is used. The user signs in on GiftRoam (email link), approves the orders:read scope, and can disconnect any time from My orders. The assistant still never sees addresses, phone numbers or payment details.
Clients that can only do authorization at connect time can use https://mcp-stage.giftroam.com/mcp/account instead — identical tools, sign-in required up front.
In claude.ai: Settings → Connectors → Add custom connector → paste the endpoint URL. The same operations are also available as plain JSON at /api/v1 (search, gift details, delivery check, checkout, order status) — both share this site’s order engine.