Formul.io MCP Server

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, save recipe notes with save_recipe_note, and run the reviewed import. The other write tools — update_recipe, delete_recipe, delete_recipe_note, set_recipe_dag, save_collection, delete_collection, create_ingredient and update_ingredient — need Pro. Every call counts toward your plan’s rate limits.

Claude.ai web Recommended · no key

The easiest path. Claude.ai runs the whole OAuth flow for you.

1. 1 Open claude.ai and go to Settings → Connectors.
2. 2 Click Add custom connector.
3. 3 Name it Formul.io and paste the Remote MCP server URL below. Leave OAuth Client ID and Secret blank — they are discovered automatically.
4. 4 Click Add. Claude.ai redirects you to Formul.io to authorize.
5. 5 Log in if prompted, review the requested permissions, and click Allow.
6. 6 Start a new chat and ask Formul.io something — see the example prompts below.

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

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.

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

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.

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.

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.

Try these once connected

The assistant works against your own account.

Troubleshooting