Koskamo

usda-mcp-server

An MCP server that provides access to the USDA FoodData Central database, allowing agents to search for foods by keyword or UPC, retrieve full nutrient profiles with portion scaling, compare multiple foods side-by-side, and look up nutrient reference tables.

Endpoint and access

No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.

usda-mcp-server logo, by cyanheadsCommunity listingStreamable HTTPNo sign-inEndpoint checked 2026-11-06Published by cyanheads
MCP endpoint (Streamable HTTP)
https://usda.caseyjhand.com/mcp
Vendor documentation

What its tools do

5 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.

Read-only (5)

5 of 5 have a description · 5 of 5 declare behavior hints · 5 of 5 with parameters document them all

Checks and signals

Each line is separate evidence, not a trust score.

  • Passed Endpoint answered the live check ·
  • Availability 1 of 1 checks passed in 30 days

What you can do with it

  • Search for foods by name or UPC code
  • Retrieve full nutrient profiles for specific foods
  • Compare nutritional content of multiple foods
  • Look up nutrient IDs and categories

Source and maintenance

Community listingRegistry 0.2.0
mcp-registry: io.github.cyanheads/usda-mcp-server@0.2.0Source repository
Maintenance checked

Protocol and capabilities

Server
usda-mcp-server 0.2.0
MCP protocol negotiated in check
2025-11-25
Tools
5 advertised
Resources
2 advertised
Resource templates
2 advertised
Prompts
0 advertised
Server-advertised capabilities
{
  "tools": {
    "listChanged": true
  },
  "logging": {},
  "prompts": {
    "listChanged": true
  },
  "resources": {
    "subscribe": true,
    "listChanged": true
  },
  "extensions": {
    "io.modelcontextprotocol/skills": {
      "directoryRead": true
    }
  }
}

Server-provided instructions

Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.

USDA FoodData Central (FDC) — authoritative US food composition database (~400K+ foods). Key workflow: usda_search_foods → fdcId → usda_get_food (single), usda_get_foods (batch), or usda_compare_foods (comparison). Use usda_list_nutrients to resolve nutrient names to numeric IDs before filtering.

Tools

5 advertised

usda_list_nutrients — List USDA Nutrients
Advertised by the server during the last successful anonymous check.
Advertised read-only

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.

usda_list_nutrients input schema
{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "category": {
      "enum": [
        "macronutrients",
        "vitamins",
        "minerals",
        "lipids",
        "amino_acids",
        "other"
      ],
      "type": "string",
      "description": "Filter to a nutrient category. Omit to return all ~150 tracked nutrients. Options: macronutrients, vitamins, minerals, lipids, amino_acids, other."
    }
  },
  "additionalProperties": false
}
usda_list_nutrients output schema
{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "nutrients"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "nutrients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "number",
          "unit",
          "category"
        ],
        "properties": {
          "id": {
            "type": "number",
            "description": "FDC nutrient ID — pass this to nutrients[] params on other tools."
          },
          "name": {
            "type": "string",
            "description": "Human-readable nutrient name (e.g. \"Protein\", \"Iron, Fe\")."
          },
          "unit": {
            "type": "string",
            "description": "Measurement unit (e.g. \"G\", \"MG\", \"UG\", \"KCAL\")."
          },
          "number": {
            "type": "string",
            "description": "SR reference number (legacy identifier, e.g. \"203\")."
          },
          "category": {
            "type": "string",
            "description": "Nutrient category grouping."
          }
        },
        "description": "A nutrient reference entry with ID, name, unit, and category.",
        "additionalProperties": false
      },
      "description": "Nutrient reference entries matching the requested category, or all if category is omitted."
    }
  },
  "additionalProperties": false
}
usda_list_nutrients annotations
{
  "readOnlyHint": true,
  "openWorldHint": false
}
usda_search_foods — Search USDA Foods
Advertised by the server during the last successful anonymous check.
Advertised read-onlyOpen-world

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.

