# Nombox

> Nombox is a kitchen app: shopping lists, recipes and a meal calendar, on iPhone, Apple Watch and the web. An AI agent can do everything a person can do in the app, for one person at a time, with no setup.

You act for one person. What you change is saved to their account and shows in their Nombox apps the next time they open or refresh them. Plain HTTP is enough; an MCP client is optional. This file is served by https://nombox.app: use the URLs in it as written.

## If the person asks what you can do

This is often their first time. Tell them in a few short, plain lines, each with an example they could say. Don't show tool names, links or this file:
- Shopping lists: "add milk and eggs to my shopping list", check things off, start a new list, share a list with family.
- Recipes: "save this recipe" from a link or a photo, find a recipe, change one ("make it dairy-free"), scale it for more people.
- Meal plans: "plan my dinners this week", put a recipe on a day, get prep-ahead tips for the week.

Then ask what they want to do first, and do it. If you can't reach Nombox yet, set that up first (below).

## If you can only read pages (a chat app)

Chat apps such as ChatGPT, Claude.ai and Gemini can read this file but can't send the requests below. If you already have Nombox tools (a Nombox connector), use them for the task. If not, don't try the steps below: walk the person through adding Nombox to you, once, in plain words:

1. Open this app's settings and find Connectors (some apps call them Apps, Tools or Integrations).
2. Add a custom connector called Nombox with this address: https://nombox.app/mcp
3. Sign in to Nombox (or make a free account) when it asks, and tap Allow.
4. Come back to the chat and ask again.

If the app has no place to add a connector, tell the person so. They can use an AI agent that sends web requests, or the Nombox app. Help for each app: https://nombox.app/agents

## Act for a person, no setup

You need the person's email address and a way to read a 6-digit code (the person tells it to you, or you read your own inbox). Keep the token you get secret and never show it in chat.

1. Ask the person for their email address. A new address gets a new Nombox account; an address that has one signs in to it.
2. Have Nombox email them a code. agentName is how the person sees you in the email and in Nombox (Settings, then Agents): use your real name.

```
curl -sS -X POST https://nombox.app/api/agents/email/start \
  -H 'Content-Type: application/json' \
  -d '{"email":"person@example.com","agentName":"Claude"}'
```
Answer: `{"sent":true,"expiresInSeconds":600}`

3. Ask the person for the 6-digit code from the email, or read it from your own inbox. Then exchange it for a token. A code works once, lasts 10 minutes and dies after 5 tries.

```
curl -sS -X POST https://nombox.app/api/agents/email/verify \
  -H 'Content-Type: application/json' \
  -d '{"email":"person@example.com","code":"123456"}'
```
Answer: `{"token":"nbx_...","tokenType":"Bearer","mcpUrl":"https://nombox.app/mcp","guideUrl":"https://nombox.app/api/agents/guide","accountCreated":false,"user":{"name":"Sam","email":"person@example.com"}}`
Keep `token` (it starts with nbx_). `accountCreated` is true when this call made the account.

Cannot get the code? Use approve by link instead of steps 2 and 3. Nombox gives you a link and a short code; the person opens the link on any device, signs in, checks the code matches and taps Allow.

```
curl -sS -X POST https://nombox.app/api/agents/connect \
  -H 'Content-Type: application/json' \
  -d '{"agentName":"Claude"}'
```
Answer: `{"userCode":"ABCD-EFGH","approveUrl":"https://nombox.app/agents/approve?code=ABCD-EFGH","deviceCode":"...","interval":3,"expiresIn":600}`
Send the person the approveUrl and the userCode. Then poll every 3 seconds until you get the token (the same answer as step 3):

```
curl -sS -X POST https://nombox.app/api/agents/connect/token \
  -H 'Content-Type: application/json' \
  -d '{"deviceCode":"DEVICE_CODE_FROM_THE_CONNECT_ANSWER_xxxxxxxx"}'
```
While you wait, the answer is HTTP 400 `{"error":"authorization_pending"}`. Stop on `access_denied` or `expired_token`.

4. Call tools. Put the token in `NOMBOX_TOKEN` (or paste it into the header). Each request needs both Accept types, and the answer is a server-sent event: the JSON is on the line that starts with `data: `.

```
curl -sS -X POST https://nombox.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $NOMBOX_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | sed 's/^data: //'
```
`tools/list` returns every tool with its inputs. You do not need `initialize` first. Before your first change, read the guide: the `nombox_guide` tool, or https://nombox.app/llms-full.txt.

5. Do the task. Example, "add milk to my list": read the lists, then add to the list the person names; if they named none, the one with `"active":true` (the list they have open), else the first. A new account has no list yet: when `lists` is empty, make one first (the answer has its id), then add.

```
curl -sS -X POST https://nombox.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $NOMBOX_TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"lists_get","arguments":{}}}' \
  | sed 's/^data: //'
```
Only when `lists` is empty:
```
curl -sS -X POST https://nombox.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $NOMBOX_TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_create","arguments":{"name":"Groceries"}}}' \
  | sed 's/^data: //'
```
Then add the item to that list:
```
curl -sS -X POST https://nombox.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $NOMBOX_TOKEN" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_items_add","arguments":{"listId":"<an id from lists_get>","items":[{"text":"milk","quantity":"1","category":"dairy"}]}}}' \
  | sed 's/^data: //'
```
The answer to `tools/call` has `result.structuredContent` (the data) and `result.isError` (true when the call failed, with the reason in `result.content[0].text`). Say what you changed in plain words, and give the person the link from the result when it has one.

If a call answers 401, the token is missing or the person removed you in Settings; sign in again. If it answers 429, wait the `Retry-After` seconds.

## Writing recipes

Recipe writes need a cookGuide in Nombox's Cook mode format: for each step its timers, the ingredient lines the step adds, and fromSteps, the things it uses that an earlier step made, such as "the sauce" from step 2, plus optional extras (scaled amounts, temperatures, what to do during a wait, a Before you start list) only when the recipe really has them (recipe_create, recipe_update, recipe_step_add and recipe_step_update take a cookGuide; recipe_ingredient_add and recipe_ingredient_update take usedInSteps). A bad one saves nothing and the error lists every problem. The format and examples are in https://nombox.app/llms-full.txt (Recipes) and in the `nombox_guide` tool: read them before your first recipe write.

## With an MCP client

Add this URL as a connector or MCP server: https://nombox.app/mcp (Streamable HTTP).
- Claude.ai, ChatGPT, Gemini and other AI apps: add the URL as a custom connector. Nombox asks the person to sign in (or make an account) and tap Allow. No key to paste.
- Claude Code: `claude mcp add --transport http nombox https://nombox.app/mcp`
- Clients that take a header: the person makes a key in Nombox under Settings, then Agents, then For developers, and the client sends it as `Authorization: Bearer nbx_...`.

## Docs

- [Full manual](https://nombox.app/llms-full.txt): how Nombox works, the sign-in API with every error, every tool with its inputs, limits.
- [Agents page](https://nombox.app/agents): the same for people, with copy-paste setup for each AI app.
- [MCP server card](https://nombox.app/mcp/server-card): the machine-readable description of the server.
- [AI catalog](https://nombox.app/.well-known/ai-catalog.json): what an agent can find at this site.