usda-mcp-server

Name: usda-mcp-server
Author: cyanheads

Server Details

Search foods, compare nutrients, and look up the full USDA FoodData Central database.

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.

Status: Healthy
Uptime: 99.9% over 76 days
Last Tested: 2026-11-02 09:59
Transport: Streamable HTTP · MCP 2025-11-25
URL
Repository: cyanheads/usda-mcp-server
GitHub Stars: 1
Server Listing: usda-mcp-server

TDQS

A4.5/5.0

Scored 2026-10-26 08:00 across 5 tools

Disambiguation5/5

Each tool targets a distinct operation: discovery (search_foods), single retrieval (get_food), batch retrieval (get_foods), formatted side-by-side comparison (compare_foods), and reference-table lookup (list_nutrients). The main risk area — get_foods vs compare_foods — is explicitly resolved in the descriptions ("For side-by-side comparison with a formatted table, use usda_compare_foods instead"). No two tools appear to do the same thing.

Naming Consistency5/5

All names follow a uniform usda_<verb>_<noun> snake_case convention with a consistent prefix. The singular/plural distinction (get_food vs get_foods) is principled and readable. No mixed conventions anywhere.

Tool Count5/5

Five tools is tightly scoped for a food-data API: one each for search, single fetch, batch fetch, comparison, and nutrient ID lookup. Every tool earns its place, and none feel redundant or missing for the core workflow.

Completeness4/5

The core lifecycle — discover IDs, fetch profiles, batch fetch, compare, resolve nutrient IDs — is fully covered with sensible defaults. Minor gaps exist, such as no dedicated tool for finding foods by nutrient criteria (e.g., "highest iron foods") or listing data types/categories, but agents can work around these via search keywords.

Available Tools

5 tools

usda_compare_foodsCompare USDA FoodsA

Read-only

Inspect

Compare nutrients side-by-side for 2–5 foods. Returns a structured table — one row per nutrient, one column per food — formatted as markdown. Best for "spinach vs kale iron" or "which has more protein?" questions. Omit nutrients[] to use the 12 most common defaults (energy, protein, fat, saturated fat, carbs, fiber, sugars, sodium, potassium, calcium, iron, vitamin C); provide nutrients[] with specific FDC IDs to compare different nutrients. All values are scaled to the same basis, quantity in unit: default 100 g, so unit="oz" alone compares per 100 oz and quantity alone is grams. If one or more FDC IDs are not found, the comparison proceeds with the valid foods — only throws too_few_foods when fewer than 2 IDs return data.

