Skip to main content
AI Integration · MCP

Formul.io MCP Server

Connect your recipes and the ingredient library to Claude, ChatGPT and any MCP-compatible assistant — and formulate in plain conversation.

MCP endpoint
https://api.formul.io/mcp
Speaks MCP protocol versions 2024-11-05 through 2026-07-28 — including the stateless per-request model and server/discover — with result cards (MCP Apps) in Claude and ChatGPT, shown by show_card, and built-in guidance prompts.

What is the Formul.io MCP server?

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. The Formul.io MCP server puts your saved recipes, your custom ingredients and the 10,000+ ingredient library — plus the same food-science engine behind our calculators — directly inside the conversation.

Connect once and ask an assistant to read a recipe, estimate water activity and shelf life, run what-if simulations, diagnose problems, find substitutes, organise recipes into collections, or check what your stock covers and read your shopping lists — without leaving the chat. You stay in control: the assistant can only do what the scopes you grant allow, and destructive actions require explicit confirmation.

Tools the assistant gets

Tools are grouped by task. Read-only tools retrieve or calculate data without saving changes; write tools require the permissions you grant.

Every plan, Free included, can use the read tools, save new recipes with create_recipe and import_recipe, and save recipe notes with save_recipe_note. Free keeps up to five of your own recipes (copies of knowledge-base recipes do not count); past that, create_recipe and import_recipe return an error that names Pro and links the plans on formul.io. Whole files are imported in the Formul.io app. The other write tools — update_recipe, delete_recipe, delete_recipe_note, set_recipe_dag, save_collection, delete_collection, create_ingredient, update_ingredient and add_stock — need Pro. On Free, calling one returns an error that names Pro and links the plans on formul.io; the read tools keep working. Every call counts toward your plan’s rate limits.

Find & read recipes
  • list_recipes
    Find and filter your saved recipes.
  • get_recipe
    Full ingredient list and metrics for one recipe.
  • list_recipe_versions
    A recipe's saved versions, newest first, and whether the current state is already saved.
Create & edit recipes
  • create_recipe
    Author and save a new formula from known ingredients, or clone an existing recipe. Names the library does not hold are reported back; rows that only resemble them are marked weak and are never used without your confirmation.
  • update_recipe
    Edit name, settings, tags or the full ingredient list in place — ingredient lines support an "excluded" flag to keep an ingredient listed but out of all calculations (e.g. infusions). Pass the revision from get_recipe as expected_revision and the update is refused, not saved over, when the recipe was edited elsewhere since.
  • import_recipe
    Import one external recipe the assistant has already structured: preview each ordered ingredient line, then atomically save its description, phases, line notes, optional process stages, and all source step-by-step instructions as recipe notes. Weak (similar-name) matches for a line are never used without your confirmation.
  • delete_recipe
    Delete a recipe — requires confirmation.
Ingredients
  • search_ingredients
    Search your custom items + the global library. Returns composition, allergens and any mass left unaccounted by the recorded components; ask for the full view to add carbohydrates and the reference-data source. Similar names are marked weak and listed after the matches. Falls back to USDA/CIQUAL reference foods when nothing matches.
  • resolve_ingredients
    Match a whole list of recipe ingredient names to library ids in one call. A name the library does not hold comes back as needs_create; rows that only resemble it (another percentage, a shared word) are marked weak and are never matched.
  • find_substitutes
    Ranked substitutes by composition, diet and flavour, each with composition, allergens and a ready-to-run swap; ask for the full view to add carbohydrates and the reference-data source.
  • create_ingredient
    Add a custom ingredient with full composition, including measured total polyols and each named polyol (erythritol, sorbitol, maltitol, isomalt, xylitol, mannitol, lactitol, glycerol), plus other substances the macro fields cannot hold (acids, cocoa alkaloids, leavening salts) via components. The reply reports any mass still unaccounted.
  • update_ingredient
    Patch only supplied fields of your custom ingredient; null resets a nullable value, so canonically derived fields may be recomputed; components replaces the whole other-substance map; unknown or protected fields are rejected.
