usda-mcp-server

Get USDA Food

usda_get_food

Read-only

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.

Input Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 26, 2026

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."

Changed7 schema fields changedOct 25, 2026

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)."

Changed6 schema fields changedAug 25, 2026

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"
-]

First observedAug 13, 2026

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.

All usda-mcp-server tools Inspect

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.