Pantryfy MCP documentation

Connect Pantryfy

Pantryfy’s remote Model Context Protocol (MCP) server connects an assistant to your household’s pantry, saved recipes, meal plan and shopping lists.

ChatGPT and Claude: https://api.pantryfy.ai/mcp/ (21 tools)

Muse: https://api.pantryfy.ai/mcp-muse/ (20 tools; no recipe URL import)

Transport: Streamable HTTP over HTTPS. Keep the trailing slash. This is a remote server; no local installation is required.

In your assistant’s connector settings, add a custom remote MCP server with the URL above. Choose OAuth authentication if prompted.
Sign in to Pantryfy in the authorization window. Select the household to connect and review the requested permissions.
Approve the permissions you want to grant and return to the assistant. Let it finish discovering the tools.
Try: “What in my Pantryfy pantry expires in the next seven days?”

For Claude, use its custom connector flow with the server URL and automatic OAuth discovery. For ChatGPT, use its custom app/MCP connection flow with OAuth. For Muse, use its remote MCP connection flow and the Muse URL above. The assistant must support remote MCP and OAuth; access to custom connections depends on the assistant’s own account and workspace settings. Adding a custom connection does not require finding Pantryfy in a directory.

You need a Pantryfy account and membership in a household. OAuth connections work with Free, Pro and Family accounts. Individual features and usage allowances follow your Pantryfy plan. No Pantryfy API key or OAuth client secret is required for this flow.

Permissions and household access

Each connection is bound to the household selected during authorization. Tools cannot select an arbitrary household or access another household through an object ID. Members of the connected household can see changes to its shared data.

Scope	Allows
`pantry:read`	Search pantry items, check expiry dates, request substitutes and read a kitchen summary.
`pantry:write`	Add pantry items and update their details or quantities.
`recipes:read`	Search and read saved recipes and request pantry-based recommendations.
`recipes:write`	Create recipes, import a public recipe URL and edit recipe metadata.
`planner:read`	Read a week’s meal plan.
`planner:write`	Add planned meals and mark meals cooked.
`shopping:read`	Read shopping lists and their items.
`shopping:write`	Create lists, add items, check items off and generate a list from planned meals.

Read permissions do not authorize changes. Approved write permissions let the assistant perform matching actions; Pantryfy does not show a separate confirmation dialog for every tool call. Review requests that edit quantities or mark meals cooked: marking a meal cooked deducts its ingredients from pantry stock. Adding planned meals can reserve pantry quantities for those meals.

Tool reference

ChatGPT and Claude expose all 21 tools below. Muse exposes the same tools except recipes_import_url; use recipes_create with recipe text supplied by the user. The Muse connector does not scrape websites. All endpoints share the same authentication, retention and disconnect controls. An authenticated MCP tools/list request returns the current descriptions, JSON input schemas and read-only, destructive and open-world annotations. IDs used in later calls come from earlier tool results; do not invent IDs.

Tool	Permission	Inputs and behavior
`pantry_search`	`pantry:read`	Optional `query`; returns matching pantry items and their IDs.
`pantry_expiring`	`pantry:read`	Optional `days` (1–30, default 7); returns expiring items.
`pantry_substitute`	`pantry:read`	`ingredient`, optional `require_in_pantry`; suggests substitutes.
`household_context`	`pantry:read`	No inputs; returns pantry and meal/list counts and tonight’s dinner title.
`pantry_add`	`pantry:write`	`items` (1–30), each with `name` and optional `quantity`, `unit`, `location`; adds items.
`pantry_update`	`pantry:write`	`item_id` and fields to change: `name`, `quantity`, `unit`, `location`, `expiry_date`. Changes existing data.
`recipes_search`	`recipes:read`	Optional `query`; searches the household’s saved recipes.
`recipes_get`	`recipes:read`	`recipe_id`; returns ingredients and instructions.
`recipes_make_now`	`recipes:read`	Optional `limit` (1–5); ranks saved recipes using local ingredient overlap and household allergen/diet exclusions. `request` is accepted for compatibility but does not change this local ranking.
`recipes_create`	`recipes:write`	`title`, `ingredients` (text lines), `instructions` (steps); optional description, servings, tags and preparation/cooking minutes. Saves a new recipe.
`recipes_import_url`	`recipes:write`	`url`; fetches a public recipe page and saves the imported recipe. This tool accesses an external website and is available only on the ChatGPT/Claude endpoint.
`recipes_update`	`recipes:write`	`recipe_id` and optional title, description, servings, tags or meal types. Edits metadata, not ingredient or instruction lists.
`planner_get_week`	`planner:read`	`week_start`; returns meals with their IDs and completion state.
`planner_add_meals`	`planner:write`	`week_start`, `meals` (1–28), each with `recipe_id`, `day_of_week` (0 Monday–6 Sunday), optional `meal_type` and `servings`.
`planner_complete_meal`	`planner:write`	`meal_id`; marks the meal cooked and deducts pantry ingredients.
`shopping_list`	`shopping:read`	No inputs; returns lists with IDs and item counts.
`shopping_get`	`shopping:read`	Optional `list_id`; reads lists or one list’s items and item IDs.
`shopping_create_list`	`shopping:write`	`name`; creates an empty list.
`shopping_add`	`shopping:write`	`items` (1–30), each with `name` and optional `quantity`, `unit`, `category`; optional `list_id` selects a list.
`shopping_check_item`	`shopping:write`	`list_id`, `item_id`; marks an item bought.
`shopping_generate_from_week`	`shopping:write`	`week_start`; creates a shopping list from that week’s planned meals.