Analysis & metrics
  • analyze_recipe
    Quality score, diagnosed issues, rule checks and suggested fixes.
  • get_recipe_metrics
    Water activity, shelf life, composition and nutrition — for a saved recipe or an ad-hoc ingredient list. Shelf life comes as the microorganisms that can grow at that water activity and the storage the product needs, with a reference day count. Every metric arrives with the target band for that calculator and style, and how far outside it the value sits.
  • simulate_changes
    Compare many formula variants in one call, without saving anything. Start from a saved recipe or an ad-hoc ingredient list; each scenario comes back as before/after deltas alongside the bands they are judged by, and says when the shelf-life class or the storage the product needs changes. Name the metrics you care about to add them.
  • show_card
    Show you one result as a visual card in Claude or ChatGPT: a recipe, its metrics, a scenario comparison or a quality scorecard. The other tools show no card, so the assistant can check as many variants as it needs and show you only the one it presents.
Reference
  • advise_formulation
    When a metric will not come into range, report what the current ingredients can still reach and which class of ingredient would unlock the rest. It suggests no recipe and makes no trade-off for you.
  • get_calculator_guide
    Optimal ranges, the shelf-life water-activity classes, pro formulation rules and the settings schema per calculator; ask for a section to get the metric glossary or the process-graph template. Every style is listed with a sentence saying what it is, so you can pick one; pass it (sorbet, sauce, truffle…) and the ranges come back for that style, because they differ sharply between them. The process-graph template follows the style too and lists the steps that calculator runs.
Notes
  • list_recipe_notes
    Read the caveats and tips saved on a recipe, pinned first, a page at a time.
  • save_recipe_note
    Save a caveat, tip or rationale.
  • delete_recipe_note
    Delete a note — requires confirmation.
Collections
  • list_collections
    Browse your collections or public ones.
  • get_collection
    A collection with its member recipes, plus your private project instructions and requirements.
  • save_collection
    Create or update a collection, including its project instructions and requirements. New collections are private; sharing is changed in the app.
  • delete_collection
    Delete a collection — requires confirmation.
Stock & shopping lists
  • inventory_summary
    Ingredients running low against your reorder points, and stock batches about to expire.
  • list_stock
    What you have in stock: each ingredient with its total across lots, the nearest expiry and whether it is running low; searchable, up to 100 a page.
  • add_stock
    Add up to 20 lots you bought or received — ingredient, quantity and unit, with expiry, cost, supplier and lot number if you give them. All are added or none.
  • stock_check_recipes
    Can these recipes — or a whole collection — be made from current stock? Each recipe on its own and all of them together, with the shortfall per ingredient.
  • list_shopping_lists
    Your shopping lists, newest first, with what is still to buy on each.
  • get_shopping_list
    One shopping list in full — what to buy and what is checked off — up to 100 items a page.
Process graph (DAG)
  • get_recipe_dag
    Read a recipe's multi-stage process graph, including source notes and chef-facing instructions on each stage, plus a graph token for a safe write-back.
  • set_recipe_dag
    Author or replace the process graph, including source notes and chef-facing instructions on its stages; refuses to overwrite a graph that changed since it was read, and returns the recipe’s new revision for a following update_recipe.

Claude.ai web Recommended · no key

The easiest path. Formul.io is in the Claude connector directory, and Claude.ai runs the whole OAuth flow for you.

Open Formul.io in the Claude directory
  1. 1 Open the Formul.io listing in the Claude directory and connect it.
  2. 2 Claude.ai redirects you to Formul.io to authorize.
  3. 3 Log in if prompted, review the requested permissions, and click Allow.
  4. 4 Start a new chat and ask Formul.io something — see the example prompts below.

You can also add it by hand: in Settings → Connectors click Add custom connector, name it Formul.io and paste the MCP endpoint below. Leave OAuth Client ID and Secret blank — they are discovered automatically.

MCP endpoint
https://api.formul.io/mcp
Preview
Authorize Access

api.formul.io is requesting access to your Formul.io account.

Tokens will be sent to
https://claude.ai/api/mcp/auth_callback
Requested permissions
  • Run formulation calculations
  • Read your recipes
  • Create and modify your recipes
  • Search ingredient database
  • Create and modify ingredients
  • Diagnose recipe issues
  • Read your inventory and stock levels
  • Add lots to your stock
  • Read your shopping lists