Name	Required	Description	Default
`unit`	No	Unit for quantity. Default "g". Does not support "serving" (each food's portion weight differs, so a serving basis would not compare equal amounts).	g
`fdcIds`	Yes	FDC IDs to compare — 2 to 5 foods. Use usda_search_foods to discover IDs.
`quantity`	No	Amount of food, in unit, that every value is scaled to. Must be positive. Default 100.
`nutrients`	No	Nutrient IDs to include in the comparison. Defaults to the 12 most common: energy (1008), protein (1003), total fat (1004), saturated fat (1258), carbohydrate (1005), fiber (1079), total sugars (2000), sodium (1093), potassium (1092), calcium (1087), iron (1089), vitamin C (1162). Use usda_list_nutrients to look up other IDs.

Output Schema

Name	Required	Description
`basis`	No	The common scaling basis applied to all nutrient values.
`error`	No	Present when the call failed. Absent on success.
`foods`	No	The compared foods, in the same order as the values arrays below.
`nutrients`	No	Nutrient rows — one entry per requested nutrient, with per-food values in the values[] array.
`missingData`	No	Foods or food+nutrient pairs where data was unavailable. Absent when all data was present.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare a safe read (readOnlyHint=true, openWorldHint=false), and the description goes well beyond by disclosing the return format (markdown table, one row per nutrient, one column per food), the equal-basis scaling rule, and graceful partial-failure behavior including the specific too_few_foods error condition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return format, then behavior, then parameters — good ordering. It is dense and the unit/quantity sentence is slightly convoluted, but nearly every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and rich annotations, the description covers what the schema cannot: comparison semantics, defaults, scaling, and partial-failure behavior. Nearly complete; a hint on result ordering or limits would close the last gap, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds genuinely non-obvious meaning: the unit/quantity interaction ('unit="oz" alone compares per 100 oz and quantity alone is grams') clarifies a scaling rule the schema does not spell out, and it enumerates the default nutrient set and the FDC-ID route for custom nutrients.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Compare nutrients side-by-side for 2–5 foods') plus the return shape. It implicitly distinguishes itself from discovery siblings by pointing to usda_search_foods and usda_list_nutrients for ID lookup, so an agent knows this is the comparison step, not a lookup step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete example questions ('spinach vs kale iron', 'which has more protein?') that define when to use it, and specifies behavior for omitting vs. providing nutrients[]. It also names the discovery tools to use beforehand, leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

usda_get_foodGet USDA FoodA

Read-only

Inspect

Get the full nutrient profile for one food by FDC ID. Returns all available nutrients (or a filtered subset via the nutrients[] param) with optional per-portion scaling. Use usda_search_foods to discover FDC IDs. Provide unit, optionally with quantity, to scale all nutrient values from per-100g to that amount (e.g. quantity=200, unit="g" → per-200g values). quantity defaults to 100 for g, oz, lb, and kg and to 1 for serving. Serving uses the first valid portion, or a positive finite Branded label size in g/GRM/GM (case-insensitive) when no portion exists; quantity multiplies that weight. Other label units require an explicit mass-unit request. quantity without unit is rejected. Narrow nutrients[] to specific IDs to reduce response size for focused queries.

Name	Required	Description
`unit`	No	Unit for quantity. "serving" uses the first valid portion weight, or a Branded label size in g/GRM/GM (case-insensitive) when no portion exists, multiplied by quantity. Required when quantity is provided. Given alone, scales to 100 g, oz, lb, or kg, or to 1 serving.
`fdcId`	Yes	FDC ID of the food. Use usda_search_foods to discover IDs.
`quantity`	No	Amount of food, in unit, to scale nutrient values to. Must be positive. Requires unit. Defaults to 100 when unit is g, oz, lb, or kg, and to 1 when unit is "serving". Omit both quantity and unit for per-100g values (FDC database native basis).
`nutrients`	No	Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008] for protein, fat, carbs, energy). Use usda_list_nutrients to look up IDs. Omit to return all available nutrients.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`fdcId`	No	FDC ID of the food.
`dataType`	No	FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded.
`scaledTo`	No	Scaling basis when unit was provided. Absent when returning per-100g values.
`brandName`	No	Brand name. Branded items only.
`nutrients`	No	Nutrient values for this food, per 100g or scaled to the scaledTo basis.
`brandOwner`	No	Brand owner. Branded items only.
`allPortions`	No	All named portions for this food.
`description`	No	Full USDA food name (e.g. "Chicken, broilers or fryers, breast, meat only, raw").
`ingredients`	No	Ingredient list from label. Branded items only.
`servingInfo`	No	First available portion definition, or a Branded gram-label serving identified in its description.
`foodCategory`	No	USDA food category (e.g. "Poultry Products"). Absent for some branded items.
`publicationDate`	No	Date this food entry was published in FDC.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint=false, and the description adds real behavioral detail on top: per-100g native basis, scaling defaults per unit, serving fallback logic, and the hard validation rule that 'quantity without unit is rejected.' It stops short of describing error behavior for an unknown fdcId, but the added context is substantial.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the discovery alternative, then scaling semantics. It is dense and the serving-fallback sentence is long and partially duplicates the schema's unit description, but nearly every clause carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description needn't explain return values, and it covers scaling, filtering, defaults, and one validation failure. The only gap is behavior on an invalid or nonexistent FDC ID, which is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds a worked example (quantity=200, unit="g" → per-200g values) and restates the default-per-unit rule in the context of the whole call, which helps an agent reason about the unit/quantity pair together rather than in isolation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Get the full nutrient profile for one food by FDC ID.' The singular 'one food' plus the named sibling usda_search_foods makes it distinguishable from usda_get_foods and usda_compare_foods without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to usda_search_foods for ID discovery and to usda_list_nutrients for nutrient IDs, and advises narrowing nutrients[] for focused queries. It does not, however, state when to prefer this over the singular-vs-batch sibling usda_get_foods, so one comparison is left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