usda_search_foods input schema
{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "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": {
      "type": "array",
      "items": {
        "enum": [
          "SR Legacy",
          "Foundation",
          "Survey (FNDDS)",
          "Branded"
        ],
        "type": "string"
      },
      "description": "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": {
      "type": "integer",
      "default": 10,
      "maximum": 50,
      "minimum": 1,
      "description": "Number of results per page. Default 10, maximum 50."
    },
    "brandOwner": {
      "type": "string",
      "description": "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": {
      "type": "integer",
      "default": 1,
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "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": {
      "type": "string",
      "description": "Filter by USDA food category (e.g. \"Poultry Products\", \"Vegetables and Vegetable Products\"). Case-sensitive."
    }
  },
  "additionalProperties": false
}
usda_search_foods output schema
{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "totalHits",
        "currentPage",
        "totalPages",
        "foods",
        "totalCount"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "query_empty",
                "query_syntax",
                "no_results"
              ],
              "description": "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."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "foods": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "fdcId",
          "description",
          "dataType",
          "nutrients"
        ],
        "properties": {
          "fdcId": {
            "type": "number",
            "description": "FDC ID — pass to usda_get_food, usda_get_foods, or usda_compare_foods."
          },
          "dataType": {
            "type": "string",
            "description": "FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded."
          },
          "brandName": {
            "type": "string",
            "description": "Brand name. Present for Branded items only."
          },
          "nutrients": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "amount",
                "unit"
              ],
              "properties": {
                "id": {
                  "type": "number",
                  "description": "FDC nutrient ID."
                },
                "name": {
                  "type": "string",
                  "description": "Nutrient name."
                },
                "unit": {
                  "type": "string",
                  "description": "Unit (e.g. \"G\", \"MG\", \"KCAL\")."
                },
                "amount": {
                  "type": "number",
                  "description": "Amount per 100g."
                }
              },
              "description": "A preview nutrient entry with ID, name, and amount per 100g.",
              "additionalProperties": false
            },
            "description": "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."
          },
          "brandOwner": {
            "type": "string",
            "description": "Brand owner name. Present for Branded items only."
          },
          "description": {
            "type": "string",
            "description": "USDA food description (e.g. \"Chicken, broilers or fryers, breast, meat only, raw\")."
          },
          "servingSize": {
            "type": "number",
            "description": "Serving size from the product label, in servingSizeUnit. Branded only."
          },
          "foodCategory": {
            "type": "string",
            "description": "USDA food category (e.g. \"Poultry Products\"). Absent for some branded items."
          },
          "publishedDate": {
            "type": "string",
            "description": "Date the food entry was published in FDC."
          },
          "servingSizeUnit": {
            "type": "string",
            "description": "Unit for servingSize as FDC reports it: mass (\"g\", \"GRM\", \"GM\", \"MG\"), volume (\"ml\", \"MLT\"), or another unit (\"IU\"). Branded only."
          },
          "householdServingFullText": {
            "type": "string",
            "description": "Serving description as it appears on the label (e.g. \"1 cup\", \"1 oz\"). Branded only."
          }
        },
        "description": "A food item matching the search query.",
        "additionalProperties": false
      },
      "description": "Foods matching the search query."
    },
    "notice": {
      "type": "string",
      "description": "Guidance for a requested page beyond the available range."
    },
    "totalHits": {
      "type": "number",
      "description": "Total number of foods matching the query across all pages."
    },
    "totalCount": {
      "type": "number",
      "description": "Total foods matching the query across all pages."
    },
    "totalPages": {
      "type": "number",
      "description": "Total number of pages available."
    },
    "currentPage": {
      "type": "number",
      "description": "Current page number (1-based); the requested page for exhausted pages."
    }
  },
  "additionalProperties": false
}
usda_search_foods annotations
{
  "readOnlyHint": true,
  "openWorldHint": true
}
usda_get_food — Get USDA Food
Advertised by the server during the last successful anonymous check.
Advertised 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.

