Present Agent

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.

---

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.

Parameter	Type	Description
recipient	string · required	Name or short description of who the gift is for.
relationship	string	partner, parent, sibling, friend, colleague, client, etc.
occasion	string	birthday, anniversary, thank-you, housewarming, onboarding, holiday…
budget	string	Free-form: "$50-100", "under $75", "$150 CAD". Prices are CAD.
interests	string	Comma-separated interests, hobbies, brands, or taste signals.
preferences	string	Known likes, style, taste, or profile clues.
constraints	string	Hard rules: avoid categories, delivery deadline, allergies, space, values.
needs	string	Functional needs or outcomes the gift should support.
giver_context	string	What you (the host AI) know about the giver: budget norms, taste, taboos, prior gifts. Leave empty if unknown — never fabricate.
recipient_context	string	What you know about the recipient beyond name/relation/occasion: life events, prior gift outcomes, recent notes. Leave empty if unknown — never fabricate.
useAgentContext	boolean	Opt in to local context search. Also requires PRESENT_ENABLE_LOCAL_AGENT_CONTEXT=1. Default false.

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)

✅ Feasible	❌ Not in this MCP
5 explainable gift picks for a person + occasion	Completing a purchase / checkout (happens on the web, link provided)
Budget, hard constraints, and taste honored	Real-time inventory or per-item shipping quotes (confirmed at checkout)
A shareable picksUrl for every result	Editing a saved recipient profile or wishlist (web/app feature)
Optional, opt-in local context hints	Reading your full local files (only sanitized, opt-in signals are sent)
Works offline-of-keys: no model/Shopify keys needed	Running the full local catalog engine (that's the private app repo)

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.

Variable	Default	Purpose
PRESENT_AGENT_CLIENT	unknown	Client label for attribution (e.g. claude-code, codex).
PRESENT_AGENT_API_BASE	https://presentagent.vip	API base. Change only if self-hosting Present Agent.
PRESENT_ENABLE_LOCAL_AGENT_CONTEXT	unset (off)	Allow opt-in local context search (still needs useAgentContext=true).
PRESENT_EXPOSE_LOCAL_AGENT_CONTEXT_LINES	unset (off)	Echo extracted local lines in the response (debug only).

---

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

Symptom	Fix
failed to start / command not found	Ensure Node.js ≥ 18 and that npx can reach the network on first run.
Tool call times out	Recommendations can take up to ~60s; raise your client's MCP tool timeout.
Empty / generic picks	Add a concrete interest + relationship + occasion; avoid vague input.
Want to preview Codex config	npx -y present-agent-mcp setup codex --dry-run

---

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.