usda_get_foodsGet USDA Foods (Batch)A

Read-only

Inspect

Fetch nutrient profiles for 2–20 foods in a single API call. More efficient than calling usda_get_food N times when you already have multiple FDC IDs. All values are per 100g (no portion scaling). Use the nutrients[] filter to limit response size — strongly recommended for batch calls. For side-by-side comparison with a formatted table, use usda_compare_foods instead. Failed IDs (not found or no data) are reported in the failed[] array rather than aborting the entire batch.

Name	Required	Description	Default
`fdcIds`	Yes	FDC IDs to fetch — 2 to 20 IDs. Use usda_search_foods to discover IDs.
`nutrients`	No	Filter to specific nutrient IDs (e.g. [1003, 1004, 1005, 1008]). Strongly recommended — full profiles can be large. Use usda_list_nutrients to look up IDs.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`foods`	No	Successfully fetched foods.
`failed`	No	IDs that returned no data. Check these with usda_search_foods to verify they exist.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses key behavioral details: values are per 100g with no portion scaling, and failed IDs are returned in a failed[] array rather than aborting the batch. It also strongly recommends the nutrients filter to limit response size. This adds meaningful context beyond annotations and does not contradict them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, each carrying essential information: core purpose, efficiency rationale, unit context, filter recommendation, alternative routing, and failure behavior. No redundancy; front-loaded with the primary action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the critical aspects: batch scope, units, failure handling, and recommended filter. An output schema exists (which would explain the success response shape), so its absence here is acceptable. Minor gaps like rate limits or behavior when all IDs fail are not covered, but these are not essential for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters are fully described in the schema (100% coverage), so the baseline is 3. The description reinforces the nutrients recommendation and adds efficiency context, but does not introduce additional format or semantic details for the parameters beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Fetch'), resource ('nutrient profiles'), and scope ('2–20 foods in a single API call'). It explicitly distinguishes itself from siblings by noting efficiency over usda_get_food and directing to usda_compare_foods for formatted tables, and references usda_search_foods and usda_list_nutrients for ID discovery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly tells when to use this tool (batch of multiple FDC IDs, more efficient than repeated calls) and points to an alternative (usda_compare_foods for side-by-side tables). It also reinforces the recommended nutrients filter and warns against large responses. The 2–20 range is stated explicitly, covering the main constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

usda_list_nutrientsList USDA NutrientsA

Read-only

Inspect

Look up the FDC nutrient reference table — all tracked nutrients with their numeric IDs, names, SR reference numbers, units, and categories. Use to resolve a nutrient name (e.g. "vitamin C") to its FDC ID (1162) before passing it to the nutrients[] filter on other tools. Filter by category (macronutrients, vitamins, minerals, lipids, amino_acids, or other) to narrow results. The data is static — call once and reuse the IDs.

Name	Required	Description	Default
`category`	No	Filter to a nutrient category. Omit to return all ~150 tracked nutrients. Options: macronutrients, vitamins, minerals, lipids, amino_acids, other.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`nutrients`	No	Nutrient reference entries matching the requested category, or all if category is omitted.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide readOnlyHint=true and openWorldHint=false, so the description doesn't need to cover safety. It adds useful behavioral context: the data is static, so results can be cached and reused. This goes beyond the annotations and helps the agent plan calls efficiently.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each with a distinct purpose: what it does, how to use it, and a caching hint. The most important information (purpose and usage) is front-loaded, followed by a practical note. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with only one optional parameter and an output schema, the description is complete. It covers the purpose, usage context, filtering options, and data characteristics. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of the parameters, with a clear enum and description for 'category'. The description repeats the enum options and adds 'narrow results', but doesn't add new meaning beyond the schema. Baseline of 3 applies since schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Look up') and resource ('the FDC nutrient reference table'), and specifies exactly what it returns (numeric IDs, names, SR reference numbers, units, categories). It distinguishes itself from the food-related siblings by focusing on nutrients, and even provides a concrete example ('vitamin C' → 1162).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use to resolve a nutrient name ... before passing it to the nutrients[] filter on other tools,' which gives clear when-to-use guidance. It also suggests filtering by category and notes the static nature ('call once and reuse'). It doesn't explicitly mention when not to use it, but the context with siblings makes the differentiation obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

