NemlAI for AI agents

Connect

1. The MCP server (first choice)

• URL: https://nemlai.milops.org/mcp (Streamable HTTP, stateless, JSON responses).
• Sign in with OAuth where the client supports it: add the URL with no client id/secret (the client registers itself). The client opens a browser: the user logs in to NemlAI if needed and clicks Giv adgang on the NemlAI consent page (/oauth/consent). The connection has full access to their NemlAI account; it can fill shop carts but never check out.
• Or with an API token: the user runs nemlai login once in their own terminal (it asks for their NemlAI password there, not in chat). The CLI stores a token starting with nemlai_ in ~/.config/nemlai/token; it is sent as Authorization: Bearer <token>. The configs below read it from the NEMLAI_TOKEN environment variable (export NEMLAI_TOKEN=$(cat ~/.config/nemlai/token)) instead of storing it.
• nemlai mcp install <client> (nemlai 0.11 or later) writes a client's config and installs this skill. It backs up the file first, changes nothing else in it, and --dry-run shows the change. nemlai mcp config <client> only prints the config; nemlai mcp doctor checks the URL, the token and the tool list.

Connect in one minute

• claude.ai, Claude Desktop and mobile: Customize → Connectors → Add custom connector → URL → Add → Connect → Giv adgang. Desktop and mobile use the connector added on claude.ai. For the skill, upload nemlai-skill.zip in Claude's Skills settings.

• Claude Code: nemlai mcp install claude-code. It runs claude mcp add --transport http --scope user nemlai https://nemlai.milops.org/mcp --header 'Authorization: Bearer ${NEMLAI_TOKEN}' and puts the skill in ~/.claude/skills/nemlai/. Claude Code needs NEMLAI_TOKEN set when it starts; with a fixed Authorization header it does not fall back to OAuth. For OAuth instead: claude mcp add --transport http nemlai https://nemlai.milops.org/mcp, then /mcp → nemlai → Authenticate.

• ChatGPT: Settings → Apps & Connectors (developer mode) → add a custom MCP server → URL, authentication OAuth → Create → Connect.

• Grok: grok.com/connectors → New Connector → Custom → URL → complete the sign-in.

• Codex: nemlai mcp install codex adds this to ~/.codex/config.toml and puts the skill in ~/.agents/skills/nemlai/:

  [mcp_servers.nemlai]
  url = "https://nemlai.milops.org/mcp"
  bearer_token_env_var = "NEMLAI_TOKEN"
  

• Hermes: nemlai mcp install hermes adds this under mcp_servers in ~/.hermes/config.yaml and puts the skill in ~/.hermes/skills/nemlai/. Set NEMLAI_TOKEN in the environment or in ~/.hermes/.env; in a running session, /reload-mcp.

  mcp_servers:
    nemlai:
      url: "https://nemlai.milops.org/mcp"
      headers:
        Authorization: "Bearer ${NEMLAI_TOKEN}"
  

• OpenClaw (2026.5.12 or later): nemlai mcp install openclaw adds this to ~/.openclaw/openclaw.json and puts the skill in ~/.openclaw/skills/nemlai/. Set NEMLAI_TOKEN in the environment or in ~/.openclaw/.env. If the file has JSON5 comments, run openclaw mcp set nemlai '<the server object below>' instead.

  {"mcp": {"servers": {"nemlai": {"url": "https://nemlai.milops.org/mcp", "transport": "streamable-http",
    "headers": {"Authorization": "Bearer ${NEMLAI_TOKEN}"}}}}}
  

• Other clients: nemlai mcp config generic prints the URL, the header and a JSON entry.

• If the connector can't sign in (the client's OAuth fails), use the token where the client takes a header, else the CLI or the web app.

• Check it works: whoami(). Not sure what to do: nemlai_guide().

2. The nemlai CLI (when MCP fails and you have a shell)

pipx install nemlai            # or: pip install nemlai
export NEMLAI_TOKEN=nemlai_…   # the user's token; or the user runs `nemlai login` themselves
nemlai --json whoami           # one command, JSON output, then exit
nemlai --json basket items
nemlai help                    # every command