usda_get_food input schema
{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "fdcId"
  ],
  "properties": {
    "unit": {
      "enum": [
        "g",
        "oz",
        "lb",
        "kg",
        "serving"
      ],
      "type": "string",
      "description": "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": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "FDC ID of the food. Use usda_search_foods to discover IDs."
    },
    "quantity": {
      "type": "number",
      "description": "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).",
      "exclusiveMinimum": 0
    },
    "nutrients": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 1
      },
      "description": "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."
    }
  },
  "additionalProperties": false
}
usda_get_food output schema
{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "fdcId",
        "description",
        "dataType",
        "nutrients"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "not_found",
                "quantity_without_unit",
                "no_portion_data"
              ],
              "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 valid portion or supported Branded gram-label serving. Other values are possible when a failure originates below the handler."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "fdcId": {
      "type": "number",
      "description": "FDC ID of the food."
    },
    "dataType": {
      "type": "string",
      "description": "FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded."
    },
    "scaledTo": {
      "type": "object",
      "required": [
        "quantity",
        "unit",
        "gramWeight"
      ],
      "properties": {
        "unit": {
          "type": "string",
          "description": "Unit provided in the request (g, oz, lb, kg, or serving)."
        },
        "quantity": {
          "type": "number",
          "description": "Quantity applied — the requested value, or the default for unit (100 for g, oz, lb, kg; 1 for serving)."
        },
        "gramWeight": {
          "type": "number",
          "description": "Gram weight resolved from quantity and unit (for serving, quantity × servingInfo.gramWeight) — all nutrient values are per this many grams."
        }
      },
      "description": "Scaling basis when unit was provided. Absent when returning per-100g values.",
      "additionalProperties": false
    },
    "brandName": {
      "type": "string",
      "description": "Brand name. Branded items only."
    },
    "nutrients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "number",
          "amount",
          "unit"
        ],
        "properties": {
          "id": {
            "type": "number",
            "description": "FDC nutrient ID."
          },
          "name": {
            "type": "string",
            "description": "Nutrient name (e.g. \"Protein\", \"Energy\", \"Iron, Fe\")."
          },
          "unit": {
            "type": "string",
            "description": "Measurement unit (e.g. \"G\", \"MG\", \"KCAL\")."
          },
          "amount": {
            "type": "number",
            "description": "Nutrient amount — per 100g, or per scaledTo.gramWeight when unit is provided."
          },
          "number": {
            "type": "string",
            "description": "SR reference number (legacy identifier)."
          },
          "percentDailyValue": {
            "type": "number",
            "description": "Percent daily value from product label. Branded items only."
          }
        },
        "description": "A single nutrient entry with ID, name, amount, and unit.",
        "additionalProperties": false
      },
      "description": "Nutrient values for this food, per 100g or scaled to the scaledTo basis."
    },
    "brandOwner": {
      "type": "string",
      "description": "Brand owner. Branded items only."
    },
    "allPortions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "description",
          "gramWeight"
        ],
        "properties": {
          "gramWeight": {
            "type": "number",
            "description": "Gram weight of this portion."
          },
          "description": {
            "type": "string",
            "description": "Portion description."
          }
        },
        "description": "A named portion for this food.",
        "additionalProperties": false
      },
      "description": "All named portions for this food."
    },
    "description": {
      "type": "string",
      "description": "Full USDA food name (e.g. \"Chicken, broilers or fryers, breast, meat only, raw\")."
    },
    "ingredients": {
      "type": "string",
      "description": "Ingredient list from label. Branded items only."
    },
    "servingInfo": {
      "type": "object",
      "required": [
        "description",
        "gramWeight"
      ],
      "properties": {
        "gramWeight": {
          "type": "number",
          "description": "Gram weight of this portion."
        },
        "description": {
          "type": "string",
          "description": "Portion description, or label-serving provenance with source size, unit and available household text."
        }
      },
      "description": "First available portion definition, or a Branded gram-label serving identified in its description.",
      "additionalProperties": false
    },
    "foodCategory": {
      "type": "string",
      "description": "USDA food category (e.g. \"Poultry Products\"). Absent for some branded items."
    },
    "publicationDate": {
      "type": "string",
      "description": "Date this food entry was published in FDC."
    }
  },
  "additionalProperties": false
}
usda_get_food annotations
{
  "readOnlyHint": true,
  "openWorldHint": false
}
usda_get_foods — Get USDA Foods (Batch)
Advertised by the server during the last successful anonymous check.
Advertised read-only

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.