usda_search_foodsSearch USDA FoodsA

Read-only

Inspect

Search USDA FoodData Central foods by keyword. Returns matching foods with FDC IDs and available preview nutrients: protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048), preserving distinct energy estimates. Missing nutrients are omitted. Use the returned fdcId with usda_get_food for other nutrients or the full profile, or usda_compare_foods for side-by-side comparisons. When dataType is omitted, defaults to SR Legacy (common whole foods with complete profiles) — or to Branded when brandOwner is set, since only Branded records carry one. Set dataType to ["Branded"] for packaged products, or include a UPC/GTIN code as the query. Pass brandOwner (e.g. "General Mills") to narrow branded results.

Name	Required	Description
`query`	Yes	Search terms — food name, ingredient, or UPC/GTIN code for branded products. Examples: "chicken breast raw", "banana", "012345678901". FDC reads Lucene syntax: "quoted phrases", +required and -excluded terms, AND/OR/NOT, wildcards (chick), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick./), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters.
`dataType`	No	FDC data sources to search. Omitting this defaults to ["SR Legacy"] (common whole foods, complete nutrient profiles), or to ["Branded"] when brandOwner is set. Include "Branded" for packaged products. Multiple values allowed.
`pageSize`	No	Number of results per page. Default 10, maximum 50.
`brandOwner`	No	Filter branded results by brand owner name (e.g. "General Mills", "Kraft"). Only Branded records carry one, so setting this defaults dataType to ["Branded"] unless dataType is given explicitly.
`pageNumber`	No	Page number (1-based). Use with totalPages to paginate. Pages past the end return empty foods with a notice when the query has matches.
`foodCategory`	No	Filter by USDA food category (e.g. "Poultry Products", "Vegetables and Vegetable Products"). Case-sensitive.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`foods`	No	Foods matching the search query.
`notice`	No	Guidance for a requested page beyond the available range.
`totalHits`	No	Total number of foods matching the query across all pages.
`totalCount`	No	Total foods matching the query across all pages.
`totalPages`	No	Total number of pages available.
`currentPage`	No	Current page number (1-based); the requested page for exhausted pages.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint; the description adds real behavioral detail — which nutrients are returned with their IDs, that missing nutrients are omitted, and that distinct energy estimates are preserved rather than collapsed. It also explains the dataType defaulting rule and how it interacts with brandOwner, which is non-obvious. It stops short of mentioning rate limits, error behavior, or result caps beyond pagination.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return shape, then routing guidance, then filter hints — a sensible order with no filler sentences. It runs a bit long and duplicates schema-level facts about dataType defaults, costing some tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter search tool with an output schema and read-only annotations, the description covers what an agent needs: what is searched, what is returned, what defaults apply, and which sibling to call next. Nothing required for a correct first call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries parameter meaning, and most of the description's parameter text (dataType defaulting, brandOwner interaction, UPC-as-query) restates the schema verbatim. The one added nuance — that query strings support Lucene syntax and that URLs/slashes/quotes are treated literally — is already fully documented in the query schema description. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search USDA FoodData Central foods by keyword") and immediately scopes what comes back (FDC IDs plus preview nutrients). It also names the sibling tools it is not — usda_get_food for full profiles and usda_compare_foods for side-by-side — so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance: this tool for lookup, usda_get_food when other nutrients or a full profile are needed, usda_compare_foods for comparisons. It also spells out selection rules for the optional filters (set dataType to ["Branded"] for packaged products, pass a UPC/GTIN as the query, use brandOwner to narrow branded results).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesOct 26, 2026