Deny Allow
What the Formul.io authorization screen looks like — review the permissions, then Allow.

Claude Code, Codex, Cursor and other agents No key

Paste this prompt into your agent. It adds the Formul.io server, starts the sign-in and checks the connection. Your part is to sign in to Formul.io in the browser and click Allow.

Connect the Formul.io MCP server to yourself so I can use my Formul.io recipes, ingredients and calculators in this agent.

Server
- Name: formulio
- URL: https://api.formul.io/mcp (Streamable HTTP)
- Sign-in: OAuth in the browser. The server supports dynamic client registration, so no client ID, secret or API key is needed.
- Docs: https://formul.io/mcp

Before you run anything that opens a browser, tell me: a Formul.io page will open; I sign in or create a free account and click Allow.

1. Find out which client you are running in and add the server for my user (all projects), keeping every other entry in its config:
   - Claude Code: claude mcp add --transport http --scope user formulio https://api.formul.io/mcp
   - Codex CLI: codex mcp add formulio --url https://api.formul.io/mcp
   - Gemini CLI: gemini mcp add --scope user --transport http formulio https://api.formul.io/mcp
   - Cursor: in ~/.cursor/mcp.json add "formulio": { "url": "https://api.formul.io/mcp" } under "mcpServers"
   - VS Code: in the user mcp.json (command "MCP: Open User Configuration") add "formulio": { "type": "http", "url": "https://api.formul.io/mcp" } under "servers"
   - Any other client: use its documented way to add a remote Streamable HTTP MCP server with OAuth.
   If a server named formulio already exists, show me its config and ask before replacing it.
2. Start the sign-in and wait until I say it is done:
   - Claude Code: claude mcp login formulio
   - Codex CLI: codex mcp login formulio (skip it if adding the server already opened the browser)
   - Gemini CLI, Cursor, VS Code: tell me exactly what to run or click (Gemini: /mcp auth formulio; Cursor and VS Code: Connect or Start on the formulio entry).
   If the command cannot open a browser here and asks for a pasted URL, give me the exact command to run in my own terminal instead.
3. Check it works: call the formulio tool get_calculator_guide with calculator_type "ganache" and tell me in one sentence what came back. If the tools only appear in a new session, tell me to restart or open a new chat — that is the last step.
4. If something fails, show me the exact error and do not repeat the same attempt more than once. Do not change anything else on my machine.

For Claude.ai, Claude Desktop and ChatGPT, follow their own sections on this page.

Claude Desktop API key

For Claude Desktop or any client that uses a static bearer token.

1. Create an API key

Log in to Formul.io, open Settings → Security, and create an API key. Pick only the permissions you need:

  • Run formulation calculations
  • Read your recipes
  • Create and modify your recipes
  • Search ingredient database
  • Create and modify ingredients
  • Diagnose recipe issues
  • Read your inventory and stock levels
  • Add lots to your stock
  • Read your shopping lists
Copy the key immediately — it is shown only once.