• Every MCP tool names its CLI command (see the fallback topic, or error.fallback.cli). Run that command as written: the global --json makes every command print one JSON object (status plus the data, or status + message for a text reply, or status + error + hint). With nemlai older than 0.11 (nemlai --version), add --format json to analytics commands; the report then comes back as a JSON string in message, so parse it a second time.
• The CLI reads the token from ~/.config/nemlai/token, else from NEMLAI_TOKEN. Don't pass --token on the command line (it shows up in process lists).
• Never type a password into the CLI for the user. Commands that need one (login, shops link, a Nemlig reauth) are for the user to run in their own terminal, or to do in the web app.
• Python: from nemlai import NemlAI; client = NemlAI(token=…) gives the same features as methods (client.basket.items(), client.basket.send(), …).

3. The web app (no shell, or the CLI fails too)

An agent with a browser tool opens the page and follows the steps listed for the tool in the fallback topic; an agent without one gives the user the link and the steps. The user logs in themselves.

4. Everything down

Say so plainly and don't invent results. Check https://nemlai.milops.org/healthz. The user can still shop directly on https://www.nemlig.com.

Data model and core loop

What NemlAI is

• A household shops online, mostly at Nemlig.com. NemlAI fetches the household's past orders, learns what it buys and how often, and predicts the next basket: which products and how many.
• The user (or you, the agent) reviews the basket, adjusts it, and sends it to a shop. Sending fills the shop's own cart. The user then opens the shop's site and checks out. NemlAI never checks out or pays.
• The same basket can be priced at other shops (BilkaToGo, Netto, Føtex, REMA 1000) and sent to the ones that accept a basket.

Data model

Scope: household scope is the default for orders, analytics and settings. Use one member's scope only when the user names that person ("refresh Anna's orders"). The basket is the exception: it belongs to the user this connection acts for, so another member doesn't see it; the user sees it on the web page /kurv/.

The core loop

1. Check the connection: whoami(). No household → the user joins or creates one in the web app first.
2. Look at the basket: get_basket(). If it is empty or old, generate_basket() with a budget preset (small, medium, large). It returns when done or gives a job_id for job_status().
3. Review with the user: show the items, quantities and the total in kr against the budget. explain_item() says why an item is there.
4. Adjust: add_to_basket() (by SKU from search_products()), set_quantity(), remove_from_basket(), add_dish_to_basket() for a meal.
5. Optionally compare shops: compare_shop_prices().
6. Send with send_basket() only after the user says so. Tell them to check out on the shop's site.

How results look

Every tool returns an envelope:

• Success: {"ok": true, "data": {…}, "next": ["…"]}. next lists what makes sense now; follow it.
• Failure: {"ok": false, "error": {"code", "message", "hint", "fix": {"tool", "args"}, "fallback": {"cli", "web"}}}. Do fix if present; otherwise see the fallback topic.