Changedusda_get_food5 fields changed

changedInput schema / properties / unit / description

Previous value: -"Unit for quantity. \"serving\" is the food's first defined portion weight, multiplied by quantity. Required when quantity is provided. Given alone, scales to 100 g, oz, lb, or kg, or to 1 serving."New value: +"Unit for quantity. \"serving\" uses the first valid portion weight, or a Branded label size in g/GRM/GM (case-insensitive) when no portion exists, multiplied by quantity. Required when quantity is provided. Given alone, scales to 100 g, oz, lb, or kg, or to 1 serving."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The FDC ID does not exist in the database. `quantity_without_unit`: quantity is provided but unit is omitted. `no_portion_data`: unit=\"serving\" was requested but the food has no portion data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The FDC ID does not exist in the database. `quantity_without_unit`: quantity is provided but unit is omitted. `no_portion_data`: unit=\"serving\" was requested but the food has no valid portion or supported Branded gram-label serving. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / scaledTo / properties / gramWeight / description

Previous value: -"Gram weight resolved from quantity and unit (for serving, quantity × the first portion weight) — all nutrient values are per this many grams."New value: +"Gram weight resolved from quantity and unit (for serving, quantity × servingInfo.gramWeight) — all nutrient values are per this many grams."

changedOutput schema / properties / servingInfo / description

Previous value: -"First available portion definition, if present."New value: +"First available portion definition, or a Branded gram-label serving identified in its description."

changedOutput schema / properties / servingInfo / properties / description / description

Previous value: -"Portion description (e.g. \"1 cup\", \"4 oz\")."New value: +"Portion description, or label-serving provenance with source size, unit and available household text."

Changedusda_search_foods5 fields changed

changedInput schema / properties / pageNumber / description

Previous value: -"Page number (1-based). Use with totalPages to paginate."New value: +"Page number (1-based). Use with totalPages to paginate. Pages past the end return empty foods with a notice when the query has matches."

changedOutput schema / properties / currentPage / description

Previous value: -"Current page number (1-based)."New value: +"Current page number (1-based); the requested page for exhausted pages."

changedOutput schema / properties / foods / items / properties / nutrients / description

Previous value: -"Preview nutrients per 100g — typically energy, protein, fat, carbs for SR Legacy. Not a complete profile; use usda_get_food for the full set."New value: +"Available preview nutrients per 100g: protein (1003), fat (1004), carbohydrate (1005), fiber (1079), and energy (1008, 1062, 2047, 2048). Source order, values and distinct energy estimates are preserved. Missing entries are omitted; use usda_get_food for other nutrients."

changedOutput schema / properties / foods / items / properties / servingSizeUnit / description

Previous value: -"Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\", \"MG\"). Branded only."New value: +"Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\", \"GM\", \"MG\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\"). Branded only."

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance for a requested page beyond the available range.",
+  "type": "string"
+}

3 tool updatesOct 25, 2026

Changedusda_compare_foods5 fields changed

changedInput schema / properties / quantity / description

Previous value: -"Gram basis for comparison. All values scaled to this amount. Must be positive. Default 100."New value: +"Amount of food, in unit, that every value is scaled to. Must be positive. Default 100."

changedInput schema / properties / unit / description

Previous value: -"Unit for quantity. Default \"g\". Does not support \"serving\" (use a fixed gram basis for consistent comparison)."New value: +"Unit for quantity. Default \"g\". Does not support \"serving\" (each food's portion weight differs, so a serving basis would not compare equal amounts)."

changedOutput schema / properties / basis / properties / gramWeight / description

Previous value: -"Gram weight resolved from quantity+unit — all nutrient values are per this many grams."New value: +"Gram weight resolved from quantity and unit — all nutrient values are per this many grams."

