AI Assistants

GiftWrapt is a Model Context Protocol server. Any MCP-capable assistant can connect to your deployment, sign in as you, and then add things to your lists, read the lists of people you shop for, claim gifts, keep track of what you have bought, and act on GiftWrapt’s own suggestions. There is nothing extra to install or host: the server is built into the app.

Turn It On

An admin enables the feature once per deployment:

Open Admin → General and turn on Enable MCP Server.
Open Admin → MCP. The page shows the server URL to hand to users, checks that the two discovery documents are reachable at your origin, and lists the clients that have registered and every active connection.

With the switch off, nothing related to assistants exists: the endpoint, the sign-in pages, the discovery documents, the admin page, and every connected assistant stop at once.

Connect an Assistant

Every client needs one thing: your deployment’s server URL, which is your site’s address followed by /api/mcp (for example https://gifts.example.com/api/mcp). You can copy it from Settings → Connected Apps at any time. The first time a client connects, it sends you to GiftWrapt to sign in (if you are not already) and to approve the connection.

In GiftWrapt, open Settings → Connected Apps and press Add to Claude. Claude opens with your deployment’s name and server URL already filled in; confirm, then finish the sign-in and consent in the browser window that opens. To do it by hand instead, open Settings → Connectors → Add custom connector in Claude and paste the server URL. The connector then shows up in every Claude chat, on the web, in the desktop app, and on mobile.

claude mcp add --transport http giftwrapt https://gifts.example.com/api/mcp

Then run /mcp inside Claude Code and sign in when prompted.

Add the server to the client’s MCP configuration as a URL entry:

{
  "mcpServers": {
    "giftwrapt": { "url": "https://gifts.example.com/api/mcp" }
  }
}

Clients that only run local (stdio) servers can bridge through mcp-remote, which handles the sign-in in your browser:

{
  "mcpServers": {
    "giftwrapt": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://gifts.example.com/api/mcp"]
    }
  }
}

When you approve a connection you choose what the assistant may do: Read and Make Changes (it can add items, claim gifts, and edit lists when you ask) or Read Only (it can answer questions but cannot change anything). You can switch an assistant between the two at any time under Settings → Connected Apps; the change applies to its next request.

You are asked to approve the connection every time a client starts a fresh sign-in. Once connected, a client stays signed in for 30 days of inactivity and refreshes itself while you keep using it.

What an Assistant Can Do

The assistant gets a set of tools that mirror the app. A few examples of what you can ask:

“Add this to my wishlist” with a product link. The page is read for the title, price, and image, exactly like pasting a link in the app.
“What’s on Mom’s list that nobody has claimed yet?” The assistant sees her list the way you would as a gifter, including what others already claimed and how many of each item remain.
“I bought the espresso machine for Sam with Kate.” The claim is recorded with Kate as a co-gifter, so both households get credit.
“What have I spent on Christmas so far?” A summary of your claims and off-list gifts with totals per person.
“Who has a birthday in the next month that I haven’t planned a gift for?”
“Tidy my list.” Duplicates, missing prices, items that look like alternatives of each other, and GiftWrapt’s own suggestions, with proposed edits before anything changes.
“Roast my brother and make sweeping generalizations about him based on the stuff he wants.” Not everything has to be productive. The assistant reads his list the way you can and takes it from there.

Three ready-made prompts come with the server (plan gifts for someone, tidy a list, what’s coming up) for clients that surface prompts.

All tools

Every tool an assistant can call, generated from the server itself. “Reads” tools only look things up; “Changes” tools add, edit, or remove something, and assistants ask before using the destructive ones. Tools for features your deployment has turned off answer that the feature is off.

Show the full tool list