Error codes: invalid_argument (fix the call), not_found (use an id from a tool result; the hint lists candidates), forbidden, no_household, not_linked (web app link), reauth_required (the user logs in again in the web app), job_running (poll the job_id in fix), upstream_unavailable (retry once, then fall back), rate_limited (wait as the hint says), conflict (the basket changed elsewhere, e.g. on /kurv/: get_basket() again, then redo the change), cart_not_empty (the shop's cart already holds items and nothing was sent: ask the user details.ask_user, then send_basket() again with their cart_mode), internal (fall back).

Limits: each user gets about 240 tool calls a minute with at most 8 at once, and each household gets find_dishes 10 per 10 minutes, generate_basket 6 per 10 minutes, live shop reads (get_shop_cart, get_delivery_info, list_delivery_slots) 30 a minute, and analytics plus compare_shop_prices 60 a minute. Over a limit the call answers rate_limited with details.retry_after in seconds: wait that long and retry once; never loop.

Where to go next

• The rules: nemlai_guide(topic="rules").
• A whole task: the workflow topics (weekly-basket, dinners-via-dishes, trim-to-budget, compare-shops, spending-review, exclude-products, order-refresh-reauth, shop-not-linked).
• One tool: nemlai_guide(topic="<tool name>").
• When something fails: nemlai_guide(topic="fallback").

Rules

Sending and paying

1. Show before you send. Before send_basket(), show the user the items (name, quantity, price) and the total in kr, and the budget if there is one. Send only when the user clearly says so ("send it", "ja, send") about the basket you showed. A request to "make a basket" is not a request to send it, and "send kurven" about a basket the user hasn't seen in this conversation means: show it and ask "Skal jeg sende den til Nemlig?" first.
2. The user decides what happens to their shop cart. Call send_basket() without cart_mode first. An empty cart is filled straight away. If the cart at the shop already holds items, nothing is sent and the answer is cart_not_empty with the cart's count, total and a few names. Ask the user, e.g. "Du har allerede 6 varer for 214,50 kr. i din Nemlig-kurv (bl.a. mælk, rugbrød og bananer). Skal jeg beholde dem og lægge de nye varer oveni, eller tømme kurven og kun sende de nye?" (details.ask_user), then call send_basket() again with cart_mode="keep" (a product in both gets the higher quantity) or cart_mode="replace" (empty the cart first). Never pick the mode yourself, and never send replace without that answer: it removes things the user put there.
3. Send once. send_basket() is a job. If it times out, fails or the result is unclear, check job_status() with its job_id, or get_basket(), before anything else. A second send can double the shop's cart.
4. No checkout, ever. send_basket() fills the shop's cart, item by item through the shop's API. The user opens the shop's site, checks the cart and pays. Say that when you send. Never claim an order was placed. NemlAI also never books or reserves a delivery time, chooses a pickup store or the delivery mode, or changes the address: get_delivery_info() and list_delivery_slots() only read them.
5. The cart link comes after the send. A completed send returns cart_url: for Nemlig the plain https://www.nemlig.com/basket link, which opens the Nemlig app if it is installed. Offer it as "Åbn kurven i Nemlig (åbner appen, hvis den er installeret)". Before a send there is no link, and no link adds items to the cart; a failed send has no link either: say what went wrong and what to do (e.g. log in to Nemlig again in the web app).

Prices and campaigns

6. Prices are in Danish kroner (kr). Show them as the tools return them (e.g. 79,00 kr or 79.00 kr); don't convert currencies.
7. Campaign minimums. A campaign price applies only when the quantity reaches campaign_min_quantity. "Mix 3 stk 79,00" means 3 items for 79 kr together (26,33 kr each); with 2 items the regular regular_unit_price applies. When a user is 1 item short of a campaign, you may point it out; don't raise quantities on your own.
8. Pant (bottle and can deposit) is a separate charge on drinks, refunded when the empties are returned. Don't fold it into the product price or count it as spending on the product.

Danish text

9. Keep Danish text as it is. Product names, categories and dishes are Danish. Keep "øko" (organic) and the letters æ, ø and å intact in names, searches and messages. Never transliterate ("oeko", "aeble"): search with the real spelling ("æble", "økologisk").
10. Øko is a real difference. An øko product and its non-øko version are different products. Don't swap one for the other without saying so.

Scope and identity

11. Household scope is the default. Orders, analytics and settings belong to the household. Use one member's scope only when the user names a person ("Annas ordrer"). The basket is per user: one saved basket that MCP, the CLI, the SDK and the web page /kurv/ share; it is not the household's.
12. Never take ids from the user's head. SKUs, dish ids, job ids and order ids come from earlier tool results. If an id is unknown, the error lists candidates: pick from those or search again. A vague request ("tilføj mælk") that matches different products (øko or not, fat %, size) is not a choice: show the options, or what the household usually buys (analytics_top()), and ask.
13. Never ask for a password. Not for NemlAI, Nemlig, Salling/Bilka or any shop, at any step. Logins, linking a shop, Nemlig reauth, password changes and deleting the account happen in the web app; give the user the link (account_links()) and let them do it.

Honesty

14. Never invent results. If a tool fails and the fallbacks fail, say so plainly. The user can still shop directly on nemlig.com.
15. Say which way you used. If you fell back to the CLI or the web app, tell the user ("MCP is down, so I used the nemlai CLI").
16. Follow next and fix. Tool results say what state things are in and what to call next. Call nemlai_guide() when unsure instead of guessing.

Workflows

Tools

Tools marked (coming) are not built yet. Ask the server for details with nemlai_guide(topic="<tool or area>").

Account, household and feedback (account)

• update_profile: "change my name". A changed Nemlig email is not set here: the user changes it in the web app.
• export_my_data: "give me my data" (GDPR).
• account_links: the user wants something an agent must not do: signup, login, change_password, reset_nemlig_password, link_shop (Bilka/Føtex), reauth_nemlig (expired Nemlig session), delete_account.
• achievements: "what have I unlocked?".
• send_feedback: only when the user asks to send feedback to the NemlAI team.
• household_invite_code: "how do I invite my partner?".
• whoami: Documentation coming.

Household (household)

• household_info: Documentation coming.

Orders (orders)

• order_fetch_status: the user asks whether their orders are up to date, a basket looks stale, or a refresh failed with reauth_required.
• refresh_orders: the user says they ordered recently ("jeg har lige handlet") and wants the history or the next basket to include it.

Basket (basket)

• generate_basket: "make my weekly basket", "start a new basket", after refresh_orders(), or when get_basket() is empty or old.
• get_basket: before talking about the basket, before send_basket(), after changes, or when the user asks what's in it.
• explain_item: "why is X in my basket?", "why 3 of them?", or when trimming to a budget and you need to know which items the prediction is least sure about.
• add_to_basket: the user wants a product added ("add rugbrød", "2 liter øko mælk too").
• set_quantity: "more milk", "only one rugbrød", or to reach a campaign minimum.
• remove_from_basket: the user doesn't want an item, or to trim the basket to the budget.
• clear_basket: only when the user explicitly asks to empty the basket or start over by hand.

Search (search)

• search_products: the user wants a product that isn't in the basket, wants a cheaper or øko alternative, or add_to_basket() returned candidates and you need more.
• product_info: the user asks about one product: brand, weight, origin, whether it's øko or in stock, or the campaign details.
• list_categories: the user asks what kinds of products there are, or you need a category name (for browsing ideas or for the analytics_* category filters).

Dishes (dishes)

• find_dishes: "what do I need for butter chicken?", "add a fish dinner", "ideas for lasagne til 4".
• dish_info: going back to a dish found earlier in the conversation, or to see which of its ingredients are already in the basket.
• dish_recipe: the user wants to know how to cook the dish.
• add_dish_to_basket: the user wants the dish's ingredients in the basket (all or some).

Shops (shops)

• list_shops: before comparing prices or sending, or when the user asks which shops they can use.
• refresh_shop: the user shopped at Bilka or Føtex and wants those receipts in the history or analytics.
• compare_shop_prices: the user asks "hvad koster kurven i Netto/Bilka?", which shop is cheapest, or wants a shopping list for a shop without a cart.
• list_alternatives: a shop lacks a basket item, matched it loosely, or the user wants another brand/size there.
• list_offers: "hvad er på tilbud?", "er noget af det vi plejer at købe på tilbud?", "ugens tilbud hos Bilka", Dagstilbud or free gifts at nemlig.
• send_basket: only after the user has seen the basket and its total and explicitly asks to send it.
• get_shop_cart: the user asks "hvad ligger der i min kurv hos Nemlig/BilkaToGo?", or wants to see the whole cart before choosing keep or replace after send_basket() answered cart_not_empty.
• get_delivery_info: "hvornår kommer varerne?", "hvad koster leveringen?", "kan jeg nå at ændre ordren?".
• list_delivery_slots: "hvilke leveringstider er billigst i morgen?", "hvornår kan jeg få leveret?".

Analytics tools (analytics)

• analytics_overview: "How much did we spend?", a summary of a period. The one call to start with.
• analytics_spend: the total for a product or category, optionally compared with the previous period.
• analytics_top: "what do we spend most on", by product or by category.
• analytics_trend: spend over time, optionally for a product or category.
• analytics_drill: the individual lines behind a number: when something was bought, at what price, in which order.
• analytics_receipts: expense documentation, or finding the order_number for analytics_drill.
• analytics_categories_tree: you need the exact category names before filtering, or a full breakdown by category.

Settings, preferences and notifications (settings)

• get_settings: the user asks how predictions are configured, or before changing a setting.
• update_settings: "ignore orders before March", "turn off auto-learn".
• get_preferences: "what does NemlAI think I like?", before update_preferences.
• update_preferences: "I'm vegetarian now", "never suggest liver paste", "I prefer Arla".
• preference_definitions: the user asks what can be tuned, or you are unsure of a preference key.
• recalculate_preferences: after new orders were imported, or get_preferences shows total_orders 0 / stale numbers.
• notifications_status: "do I get push notifications?", before send_test_notification.
• send_test_notification: only when the user asks to test notifications.

Exclusions (exclusions)

• get_exclusions: "what have I excluded?", or to find an order id before excluding it.
• list_order_items: the user wants to hide single products on an order.
• update_exclusions: exclude or include a whole order, or hide or unhide lines.

Jobs (jobs)

• job_status: a start tool (generate_basket, send_basket, refresh_orders, refresh_shop, find_dishes) returned status: "running", or the user asks whether a basket send or refresh has finished.

Guide tools (guide)

• nemlai_guide: you are unsure which tool to use, what a Danish word means, how a whole task goes, or what to do when a tool or MCP fails. Call it first in a new conversation if the instructions are not enough.

Fallback

The ladder

Go one step down only when the step above fails.

1. The tool returned an error with a fix: do the fix call. Retry a timeout, upstream_unavailable or a 5xx once after a few seconds. For a job, poll job_status() with its job_id; don't start the job again. An HTTP 502/503 from the proxy (not a NemlAI error envelope) usually means a deploy is restarting the server: wait about 10 seconds and retry once. A job the server no longer knows after that (not_found) was lost in the restart: start it once more, except send_basket() (check the basket and the shop's cart first).
2. MCP unreachable, auth failing, or a tool missing → the CLI (agents with a shell): pipx install nemlai, then run the tool's command from the table below (or the error's fallback.cli) as written, with NEMLAI_TOKEN set. They are nemlai --json <command>.
3. No shell, or the CLI fails too → the web app: with a browser tool, open the page from the table (or fallback.web.url) and follow its steps; without one, give the user the link and the steps. The user logs in themselves.
4. Everything down: say so plainly, check https://nemlai.milops.org/healthz, never invent results. The user can still shop directly on nemlig.com.