usda_get_foods input schema
{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "fdcIds"
  ],
  "properties": {
    "fdcIds": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 1
      },
      "maxItems": 20,
      "minItems": 2,
      "description": "FDC IDs to fetch — 2 to 20 IDs. Use usda_search_foods to discover IDs."
    },
    "nutrients": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 1
      },
      "description": "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."
    }
  },
  "additionalProperties": false
}
usda_get_foods output schema
{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "foods",
        "failed"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "foods": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "fdcId",
          "description",
          "dataType",
          "nutrients"
        ],
        "properties": {
          "fdcId": {
            "type": "number",
            "description": "FDC ID of this food."
          },
          "dataType": {
            "type": "string",
            "description": "FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded."
          },
          "nutrients": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "number",
                "amount",
                "unit"
              ],
              "properties": {
                "id": {
                  "type": "number",
                  "description": "FDC nutrient ID."
                },
                "name": {
                  "type": "string",
                  "description": "Nutrient name."
                },
                "unit": {
                  "type": "string",
                  "description": "Measurement unit (e.g. \"G\", \"MG\", \"KCAL\")."
                },
                "amount": {
                  "type": "number",
                  "description": "Amount per 100g."
                },
                "number": {
                  "type": "string",
                  "description": "SR reference number."
                }
              },
              "description": "A nutrient entry with ID, name, amount, and unit.",
              "additionalProperties": false
            },
            "description": "Nutrient values per 100g."
          },
          "description": {
            "type": "string",
            "description": "Full USDA food name (e.g. \"Chicken, broilers or fryers, breast, meat only, raw\")."
          }
        },
        "description": "Nutrient profile for one food.",
        "additionalProperties": false
      },
      "description": "Successfully fetched foods."
    },
    "failed": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "fdcId",
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Why this ID failed — not found, no data returned, etc."
          },
          "fdcId": {
            "type": "number",
            "description": "FDC ID that could not be fetched."
          }
        },
        "description": "A failed food fetch with the FDC ID and error reason.",
        "additionalProperties": false
      },
      "description": "IDs that returned no data. Check these with usda_search_foods to verify they exist."
    }
  },
  "additionalProperties": false
}
usda_get_foods annotations
{
  "readOnlyHint": true,
  "openWorldHint": false
}
usda_compare_foods — Compare USDA Foods
Advertised by the server during the last successful anonymous check.
Advertised read-only

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.