Use ISO dates (YYYY-MM-DD) and a Monday for week_start. Unit values are case-sensitive: item, piece, dozen, bunch, bag, box, can, bottle, jar, package, stick, lb, oz, gallon, quart, pint, cup, fl oz, tbsp, tsp, kg, g, mg, L, ml.

The connector does not expose purchases, public posting, delete/remove tools, shopping-to-pantry export, or Recipe Studio. Recipe search searches saved household recipes. Suggestions use available ingredient and household restriction data; check labels, unknown ingredients and cross-contact yourself. Pantryfy does not certify allergen safety.

Examples

“What should I use up this week?” — pantry_expiring with {"days":7}.
“Find my saved lentil recipes and show the ingredients.” — recipes_search, then recipes_get using a returned recipe ID.
“Add two cans of chickpeas to my pantry.” — pantry_add with {"items":[{"name":"chickpeas","quantity":2,"unit":"can"}]}.
“Plan that saved recipe for Monday dinner.” — planner_add_meals with a returned recipe ID and the selected week.
“Show this week’s shopping list.” — shopping_list, then shopping_get using the chosen list ID.

OAuth and client implementation

Pantryfy uses authorization code authentication with PKCE (S256) and bearer access tokens. Use discovery rather than hardcoding authorization details:

Endpoint	URL
MCP resource / OAuth `resource` value	`https://api.pantryfy.ai/mcp/` or `https://api.pantryfy.ai/mcp-muse/`; must match the connected endpoint
OAuth revocation	`https://api.pantryfy.ai/oauth/revoke`
Protected resource metadata	`https://api.pantryfy.ai/.well-known/oauth-protected-resource`
Authorization server metadata	`https://api.pantryfy.ai/.well-known/oauth-authorization-server`
Authorization	`https://api.pantryfy.ai/oauth/authorize`
Token exchange and refresh	`https://api.pantryfy.ai/oauth/token`
Dynamic client registration	`https://api.pantryfy.ai/oauth/register`

The server supports OAuth Client ID Metadata Documents and dynamic client registration. Public clients use token endpoint authentication method none. Send the exact resource URL above during authorization and token exchange. Access tokens last one hour. Refresh tokens rotate on use and expire after 30 days; clients must store the newly returned refresh token and avoid replaying a rotated token.

For MCP POST requests, send Content-Type: application/json, Accept: application/json, text/event-stream and Authorization: Bearer <access token>. Complete initialize and notifications/initialized before requesting tools/list. Send the negotiated MCP-Protocol-Version on subsequent requests. The server is stateless and does not require a persistent Mcp-Session-Id. The endpoint is not a legacy SSE URL.

An unauthenticated request returning 401 with WWW-Authenticate is the normal start of OAuth discovery. A plain browser visit is not an authenticated MCP connection test.

Data handling and disconnecting

Tool responses share the requested household data with the assistant you connect. Depending on the tool and scopes, this includes pantry inventory, recipe content, meal plans and shopping lists. Substitution and recommendation tools may use household dietary restrictions. URL import fetches the recipe website you supply; URL import uses Pantryfy’s configured AI providers. Other connector tools use local data processing; ingredient matching does not add connector input to global learning queues. See our Privacy Policy and Terms of Service for data handling details.

Connector requests and responses are processed to fulfill the requested action. They are not stored as chat histories, persistent MCP sessions, prompt/result caches or per-call product analytics. Payload tracing is suppressed; account-level usage totals and short-lived rate-limit counters enforce service limits. Content you explicitly save remains in your Pantryfy household for your use.

To revoke access, open Pantryfy Settings, find Connect an agent → Connected apps, and choose Disconnect for the connected app. Remove the connector in your assistant as well. Disconnect erases that household/client connection’s tokens, write grants and authorization codes, and removes its legacy identifiable external-call analytics. OAuth clients may also POST a token to /oauth/revoke; it uses the same disconnect operation. Access and refresh tokens from a disconnected connection fail, and a fresh authorization is required. Pending tool work is serialized with disconnect. Account deactivation also erases OAuth credentials and grants. Disconnecting makes saved household data inaccessible to that connector; it does not undo saved pantry changes or delete earlier conversations held by the assistant. Manage conversation history and retention through that assistant’s controls.

Troubleshooting

Symptom	What to do
Authorized, but connection or tool discovery fails	Confirm the exact server URL, including `/mcp/`. Retry the connection. If it persists, send support the assistant name, time and error/reference ID. Successful sign-in does not guarantee the MCP transport completed.
`421 Misdirected Request`	The server rejected the request’s host. Use the canonical URL above. If it is already correct, contact support; changing your password or repeatedly approving OAuth will not fix a server host configuration error.
`401` after previously working	Let the client refresh its token, or reconnect if access was revoked or the refresh token expired.
`403` or a scope error	Check the approved permissions and household membership. For a write action, reconnect and grant its matching write scope if you want to allow it.
`rate_limited`	Wait for the `retry_after_s` interval before retrying. Tool calls are limited to 60 per minute per principal.
`usage_limit_reached`	Wait for a time-based allowance to reset, or reduce saved items in Pantryfy when you have reached a saved-item limit.
`feature_unavailable`	That action is not available for the connected Pantryfy account. Other permitted tools remain available.
An item or recipe cannot be found	Confirm the selected household and search again for its current ID.
Connection fails after a server restart	Let the client initialize a fresh MCP session.

Contact [email protected] with the assistant name, approximate time and timezone, failing step and error text or support reference. Never send passwords, API keys, access tokens or refresh tokens.

Security incidents

Report connector security concerns through Pantryfy support. Pantryfy’s connector incident process covers containment, credential revocation, evidence minimization, affected-user assessment and provider notification. For a security incident involving Muse User Data, the notification deadline to Meta is 48 hours from awareness; an initial notice may be followed by updates as facts are confirmed.