NutriRef provides pay-per-call access to USDA FoodData Central nutrition data for AI agents via USDC micropayments on Base mainnet — no traditional API keys required.
Search for foods (nutrition_search, $0.001/call): Find foods by free-text query (e.g., "banana", "chicken breast"). Returns fdc_id, description, brand owner, and macro summary (calories, protein, carbs, fat per 100g).
Get detailed nutrition profiles (nutrition_detail, $0.002/call): Retrieve a full per-100g breakdown for a specific food by fdc_id, covering 13 nutrients: calories, protein, fat, carbs, fiber, sugar, sodium, cholesterol, saturated fat, vitamin C, calcium, iron, and potassium.
Compare multiple foods (nutrition_compare, $0.003/call): Compare 2–5 foods side by side, with per-nutrient winners (e.g., highest protein, lowest sodium).
Analyze recipe nutrition totals (nutrition_recipe, $0.005/call): Calculate combined nutrition for a multi-ingredient recipe by specifying each ingredient's fdc_id and weight in grams; values are scaled and summed.
The server integrates natively with MCP-enabled AI agents like Claude and can be self-hosted locally via Docker Compose using a free USDA API key.
Provides payment facilitation for the NutriRef nutrition data API using Coinbase Developer Platform for USDC micropayments on Base.
Pay-per-call USDA nutrition data for AI agents. Structured FoodData Central via the x402 micropayment protocol — agents pay $0.001–$0.005 in USDC per request, no signup, no API keys, no human auth flows.
Live at https://nutriref.xyz. Spec at /openapi.json · Swagger at /docs · Bazaar discovery at /.well-known/x402.
Method | Path | Price | Cache |
|
| $0.001 | 24h |
|
| $0.002 | 7d |
|
| $0.003 | derived |
|
| $0.005 | derived |
All values per 100g. Missing nutrients are null, not 0. compare returns per-nutrient winners (highest protein, lowest sodium, etc.). recipe scales by grams and sums.
Related MCP server: Nutrition By Api Ninjas MCP Server
NutriRef ships an MCP server that exposes the four endpoints as native tools. Install it from PyPI:
pip install nutriref-mcpThen add this to your MCP client config (Claude Desktop's claude_desktop_config.json, Claude Code's MCP settings, etc.):
{
"mcpServers": {
"nutriref": {
"command": "nutriref-mcp",
"env": {
"PAYER_PRIVATE_KEY": "0x...your-funded-wallet-key...",
"NUTRIREF_BASE_URL": "https://nutriref.xyz"
}
}
}
}Prefer not to install? Use
uvx nutriref-mcpas thecommandto run it on demand. To work from a clone instead,pip install -e ".[mcp]"and setcommandtopythonwithargs: ["-m", "mcp_server"].
The wallet needs USDC on Base mainnet — gas is sponsored by the facilitator, so you only need stablecoin balance. The agent now has nutrition_search, nutrition_detail, nutrition_compare, nutrition_recipe and auto-pays per call.
Unpaid requests get 402 Payment Required with x402 payment instructions. Any x402-aware client signs a gasless USDC authorization (EIP-3009) and retries automatically:
import asyncio
from eth_account import Account
from x402.client import x402Client
from x402.http.clients.httpx import wrapHttpxWithPayment
from x402.mechanisms.evm.exact import register_exact_evm_client
account = Account.from_key("0x...funded-wallet-key...")
client = x402Client(); register_exact_evm_client(client, account)
async def main():
async with wrapHttpxWithPayment(client, base_url="https://nutriref.xyz") as http:
r = await http.get("/v1/nutrition/detail/2012128")
print(r.json())
asyncio.run(main())GET /v1/nutrition/detail/173944:
{
"fdc_id": 173944,
"description": "Banana, raw",
"data_type": "Foundation",
"serving_size": 100, "serving_size_unit": "g",
"calories": 89.0, "protein": 1.1, "fat": 0.3,
"carbs": 22.8, "fiber": 2.6, "sugar": 12.2,
"sodium": 1.0, "cholesterol": null, "saturated_fat": 0.1,
"vitamin_c": 8.7, "calcium": 5.0, "iron": 0.3, "potassium": 358.0
}NutriRef is open source; the live instance at nutriref.xyz is one deployment among many possible. To run your own:
cp .env.example .env
# fill in USDA_API_KEY (free at https://fdc.nal.usda.gov/api-key-signup.html)
# and X402_RECEIVER_ADDRESS (an EVM address that should receive payments)
docker compose up --build
curl http://localhost:8000/healthVar | Required | Default | Purpose |
| yes | — | Free key from fdc.nal.usda.gov |
| no |
| |
| no |
| Response cache |
| no |
|
|
| yes | — | EVM address that receives USDC |
| no |
|
|
| mainnet only | — | Coinbase Developer Platform key ID |
| mainnet only | — | Coinbase Developer Platform key secret |
| no |
|
For mainnet you need a Coinbase CDP account and the public x402 facilitator at https://api.cdp.coinbase.com. Testnet works for free with the community facilitator at https://x402.org/facilitator.
agent → x402 middleware → route handler → cache (Redis) → USDA FDC APIsearch and detail cache USDA responses directly. compare and recipe compose from the cached detail data — no extra USDA calls when warm. The cache is a meaningful cost lever: warm requests return in <50ms and never hit USDA.
pip install -e ".[dev]"
pytestexamples/meal-planner/ is a complete, ~150-line agent that gives Claude
the four NutriRef endpoints as tools and asks it to plan a day of meals
hitting a calorie/protein goal. Worth reading if you're wiring NutriRef
into your own agent — the tool schemas and the payment loop are all
there. See examples/meal-planner/README.md.
app/ # FastAPI service
main.py # app factory + x402 init
routes/ # search, detail, compare, recipe
landing.py # / (public landing page)
discovery.py # /.well-known/x402, /llms.txt, /.well-known/ai-plugin.json, /logo.svg
usda.py # async USDA client
cache.py # Redis wrapper
normalize.py # USDA → flat 13-nutrient schema
mcp_server/ # MCP server wrapper for agent use
examples/ # worked agent examples (meal planner)
scripts/ # CDP wallet bootstrap + payer-side test
tests/ # pytest + respx + fakeredisUSDA FoodData Central for the data.
x402 for the payment protocol.
fastapi-x402 for the server middleware (with a small EIP-712 patch we apply at startup for Base mainnet USDC).
Compare 2 to 5 foods side by side. Use this when the user asks "which is healthier," "which has more protein," or any cross-food comparison — it's cheaper and clearer than calling nutrition_detail multiple times. Returns each food's full nutrition plus per-nutrient winners (highest protein, lowest sodium, etc.). Charges $0.003 USDC per call.
Args: fdc_ids: 2 to 5 USDA FDC IDs to compare.
| Name | Required | Description | Default |
|---|---|---|---|
| fdc_ids | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses pricing ($0.003 USDC per call) and return format (full nutrition plus per-nutrient winners). However, it does not mention error handling or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences plus a parameter line. It front-loads the purpose, then gives usage guidance, then return and pricing. No wasteful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (likely detailed), the description adequately covers inputs, purpose, return summary, and pricing. It is complete for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does so by explaining that fdc_ids are USDA FDC IDs and must be between 2 and 5, adding critical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'compare' with resource 'foods' and constraints '2 to 5'. It distinguishes from siblings by noting it's cheaper and clearer than calling nutrition_detail multiple times.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('when the user asks which is healthier, which has more protein, or any cross-food comparison') and why it's better (cheaper and clearer than alternatives). It also names the alternative tool nutrition_detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full per-100g nutrition profile for one specific food. Use this when you have an fdc_id (from nutrition_search) and the user needs micronutrients beyond just calories/protein/carbs/fat. Returns all 13 tracked nutrients: calories, protein, fat, carbs, fiber, sugar, sodium, cholesterol, saturated_fat, vitamin_c, calcium, iron, potassium. Missing nutrients are null, not 0. Charges $0.002 USDC per call.
Args: fdc_id: USDA FoodData Central ID, obtained from nutrition_search.
| Name | Required | Description | Default |
|---|---|---|---|
| fdc_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behaviors: missing nutrients return null not 0, and cost per call. However, no annotations exist to cover safety or side effects. Lacks details on authentication or error handling, but sufficient for expected use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with clear purpose, usage, and return details. While slightly long due to the nutrient list, it is efficiently structured and front-loaded. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but mentioned), description explains return values. It covers parameter source, cost, and missing nutrient handling. Sufficient for a single-parameter look-up tool with no complex workflows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema only says fdc_id is integer required. Description adds essential context: it is a USDA FoodData Central ID obtained from nutrition_search, which is critical for correct usage. With 0% schema coverage, description compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets the full per-100g nutrition profile for one food using an fdc_id. Distinguishes itself from siblings like nutrition_search, nutrition_compare, and nutrition_recipe by specifying its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('when user needs micronutrients beyond calories/protein/carbs/fat') and that fdc_id comes from nutrition_search. Also mentions cost per call, giving clear usage policy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sum nutrition across a recipe of weighted ingredients. Use this for meal planning, recipe analysis, or any "what are the totals if I combine X grams of A with Y grams of B" task. Each food's per-100g nutrition is scaled by grams/100 then summed. Charges $0.005 USDC per call.
Args: ingredients: List of {"fdc_id": int, "grams": float} pairs. At least one; weights in grams.
| Name | Required | Description | Default |
|---|---|---|---|
| ingredients | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the scaling and summation logic. Discloses pricing but does not mention rate limits or error handling. Overall transparent for a pure computation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
4 sentences, each valuable: purpose, usage examples, technical detail, parameter spec. Front-loaded with key info, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description covers purpose, usage, parameter, cost, and computation. Missing error scenarios but adequate for a single-param tool with good structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0% means description is crucial. It specifies ingredient list must contain fdc_id (int) and grams (float) pairs, min length 1, and weights in grams. This fully compensates for the vague schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool sums nutrition across weighted ingredients, with specific verb 'Sum' and resource 'nutrition across a recipe'. It distinguishes from siblings (compare, detail, search) by focusing on aggregation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: meal planning, recipe analysis, combining ingredients. Mentions cost per call. Lacks explicit when-not-to-use or direct comparison to siblings, but usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find foods in the USDA FoodData Central database by free-text name. Use this FIRST when the user mentions a food by name and you need its fdc_id for any of the other nutrition_* tools. Returns ranked matches with fdc_id, description, brand_owner, and a quick macro summary (calories/protein/carbs/fat per 100g). Charges $0.001 USDC per call.
Args: q: Free-text food name (e.g. "banana", "greek yogurt", "chicken breast"). limit: Max results to return, 1-50. Default 10. Use a small limit unless you need to browse.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses that results are 'ranked matches', lists returned fields, and mentions the cost ($0.001 per call). It does not mention any mutability, rate limits, or auth needs, which are less critical for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the main purpose in the first sentence. The description is brief (5 sentences) and well-structured, with clear separation of parameter guidance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (a free-text search with one required parameter) and the presence of an output schema (mentioned but not shown), the description is complete. It covers purpose, usage flow, cost, and parameter details, leaving no obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains 'q' as 'Free-text food name' with examples, and 'limit' with default value (10) and valid range (1-50), adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds foods in the USDA FoodData Central database by free-text name and explains its primary use case: getting fdc_id for other nutrition tools. It explicitly distinguishes from siblings by positioning it as the first step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this FIRST when the user mentions a food by name', providing clear context for when to use it. It implies alternatives (other nutrition_* tools) but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.2nutrition_comparenutrition_detailnutrition_recipenutrition_searchEach tool has a clear, distinct purpose: search for foods, get detailed nutrition for one food, compare multiple foods, and sum recipe nutrition. No overlapping functionality.
All tools follow a consistent 'nutrition_' prefix with descriptive verbs/nouns (search, detail, compare, recipe), making the naming pattern predictable and clear.
Four tools is well-scoped for a nutrition database server, covering essential operations without redundancy or excessive overhead.
The set covers the full lifecycle of working with USDA food data: search, retrieve details, compare, and aggregate recipe totals. No obvious gaps for typical use cases.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Pay-per-call data APIs for AI agents. USDC on Base via x402. 33 tools, no signup.
Pay-per-call crypto market intelligence for AI agents. USDC on Base via x402.
x402 paid APIs for AI agents on Base. Blockchain, wallet, DEX, crypto, web search.
Pay-per-call data tools for AI agents: crypto signal, web reader, SEO audit. x402 USDC on Base.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Younghef/nutriref-api'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
