For AI Agents

Bring real gift ideas into your AI chat

Surprise Buddy hosts a public Model Context Protocol server so any AI agent — Claude, ChatGPT, your own SDK app — can search a curated, country-scoped gift database and return ready-to-click product cards.

Quickstart Read SKILL.md

No authentication · JSON-RPC 2.0 over HTTP · Free to use

What you get

Every result is a real product on a real marketplace, with our affiliate referral baked into the URL — pass it straight to the user.

Curated, not generated

Every gift is a verified product page — no hallucinated URLs. Re-verified weekly.

Country-scoped

Country is a hard filter. Results respect the local marketplace and currency — no US Amazon links for a German user.

Card-ready output

Each hit ships with title, image, price, why-it-fits and product URL. Render the card and you're done.

Discovery & reference

All resources are public and statically hosted — link to them directly from your own agent skill, plugin manifest, or docs.

SKILL.md

Agent-facing instructions: tools, parameters, rendering guidance.

openapi.yaml

OpenAPI 3.1 spec for OpenAI Custom GPT Actions and other non-MCP clients.

.well-known/mcp.json

MCP discovery manifest — endpoint, transport, auth.

llms.txt

Site map for LLM crawlers — pages, content scope, MCP pointers.

Five tools, one endpoint

All calls go to https://www.surprise-buddy.com/api/mcp as JSON-RPC 2.0.

find_gifts

Main search. country is required and is a hard filter. Optional: occasion, age, gender, budget range, interests, profession, limit.

{ country: "DE", age: 31, gender: "female", interests: ["wellness"] }

list_supported_countries

Returns ISO-2 codes of countries with active gift entries.

{}

list_supported_occasions

Returns occasion codes with active entries (optionally per country).

{ country: "DE" }

list_supported_interests

Returns the canonical interest/hobby tag vocabulary used by find_gifts.

{}

list_supported_colors

Returns the canonical favorite-color vocabulary used by find_gifts.favorite_color.

{}

Quickstart

Pick the path that matches your client.

Plain HTTP / curl

The endpoint speaks JSON-RPC 2.0. Send a tools/call request and you'll get back a list of gift cards.

bash

curl -X POST https://www.surprise-buddy.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "find_gifts",
      "arguments": {
        "country": "DE",
        "occasion": "birthday",
        "age": 31,
        "gender": "female",
        "limit": 5
      }
    }
  }'

Claude Desktop / Claude.ai

Add the server to your claude_desktop_config.json or as a Claude.ai custom connector. Then ask: “Find a birthday gift for my 31-year-old girlfriend in Germany.”

json

{
  "mcpServers": {
    "surprise-buddy": {
      "url": "https://www.surprise-buddy.com/api/mcp"
    }
  }
}

ChatGPT Custom GPT

Import our OpenAPI 3.1 spec as a Custom GPT Action — no MCP support needed. Point the import to:

https://www.surprise-buddy.com/openapi.yaml

Building an agent that helps people pick gifts?

Let us know — we're happy to add countries, occasions, or interest tags that your users care about.

Get in touch