changedOutput schema / properties / basis / properties / quantity / description

Previous value: -"Numeric quantity provided in the request."New value: +"Quantity applied, in unit — the requested value or the default 100."

changedOutput schema / properties / basis / properties / unit / description

Previous value: -"Unit provided in the request (g, oz, lb, or kg)."New value: +"Unit applied (g, oz, lb, or kg) — the requested value or the default \"g\"."

Changedusda_get_food7 fields changed

changedInput schema / properties / quantity / description

Previous value: -"Amount of food to scale nutrient values to. Must be positive. When provided, unit is required. Omit for per-100g values (FDC database native basis)."New value: +"Amount of food, in unit, to scale nutrient values to. Must be positive. Requires unit. Defaults to 100 when unit is g, oz, lb, or kg, and to 1 when unit is \"serving\". Omit both quantity and unit for per-100g values (FDC database native basis)."

changedInput schema / properties / unit / description

Previous value: -"Unit for quantity. \"serving\" uses the food's first defined portion weight. Required when quantity is provided."New value: +"Unit for quantity. \"serving\" is the food's first defined portion weight, multiplied by quantity. Required when quantity is provided. Given alone, scales to 100 g, oz, lb, or kg, or to 1 serving."

changedOutput schema / properties / nutrients / description

Previous value: -"Nutrient values for this food, per 100g or scaled to the requested quantity."New value: +"Nutrient values for this food, per 100g or scaled to the scaledTo basis."

changedOutput schema / properties / nutrients / items / properties / amount / description

Previous value: -"Nutrient amount — per 100g, or scaled to quantity+unit if provided."New value: +"Nutrient amount — per 100g, or per scaledTo.gramWeight when unit is provided."

changedOutput schema / properties / scaledTo / description

Previous value: -"Scaling basis when quantity+unit were provided. Absent when returning per-100g values."New value: +"Scaling basis when unit was provided. Absent when returning per-100g values."

changedOutput schema / properties / scaledTo / properties / gramWeight / description

Previous value: -"Gram weight resolved from quantity+unit — all nutrient values are per this many grams."New value: +"Gram weight resolved from quantity and unit (for serving, quantity × the first portion weight) — all nutrient values are per this many grams."

changedOutput schema / properties / scaledTo / properties / quantity / description

Previous value: -"Numeric quantity provided in the request."New value: +"Quantity applied — the requested value, or the default for unit (100 for g, oz, lb, kg; 1 for serving)."

Changedusda_search_foods5 fields changed

changedInput schema / properties / query / description

Previous value: -"Search terms — food name, ingredient, or UPC/GTIN code for branded products. Examples: \"chicken breast raw\", \"banana\", \"012345678901\"."New value: +"Search terms — food name, ingredient, or UPC/GTIN code for branded products. Examples: \"chicken breast raw\", \"banana\", \"012345678901\". FDC reads Lucene syntax: \"quoted phrases\", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `query_syntax`: FDC rejected the query syntax, e.g. a dangling operator or a trailing backslash. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "query_empty",
-  "no_results"
-]New value: +[
+  "query_empty",
+  "query_syntax",
+  "no_results"
+]

changedOutput schema / properties / foods / items / properties / servingSize / description

Previous value: -"Serving size in grams from the product label. Branded only."New value: +"Serving size from the product label, in servingSizeUnit. Branded only."

changedOutput schema / properties / foods / items / properties / servingSizeUnit / description

Previous value: -"Unit for servingSize (usually \"g\"). Branded only."New value: +"Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\", \"MG\"). Branded only."

1 tool updateSep 16, 2026
- Changedusda_compare_foods4 fields changed
  - removedOutput schema / properties / missingData / items / properties / nutrientId / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
  - addedOutput schema / properties / missingData / items / properties / nutrientId / type
```
Added value: +[
+  "number",
+  "null"
+]
```
  - removedOutput schema / properties / nutrients / items / properties / values / items / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
  - addedOutput schema / properties / nutrients / items / properties / values / items / type
```
Added value: +[
+  "number",
+  "null"
+]
```

