Present Agent MCP

Find 5 explainable, personalized gift recommendations from inside any MCP client — Claude Code, Codex, Cursor, and more.

Current status and split guidance: docs/STATUS.md.

Present Agent is a gifting engine that reasons about the relationship, occasion, and the signal a gift sends — not just product search. This package is the public, hosted MCP server: it calls the live Present Agent API at presentagent.vip, so you need no local product catalog, no Shopify credentials, and no model-provider API keys to get value.

• 🎁 5 curated picks, each with a plain-language reason it fits

• 🔌 Works in any MCP-capable client over stdio

• 🔒 Hosted by default — zero secrets to configure

• 🌐 Every result includes a shareable web URL you can open or continue in the browser

Full docs & client catalog: https://presentagent.vip/mcp

Quickstart

Claude Code

claude mcp add present-agent --transport stdio --scope user \
  -e PRESENT_AGENT_CLIENT=claude-code \
  -- npx -y present-agent-mcp

Then ask Claude, in any project:

Find a gift for my sister's birthday under $100. She just got into pottery.

Codex

One command writes the config to ~/.codex/config.toml:

npx -y present-agent-mcp setup codex

Use --dry-run to preview without writing, or --local-context to enable opt-in local context (see Local context mode). Restart Codex, then ask for a gift.

Any other MCP client (generic stdio config)

{
  "mcpServers": {
    "present-agent": {
      "command": "npx",
      "args": ["-y", "present-agent-mcp"],
      "env": { "PRESENT_AGENT_CLIENT": "custom" }
    }
  }
}

Requirements: Node.js ≥ 18 and network access to https://presentagent.vip. The first run downloads the package via npx; subsequent runs are cached.

Related MCP server: Gift Mate

Tools

present_find_gift

Find 5 personalized gifts through the hosted Present Agent API. Only recipient is required — every other field sharpens the picks but is optional.

Returns (JSON text):

{
  "mode": "hosted",
  "apiBase": "https://presentagent.vip",
  "sessionId": "51bd7b67-…",
  "picksUrl": "https://presentagent.vip/picks/51bd7b67-…",
  "contextSignals": { "hosted": { "sources": ["explicit input"] } },
  "recommendations": [
    {
      "slot": "top_pick",
      "name": "White — Sage Valley Pottery Pie Dish",
      "brand": "PRINTFRESH",
      "price": 60,
      "matchScore": 0.5,
      "whyThisFits": "Combines her love of pottery with practical kitchen artistry…",
      "giftAngle": "Present it as functional art she'll use regularly."
    }
  ]
}

picksUrl is a real, shareable page — open it, send it, or continue refining in the browser.

present_beta_start

Zero-argument tool that returns the fastest onboarding instructions, a live web fallback (/gift/new), and the local-context opt-in hint. Useful as a first call to orient a fresh agent.

How to get the best picks

The engine reasons from context. The more specific, true signal you give it, the better the 5 picks — but don't invent detail.

Do

• Name a concrete interest or recent change ("just got into pottery", "started trail running"). Specifics beat adjectives.

• State the relationship and occasion — they change what a gift signals.

• Put genuine hard limits in constraints ("no alcohol", "ships to Canada by Dec 20", "nut allergy"). Constraints are respected before scoring.

• Pass through real memory in giver_context / recipient_context when your host AI already knows it.

Don't

• Fabricate interests or budgets to "fill the form" — empty is better than wrong; the model treats blanks honestly.

• Expect it to read minds: "something nice" with no other signal yields generic picks.

• Use it to search a specific SKU — it recommends what to give, it isn't a product-lookup tool.

Good call:

present_find_gift({ recipient: "my dad", relationship: "parent", occasion: "birthday", budget: "$80-120", interests: "gardening, espresso, jazz vinyl", constraints: "no clothing, he's hard to surprise" })

What's feasible (and what isn't)

Practical notes

• Latency: a fresh recommendation runs live LLM scoring and typically takes ~20–60s. Repeat/cached contexts are faster.

• Currency: all prices are CAD.

• Checkout: to buy, open picksUrl and continue on presentagent.vip → secure Shopify checkout. The MCP never hands users to external retailers.

• Determinism: picks are personalized and may vary slightly run-to-run as context changes.

Local context mode (opt-in)

By default the hosted server uses only what you pass in the tool call. Nothing local is read.

To let it look at local Claude/Codex/Gemini context files for soft signals about the named recipient, both must be true:

1. Set PRESENT_ENABLE_LOCAL_AGENT_CONTEXT=1 in the server env, and

2. Pass useAgentContext: true on the tool call.

When enabled, the server extracts compact preference / need / constraint hints and sends them as weak signals (never hard requirements). Secret-looking lines and paths are skipped — raw files are never transmitted. These hints are clearly labeled in the request and treated as low-confidence flavour, behind anything you state explicitly.

Configuration

All environment variables are optional — the package runs with safe defaults and no secrets. See .env.example.

Privacy

• No keys, no accounts required to use the hosted tools.

• The server sends only the gift context you provide to presentagent.vip.

• Local context search is off by default, double-gated, sanitized, and never transmits raw files or secret-looking content.

• Requests carry an attribution label (source: "mcp", your PRESENT_AGENT_CLIENT) for analytics — no personal identifiers are added by this package.

Troubleshooting

Run from source

git clone https://github.com/GuillaumeRacine/present-agent-mcp
cd present-agent-mcp
npm install
npm start            # boots the stdio MCP server

License

MIT © Present Agent. See LICENSE.