Tool	Kind	What it does
`add_comment`	Changes	Post a comment on an item the user can see. Mention someone with @Their Name. The list owner and anyone mentioned may be emailed.
`add_item`	Changes, reads the web	Add one item to a list the user owns or can edit (defaults to their primary list). Give a title, a product URL, or both. With a URL the page is read to fill in the title, price, and image unless enrich is false; pass your own values to override what the page says.
`add_items`	Changes, reads the web	Add several items at once (a brain dump or a pasted list). Each needs a title or a URL. URLs are enriched in the background by the import queue rather than while you wait. Requires the deployment’s import feature.
`add_off_list_gift`	Changes	Record something the user is giving that is not on the recipient’s list, so other gifters see it and the recipient learns of it at reveal time. Only on other people’s lists.
`apply_recommendation`	Changes (destructive)	Run one of a suggestion’s applicable actions (by its index from list_recommendations). Actions marked destructive should be confirmed with the user first.
`archive_items`	Changes	Archive items on the user’s own list to mark them received. This REVEALS who gave each gift to the user, so only do it after the occasion, when they ask. Pass archived false to undo.
`assign_items_to_group`	Changes	Put items into a group (all must be on the group’s list), or pass group_id null to take them out of any group.
`claim_item`	Changes	Reserve an item on someone else’s list as a gift the user will give, so other gifters see it is taken. Optional cost and private notes; co_gifter_ids share the gift (and the credit) with other users. Respects pick-one and in-order groups and remaining quantity.
`create_dependent`	Changes	Add a dependent (a pet, a baby, anyone without their own account) that the user and any extra guardians will manage lists for. Admin only on this deployment, matching the web.
`create_item_group`	Changes	Group items on one of the user’s lists. An “or” group means pick one of these (once any is claimed the rest lock); an “order” group means buy them in sequence. Items in a group share the group’s priority. Optionally add items right away.
`create_list`	Changes	Create a list for the user (or for a dependent they manage). Gift-ideas lists are always private and may target the person the ideas are for. Holiday lists need a custom_holiday_id from this deployment. Ask before creating if the user already has a list of that type.
`delete_item`	Changes (destructive)	Remove an item from one of the user’s lists. If a gifter had already claimed it, the item quietly enters a pending-deletion state and the gifter is alerted; the user never sees that difference. Confirm with the user first.
`delete_item_group`	Changes (destructive)	Remove a group. Its items stay on the list, ungrouped.
`delete_list`	Changes (destructive)	Delete a list the user owns. If any item on it has already been claimed by a gifter, the list is archived instead of deleted so gift history survives; the result says which happened. Confirm with the user first.
`delete_off_list_gift`	Changes (destructive)	Remove one of the user’s off-list gifts.
`dismiss_recommendation`	Changes	Hide a suggestion (it stays hidden across regenerations). Pass undo true to bring a dismissed one back.
`get_gift_context`	Reads	Everything needed to decide what to give one person, in one call: every list of theirs the user can see (items with what is claimed and what remains, group rules, off-list gifts), the user’s own private gift ideas for them, what the user already gave or is giving them with what it cost, things they already have and things they no longer list, their birthday and the holidays coming up, and what their lists are mostly about. Start here when the user asks what to get someone. Only `lists[].items` are things the person asked for; `myGiftIdeas` are the user’s private notes that the person never sees, so present them separately and never as on the person’s list. Give person_id from list_people.
`get_list`	Reads	A list the user owns or can edit, with its items, item groups, and reveal schedule. Owner view: claims are never included, so never guess whether something was bought. A giftideas list holds the user’s private ideas for someone else, not things that person asked for. Use get_wishlist for other people’s lists.
`get_me`	Reads	The signed-in user: profile, partner, children and dependents they manage, their primary list, and which features this deployment has turned on. Call this first.
`get_wishlist`	Reads	One list belonging to another person, in the gifter view: its items with what is already claimed and how many remain, pick-one / in-order group rules, off-list gifts other gifters are bringing, and, kept separate, the user’s own private gift ideas for this person. Only `items` are things the person asked for; `myGiftIdeas` are the user’s notes that the person never sees, so never present them as on the person’s list. Give list_id, or person_id to use that person’s primary list. To plan a gift for someone across all their lists, use get_gift_context instead. Never works on the user’s own lists (use get_list).
`list_comments`	Reads	The conversation on an item the user can see (questions about sizes, coordination between gifters). Only available when the deployment has comments turned on.
`list_my_gifts`	Reads	Everything the user (or their partner) is giving: claims and off-list gifts across every list, with costs and totals per recipient. Filter by recipient_id (user or dependent) or by list type. Costs are this household’s share.
`list_my_lists`	Reads	Every list the user can edit: their own (wishlists, birthday, Christmas, holiday, gift-ideas), lists shared with them as an editor, and lists belonging to children or dependents they manage. Owner view: never includes claims.
`list_people`	Reads	Everyone whose lists the user can see and shop from: family, friends, children, and dependents (pets, babies), each with their birthday and their visible lists. Use a person’s primary list id or a list id with get_wishlist to shop. Optional query filters by name or email.
`list_received_gifts`	Reads	Gifts that have been revealed to the user (and to dependents they manage): what was given and by whom, newest first. Only revealed gifts appear; unrevealed claims stay hidden.
`list_recommendations`	Reads	GiftWrapt’s own suggestions for the user’s lists (stale items, duplicates, grouping, missing prices, set-up nudges), with the actions each one offers. Pass include_resolved to also see dismissed and applied ones. Requires the deployment’s intelligence feature.
`list_upcoming_occasions`	Reads	Birthdays of everyone the user can shop for (including children and dependents), plus the holidays this deployment celebrates and the user’s anniversary, within the next N days, each with whether the user has already planned a gift. Sorted soonest first.
`lookup_barcode`	Reads, reads the web	Identify a product from a UPC / EAN barcode number. Returns candidate titles, brands, images, and product URLs to feed into add_item.
`move_items`	Changes (destructive)	Move items to another list the user can edit. Moving between lists of different types (for example wishlist to gift-ideas) clears any claims gifters had made, so confirm with the user first.
`preview_url`	Reads, reads the web	Read a product page and return its title, price, images, and the choices a buyer must make, without adding anything. Useful before add_item or to check a price.
`refresh_recommendations`	Changes	Regenerate the user’s suggestions now instead of waiting for the nightly run. Subject to a per-user cooldown; may take a while and may call an AI provider.
`search_my_items`	Reads	Find items across every list the user owns by words in the title or notes. Results from gift-ideas lists (isGiftIdea true) are the user’s private ideas for someone else, not things the user or that person asked for.
`set_claim_split`	Changes	Set how much each co-gifter owes on one of the user’s claims; the user’s own share is the remainder. Pass an empty list to go back to an even split. The claim needs a total cost first.
`set_item_availability`	Changes	Mark an item unavailable (sold out, discontinued) so gifters skip it, or available again.
`set_primary_list`	Changes	Mark one of the user’s lists as their primary list (the default for add_item and the one others see first). Gift-ideas lists cannot be primary.
`unclaim_item`	Changes (destructive)	Release one of the user’s claims so others can give the item. Permanent: the claim and its notes are deleted. Confirm with the user first.
`update_claim`	Changes	Change the quantity, cost, notes, tracking number, or co-gifters on one of the user’s claims (their partner’s too). co_gifter_ids REPLACES the whole set; pass [] to clear. The partner is already credited automatically and need not be listed.
`update_dependent`	Changes	Rename a dependent or set their birthday. Admin only on this deployment, matching the web.
`update_item`	Changes	Change an item’s title, URL, price, notes, priority, quantity, or image. Pass null to clear a nullable field. Only fields you pass change.
`update_item_group`	Changes	Change a group’s type, name, or priority. An “or” group means pick one of these (once any is claimed the rest lock); an “order” group means buy them in sequence. Items in a group share the group’s priority.
`update_list`	Changes	Rename, describe, re-type, archive (is_active false), or change the privacy of a list the user owns or can edit. Changing a list to or from giftideas clears its target; todo lists cannot change type.
`update_off_list_gift`	Changes	Edit the description, cost, notes, tracking number, or URL of one of the user’s off-list gifts.
`use_gift_idea`	Changes (destructive)	Turn one of the user’s gift ideas for a person into an off-list gift on that person’s list (the idea is removed from the ideas list). Ideas come from get_wishlist’s myGiftIdeas.