5 tool updatesAug 25, 2026

Changedusda_compare_foods6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "basis",
+      "foods",
+      "nutrients"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `too_few_foods`: Fewer than 2 of the provided FDC IDs returned data, making comparison impossible. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "too_few_foods"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "basis",
-  "foods",
-  "nutrients"
-]

Changedusda_get_food6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "fdcId",
+      "description",
+      "dataType",
+      "nutrients"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The FDC ID does not exist in the database. `quantity_without_unit`: quantity is provided but unit is omitted. `no_portion_data`: unit=\"serving\" was requested but the food has no portion data. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "quantity_without_unit",
+            "no_portion_data"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "fdcId",
-  "description",
-  "dataType",
-  "nutrients"
-]

Changedusda_get_foods6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "foods",
+      "failed"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode.",
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "foods",
-  "failed"
-]

Changedusda_list_nutrients6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "nutrients"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode.",
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required
```
Removed value: -[
-  "nutrients"
-]
```

Changedusda_search_foods6 fields changed

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "totalHits",
+      "currentPage",
+      "totalPages",
+      "foods",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `query_empty`: The query is empty or contains only whitespace. `no_results`: No foods matched the query in the specified data sources. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "query_empty",
+            "no_results"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "totalHits",
-  "currentPage",
-  "totalPages",
-  "foods",
-  "totalCount"
-]

5 tool updatesAug 13, 2026
- First observedusda_compare_foods
- First observedusda_get_food
- First observedusda_get_foods
- First observedusda_list_nutrients
- First observedusda_search_foods

Related MCP Connectors

Nutrition MCPOAuth
io.github.AndrewVG23
USDA FoodData Central nutrition data: search foods, compare macros, and analyze meals.
Health & Wellness Open Data
1
https://docuslide-mcp-production.up.railway.app/mcp
Food & Nutrition A
org.memoryapi
Food and nutrition data: search, macros, and comparisons
Health & Wellness Search
32
https://food.memoryapi.org/mcp
openfoodfacts-mcp-server A
io.github.cyanheads
Barcode lookup, nutrition search, and product comparison for 3M+ crowd-sourced food products.
Health & Wellness Search Open Data
421
https://openfoodfacts.caseyjhand.com/mcp
fmcg.network AOAuth
network.fmcg
USDA FoodData Central nutrient lookup, FDA recall watch, EU FMCG labelling via remote MCP
Government Data Health & Wellness
61
https://mcp.fmcg.network/mcp

Related MCP Servers

nutrition-mcp-server
Search Open Data Health & Wellness
AiAgentKarl
A
license
A
quality
D
maintenance
Enables natural language access to USDA's FoodData Central database with 1M+ foods, supporting search, nutrition facts, food comparison, and daily value calculations.
Updated 6 months ago (2026-05-09 08:06 UTC)
8
MIT
USDA FoodData Central MCP
Health & Wellness Search Open Data
SpyrosBou
A
license
A
quality
C
maintenance
Enables searching and retrieving nutrition data from the USDA FoodData Central API, with tools for food search, nutrient lookups, and bulk operations.
Updated a year ago (2025-11-15 13:27 UTC)
16
8 npm
MIT
USDA Nutrition Database MCP
Databases Search Health & Wellness
HemantaPatil
F
license
Not graded
quality
D
maintenance
Provides intelligent access to the USDA nutrition database through AI assistants, enabling users to search foods, compare nutritional content, find foods high in specific nutrients, and query authoritative nutrition data across 7,146+ food items through natural language.
Updated a year ago (2025-09-02 23:56 UTC)
1
-
Food Data Central MCP Server
Search Health & Wellness
jlfwong
A
license
Not graded
quality
F
maintenance
A Model Context Protocol server that enables Claude to search and access detailed nutritional information from the USDA's FoodData Central database.
Updated 2 years ago (2025-04-07 01:05 UTC)
11
MIT

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Server Details

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Related MCP Connectors

Related MCP Servers

Glama MCP Gateway

Resources