Documentation
Everything you need to connect Surprise Chef AI to your favourite AI assistant.
What is Surprise Chef AI?
Surprise Chef turns your AI assistant into a personal family chef. It connects to Claude, ChatGPT, or any MCP-compatible AI and gives it access to your pantry, family dietary profiles, cooking history, recipes, meal plans, and shopping lists. Every suggestion is personalised to your household.
How It Works
Create a free account
Sign up at surprisechef.ai with email and password. Name your household and pick your grocery store.
Connect your AI
Go to the Connect AI page in your dashboard. Follow the instructions for your platform (Claude, ChatGPT, Claude Desktop, or others).
Start cooking
Ask your AI anything food-related. It knows your pantry, your family's preferences, and your cooking history.
What You Can Do
Smart Recipes
AI-generated recipe cards with mise en place, smart timers, and cooking cues
Meal Planning
Weekly meal plans that balance cuisines, effort, and your pantry stock
Shopping Lists
Auto-generated from meal plans, with price estimates and interactive check-off
Pantry Tracking
Know what you have, what's running low, and what's out of stock
Family Profiles
Dietary restrictions, allergies, and food preferences for every family member
Dietary Alerts
Automatic warnings when recipes conflict with family allergies or medical needs
Recipe from Photo
Photograph a handwritten or printed recipe — AI digitises and saves it
Price Tracking
Learn your preferred brands and track grocery prices over time
Connecting to Claude
From the connectors directory: open Settings → Connectors in Claude, find Surprise Chef, click Connect, and sign in with your Surprise Chef email and password. That's it — no keys to copy.
As a custom connector (works today on every plan):
- Open claude.ai → Settings → Connectors → Add custom connector
- Name it Surprise Chef and paste the server URL:
https://surprise-chef-mcp.unscramble-apiworkersdev.workers.dev/mcp - Click Add, then Connect — a Surprise Chef sign-in page opens
- Sign in with your email and password (or paste the API key from your Connect AI page)
- Start a new chat and you're connected — it works on claude.ai, the desktop app and mobile
Claude's Free plan includes one custom connector — no paid plan needed. Your password is never shared with Anthropic; Claude receives a revocable access token.
Connecting to ChatGPT
- Open chatgpt.com → Settings → Apps & Connectors → enable Developer Mode
- Go to Connectors → Create
- Paste your connection URL from the dashboard
- Save and start a new chat
Requires ChatGPT Plus or Pro.
Authentication & Security
OAuth 2.0 (recommended). AI clients connect to https://surprise-chef-mcp.unscramble-apiworkersdev.workers.dev/mcp and are sent to a Surprise Chef sign-in page. We support dynamic client registration and PKCE (S256). Access tokens last 30 days and refresh automatically; your password never leaves Surprise Chef.
API key. Every account has a personal key on the Connect AI page. Paste it on the sign-in page instead of a password (useful if you signed up with Google), or send it as Authorization: Bearer YOUR_KEY. Treat it like a password.
Revoking access.Remove the connector in your AI's connector settings at any time. Each household member connects with their own account, so the AI only ever sees data that person can see.
Example Prompts
Once connected, try these in a new chat:
Plan a week of meals around what's in my pantry
“Plan my week of meals around what's in my pantry. Use ingredients I already have where possible, respect everyone's dietary restrictions, and only add things to the shopping list if we genuinely need them.”
Build a shopping list grouped by supermarket aisle
“Build a shopping list from this week's meal plan and group it by supermarket aisle so I can shop top-to-bottom without backtracking.”
What can I cook tonight with what I already have?
“What can I cook tonight using only what's already in the pantry? Don't suggest anything that needs me to go to the shop.”
Check a recipe against my family's dietary restrictions
“Check this recipe against my family's dietary restrictions and tell me if anyone can't eat it. Suggest substitutions for anything that's a problem.”
Multi-User Households
Surprise Chef supports multiple people in one household:
- Owner — full control, invites, settings
- Member — full read/write, own recipes and personal shopping list, own AI connection
- Guest — view the meal plan and RSVP for dinner (“I'm coming Friday”)
Invite members from Settings → Household Members. They get their own account and MCP API key.
Troubleshooting
AI can't find my tools
Start a new chat. Tool definitions are loaded at the start of each conversation.
The sign-in page says my email or password is wrong
Use the same email and password you use at surprisechef.ai. Signed up with Google? Open “Use an API key instead” on the sign-in page and paste the key from your Connect AI page.
“Unauthorized” or “reconnect” error
Your connection has expired or your API key changed. Remove the connector in your AI's settings, add it again, and sign in when prompted.
My old connection URL ends in ?key=
Connections made before September 2026 put your key in the URL. They keep working, but we recommend re-adding the connector with the plain server URL and signing in instead — it's more secure and easier to revoke.