What stays private

Your own lists never reveal claims to the assistant, so your surprises stay surprises even if you ask directly. Marking items received (which reveals the givers) is a deliberate action the assistant will ask about.
On other people’s lists, other gifters’ costs and private notes stay hidden; only who is giving what is visible, as in the app.
Restricted viewers see the same filtered view they see in the app.
Child accounts cannot connect an assistant at all.

Manage Connections

Settings → Connected Apps lists the assistants connected to your account with when they were last used. Each has a switch between Can Make Changes and Read Only, and Disconnect signs that assistant out immediately.
Admin → MCP shows every registered client and every active connection across users. Admins can revoke a single connection, disable a client (which signs out everyone using it and blocks new sign-ins), or delete it. Clients re-register automatically the next time someone connects with them.

Troubleshooting

Symptom	Likely cause
The client says it cannot find the authorization server.	A reverse proxy is not forwarding paths under `/.well-known/`. The Admin → MCP connect card checks both discovery URLs; both must return JSON at your public origin.
The client gets a 503 from the server.	Enable MCP Server is off.
Claude (web, desktop, or mobile) shows “Authorization failed” right after you click Allow, while Claude Code connects fine.	A firewall in front of your deployment is blocking AI-assistant user agents. Claude’s hosted connector calls your server as `Claude-User`; rules such as Vercel’s AI Bots managed ruleset or Cloudflare’s AI crawler blocking reject it at the edge, so the request never reaches GiftWrapt. Add a bypass or allow rule for the path `/api/mcp`.
Sign-in works but the client is told it is unauthorized afterwards.	The connection was revoked or the client was disabled by an admin. Reconnect.
A child account cannot connect.	By design.
The assistant says it cannot add, claim, or change anything.	It was connected as Read Only. Switch it under Settings → Connected Apps.
Requests are refused with “too many requests”.	Per-user limits: 120 tool calls a minute, and the same scrape and barcode limits the app uses.

Admin settings for the enableMcp toggle and the admin pages.
Authentication for how the OAuth tokens relate to the web session and mobile API keys.