usda_compare_foods input schema
{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "fdcIds"
  ],
  "properties": {
    "unit": {
      "enum": [
        "g",
        "oz",
        "lb",
        "kg"
      ],
      "type": "string",
      "default": "g",
      "description": "Unit for quantity. Default \"g\". Does not support \"serving\" (each food's portion weight differs, so a serving basis would not compare equal amounts)."
    },
    "fdcIds": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 1
      },
      "maxItems": 5,
      "minItems": 2,
      "description": "FDC IDs to compare — 2 to 5 foods. Use usda_search_foods to discover IDs."
    },
    "quantity": {
      "type": "number",
      "default": 100,
      "description": "Amount of food, in unit, that every value is scaled to. Must be positive. Default 100.",
      "exclusiveMinimum": 0
    },
    "nutrients": {
      "type": "array",
      "items": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": 1
      },
      "description": "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."
    }
  },
  "additionalProperties": false
}
usda_compare_foods output schema
{
  "type": "object",
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "basis",
        "foods",
        "nutrients"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "basis": {
      "type": "object",
      "required": [
        "quantity",
        "unit",
        "gramWeight"
      ],
      "properties": {
        "unit": {
          "type": "string",
          "description": "Unit applied (g, oz, lb, or kg) — the requested value or the default \"g\"."
        },
        "quantity": {
          "type": "number",
          "description": "Quantity applied, in unit — the requested value or the default 100."
        },
        "gramWeight": {
          "type": "number",
          "description": "Gram weight resolved from quantity and unit — all nutrient values are per this many grams."
        }
      },
      "description": "The common scaling basis applied to all nutrient values.",
      "additionalProperties": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "examples": [
                "too_few_foods"
              ],
              "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."
            },
            "recovery": {
              "type": "object",
              "required": [
                "hint"
              ],
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "description": "Actionable next step for the caller.",
              "additionalProperties": {}
            },
            "retryable": {
              "type": "boolean",
              "description": "Whether retrying may succeed."
            }
          },
          "additionalProperties": {}
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        }
      },
      "description": "Present when the call failed. Absent on success.",
      "additionalProperties": {}
    },
    "foods": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "fdcId",
          "description",
          "dataType"
        ],
        "properties": {
          "fdcId": {
            "type": "number",
            "description": "FDC ID."
          },
          "dataType": {
            "type": "string",
            "description": "FDC data source: SR Legacy, Foundation, Survey (FNDDS), or Branded."
          },
          "description": {
            "type": "string",
            "description": "Full USDA food name (e.g. \"Spinach, raw\")."
          }
        },
        "description": "One of the compared foods.",
        "additionalProperties": false
      },
      "description": "The compared foods, in the same order as the values arrays below."
    },
    "nutrients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "unit",
          "values"
        ],
        "properties": {
          "id": {
            "type": "number",
            "description": "FDC nutrient ID."
          },
          "name": {
            "type": "string",
            "description": "Nutrient name (e.g. \"Protein\", \"Energy\")."
          },
          "unit": {
            "type": "string",
            "description": "Measurement unit (e.g. \"G\", \"MG\", \"KCAL\")."
          },
          "values": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "null"
              ]
            },
            "description": "One value per food in the same order as foods[]. null when data is unavailable for that food."
          }
        },
        "description": "One nutrient row with per-food values.",
        "additionalProperties": false
      },
      "description": "Nutrient rows — one entry per requested nutrient, with per-food values in the values[] array."
    },
    "missingData": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "fdcId",
          "nutrientId"
        ],
        "properties": {
          "fdcId": {
            "type": "number",
            "description": "FDC ID that had missing data."
          },
          "nutrientId": {
            "type": [
              "number",
              "null"
            ],
            "description": "Nutrient ID that was missing, or null when the entire food was not found."
          }
        },
        "description": "A food or food+nutrient pair where data was unavailable.",
        "additionalProperties": false
      },
      "description": "Foods or food+nutrient pairs where data was unavailable. Absent when all data was present."
    }
  },
  "additionalProperties": false
}
usda_compare_foods annotations
{
  "readOnlyHint": true,
  "openWorldHint": false
}

Prompts

0 advertised

No prompt definitions available.

Resources

2 advertised

USDA Nutrient Reference — USDA Nutrient Reference

Advertised by the server during the last successful anonymous check.

Access the complete FDC nutrient reference — all ~150 tracked nutrients with their numeric IDs, names, SR reference numbers, units, and categories. Use to resolve nutrient names to FDC IDs for the nutrients[] filter on usda_get_food, usda_get_foods, usda_compare_foods, and usda_list_nutrients.

USDA Nutrient Reference URI
usda://nutrients

MIME type: application/json

usda-guide

Advertised by the server during the last successful anonymous check.