Rules on every step

• Never send a basket twice blindly. After a failed or unclear send_basket(), check job_status() or the basket (get_basket(), nemlai --json basket items or /kurv/) first. A second send can double the shop's cart.
• The web page shows the same basket. MCP, the CLI and the web page /kurv/ share one saved basket per user, so falling back to the web for a basket action means opening /kurv/: the items you added are there. A change made on the page while you work makes your next write fail with conflict: read the basket again (get_basket()) before you change it.
• Never ask the user to paste a password into chat, whichever step you are on. Logins, shop linking and Nemlig reauth happen in the web app (or in the user's own terminal).
• Tell the user which step you used ("MCP is down, so I used the nemlai CLI").
• The same rules as with MCP apply: show the basket and total before sending, send only on the user's go-ahead, no checkout.

Per tool

The table is generated from nemligbot/mcp/coverage.py (TOOLS): CLI is the command to run with NEMLAI_TOKEN set; Web is the page and the steps there. Placeholders in <…> come from earlier results (SKUs, ids) or from the user.

Glossary

Words

Campaign text formats

Shops describe a campaign in text. NemlAI parses it into campaign_min_quantity, campaign_unit_price and regular_unit_price; when the quantity is at least the minimum the basket uses the campaign price and marks the item on_sale.

"Mix" means the products can be mixed: 2 of one flavour and 1 of another still reach 3. Below the minimum, each item costs regular_unit_price. If the text can't be parsed, NemlAI falls back to the regular price; say "the campaign may not apply" rather than guessing.

Shop names

Use the ids list_shops() returns; they are the only valid values.