2. Add it to your config

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "formulio": {
      "url": "https://api.formul.io/mcp",
      "headers": {
        "Authorization": "Bearer fio_YOUR_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop — the Formul.io tools appear in the tool list.

ChatGPT

For a custom connection, enable Developer mode in Settings → Security and login, if your account or workspace allows it. Open ChatGPT Plugins, select +, and add the MCP endpoint shown above. Complete the Formul.io sign-in and permission screen, then add the connection to a new conversation.

OpenAI connection instructions

Custom agents & OAuth 2.1

For your own MCP client or programmatic access. Authenticate with an API key (Bearer fio_…) or an OAuth 2.1 access token.

Transport

POST https://api.formul.io/mcp
JSON-RPC 2.0 over POST
GET https://api.formul.io/mcp
Unauthenticated server info

OAuth 2.1 endpoints

Use authorization_code with PKCE S256. Issuer: https://api.formul.io. Resource: https://api.formul.io/mcp — include it in authorize, token and refresh requests. Public clients use the none token authentication method. Access tokens last 15 minutes; each refresh replaces the old pair and starts a new 30-day refresh period.

Purpose URL
Discovery (RFC 8414) https://api.formul.io/.well-known/oauth-authorization-server
Authorization https://app.formul.io/oauth/authorize
Token exchange https://api.formul.io/api/v1/oauth/token
Client registration https://api.formul.io/api/v1/oauth/register
Token revocation https://api.formul.io/api/v1/oauth/revoke

Quick start

# 1. Register your client once
curl -X POST https://api.formul.io/api/v1/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "scope": ["calculate", "recipes:read", "ingredients:read"]
  }'
# Save the returned client_id. This is a public client with no client secret.

# 2. Send the user to authorize (PKCE, S256)
https://app.formul.io/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://myapp.example.com/callback
  &response_type=code
  &scope=calculate+recipes:read+ingredients:read
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.formul.io%2Fmcp
  &state=RANDOM_STATE

# 3. Exchange the code for tokens
curl -X POST https://api.formul.io/api/v1/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://myapp.example.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_VERIFIER" \
  --data-urlencode "resource=https://api.formul.io/mcp"
# -> { "access_token": "...", "refresh_token": "...", "expires_in": 900 }

# 4. Call the MCP server
curl -X POST https://api.formul.io/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Your data and connected assistants

An assistant can receive the recipe, ingredient, collection and calculation data returned by the tools it calls within your granted permissions. Its own privacy policy governs that copy. Disconnect it in the assistant’s settings to stop using the connection; API keys can be revoked in Formul.io Settings → Security. Disconnecting does not delete copies already held by the assistant.

Read the privacy policy

Scopes

Grant only what the assistant needs. If a tool needs an additional permission, the client can ask you to approve it while retaining your existing permissions. A subscription restriction is separate from OAuth permissions. Stock tools, inventory:read and inventory:write are available on accounts with Inventory enabled, shopping-list tools and shopping:read on accounts with Shopping enabled; the consent screen shows each of these permissions only then.

Scope Grants
recipes:read List and read recipes, collections, notes and process graphs.
recipes:write Create, edit and delete recipes, notes and collections; author process graphs.
ingredients:read Search the ingredient library and find substitutes.
ingredients:write Create and edit your custom ingredients.
calculate Run metrics and simulations, read calculator guides.
diagnose Analyse recipes — quality score, issues and fixes.
inventory:read Read your stock: low and expiring batches, and stock checks for recipes.
inventory:write Add lots you bought or received to your stock.
shopping:read Read your shopping lists.

Try these once connected

The assistant works against your own account.

What recipes do I have, and which has the shortest shelf life?
Diagnose my dark chocolate ganache and suggest how to improve its shelf life.
What's the water activity and sugar/fat split of my salted caramel?
Simulate raising the glucose in my ganache to 120 g — how does water activity change?
Find a vegan substitute for the cream in my recipe.
Create a free account

Troubleshooting

Why am I asked to authorize again?
An expired or revoked refresh token needs a new authorization. A refresh token expires after 30 days without a successful refresh; reusing an old rotated token revokes that connection’s chain. Additional permissions require your consent. Compatible server updates keep the same endpoint and token records.
The assistant connected but shows no tools.
Make sure authorization finished and you granted at least one scope. In Claude.ai, remove and re-add the connector; for an API key, confirm it has the permissions you need.
After authorizing, the browser doesn't return to my app.
For custom OAuth clients the redirect_uri must exactly match one you registered during client registration — including any trailing slash.
I'm getting rate-limited.
Free accounts get 1,000 tool calls per day and 100 per minute. Pro accounts get 20,000 per day and 120 per minute. Each call counts once. Normal conversations never come close to either tier — only a sweep across your whole library is worth spreading out.
The assistant won't delete a recipe or note.
That is deliberate. delete_recipe, delete_collection and delete_recipe_note require an explicit confirmation so nothing is removed by accident — tell the assistant to confirm.
I can't connect at all.
MCP access is governed by a global availability switch and may be briefly turned off for maintenance. Try again later, or email [email protected].

Need help?

This page is the canonical documentation for the Formul.io MCP server. Still stuck? We read every message.