Use usda_* tools for food comparisons, portion-based nutrition, and packaged-food lookups when preparation, serving weights, or missing nutrients affect the answer. Establish matching food records and measurement bases before drawing conclusions.

usda-guide URI
skill://usda-guide/SKILL.md

MIME type: text/markdown

USDA Food Profile — USDA Food Profile

Advertised by the server during the last successful anonymous check.

Full nutrient profile for a specific food by FDC ID. Returns all available nutrients per 100g — equivalent to usda_get_food without portion scaling. Use usda_search_foods to discover FDC IDs.

USDA Food Profile URI template
usda://food/{fdcId}

MIME type: application/json

io.modelcontextprotocol/skills

Advertised by the server during the last successful anonymous check.

io.modelcontextprotocol/skills URI template
skill://{+path}

90-day uptime

A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.

Too few checks for a percentage yet (1 of 1 answered).

  1. 2026-11-07: 1 of 1 checks answered

30-day availability

Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.

Successful checks
1 of 1 (100%)
Average latency
661 ms
95th percentile latency
661 ms

Maintenance history

Public check and source-refresh events. Editorial and ownership records remain private.

  • · probe · passed · 661 ms · metadata changed · 5 tool(s), 2 resource(s), 2 resource template(s), 0 prompt(s)

Connect from your client

Each snippet registers the same endpoint; pick the client you use.

This server is operated by the named third party. Listing and endpoint checks are not an endorsement or a security audit. Review the operator's permissions, terms, and data handling before connecting. How listings are checked and corrected.

Claude Code

Run this once in a terminal. It registers the remote server. Use --scope project to write .mcp.json for the repo.
Claude Code configuration
claude mcp add --transport http usda-mcp-server-caseyjhand https://usda.caseyjhand.com/mcp

Codex

Run this once. Codex stores MCP servers in ~/.codex/config.toml (or .codex/config.toml in a trusted project).
Codex configuration
codex mcp add usda-mcp-server-caseyjhand --url https://usda.caseyjhand.com/mcp

Cursor

Merge this server into .cursor/mcp.json in your project, then enable usda-mcp-server-caseyjhand in your MCP settings.
Cursor configuration
{
  "mcpServers": {
    "usda-mcp-server-caseyjhand": {
      "url": "https://usda.caseyjhand.com/mcp"
    }
  }
}

Cline

Merge this into cline_mcp_settings.json (Cline → MCP Servers → Configure).
Cline configuration
{
  "mcpServers": {
    "usda-mcp-server-caseyjhand": {
      "type": "streamableHttp",
      "url": "https://usda.caseyjhand.com/mcp",
      "disabled": false
    }
  }
}

VS Code

Merge this server into .vscode/mcp.json. Use MCP: List Servers to start usda-mcp-server-caseyjhand and inspect its tools.
VS Code configuration
{
  "servers": {
    "usda-mcp-server-caseyjhand": {
      "type": "http",
      "url": "https://usda.caseyjhand.com/mcp"
    }
  }
}

Gemini CLI

Run this once. It writes .gemini/settings.json in the current project; pass --scope user for ~/.gemini/settings.json.
Gemini CLI configuration
gemini mcp add --transport http usda-mcp-server-caseyjhand https://usda.caseyjhand.com/mcp

Claude Desktop

Open Claude Settings > Connectors > Add custom connector, enter this server URL and enable it for the conversation. This is a manual remote-connector handoff, not a desktop JSON configuration.
Claude Desktop configuration
https://usda.caseyjhand.com/mcp

Windsurf

Merge this into ~/.codeium/windsurf/mcp_config.json, then refresh MCP in Cascade. Windsurf remote servers use serverUrl, not url.
Windsurf configuration
{
  "mcpServers": {
    "usda-mcp-server-caseyjhand": {
      "serverUrl": "https://usda.caseyjhand.com/mcp"
    }
  }
}

Let your agent find its tools

Find servers like usda-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.

Connect Koskamo Explore workflows
See all 6,932