January AI Nutrition

npx add-mcp 'https://mcp.january.ai/mcp'

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

MCP server

Use January from a coding agent. The hosted MCP server exposes the v1.2 REST API as tools that Claude Code, Codex and other MCP clients can call while they build your integration.

Every tool call is an ordinary API request made with your account API key, so credits, the daily request ceiling and the usage shown in the January Developer Dashboard apply exactly as they do to your own code. The server keeps no state and stores nothing.

https://mcp.january.ai/mcp

Connect

Create an sk-… API key in the Developer Dashboard, then register the server with your client. The key is sent as the bearer credential on every request.

{% tabs %} {% tab title="Claude Code" %} --scope user makes the server available in every project on this machine. The last command asks a question without opening the agent; --allowedTools mcp__january lets that run call January's tools without a permission prompt.

claude mcp add --scope user --transport http january https://mcp.january.ai/mcp \
  --header 'Authorization: Bearer sk-your-key'
claude -p "Search the January food database for greek yogurt and list the top three matches." --allowedTools mcp__january

{% endtab %}

{% tab title="Codex" %} Codex reads the bearer token from an environment variable each time it starts, so keep the export in your shell profile. The last command asks a question without opening the agent; --skip-git-repo-check lets it run outside a Git repository.

codex mcp add january --url https://mcp.january.ai/mcp --bearer-token-env-var JANUARY_API_KEY
export JANUARY_API_KEY="sk-your-key"
codex exec --skip-git-repo-check "Search the January food database for greek yogurt and list the top three matches."

Codex stops waiting for a tool after 60 seconds by default, and an image analysis can take slightly longer. Raise the limit in the [mcp_servers.january] section that the command wrote to ~/.codex/config.toml:

[mcp_servers.january]
tool_timeout_sec = 90

{% endtab %}

{% tab title="VS Code" %} VS Code lists servers under servers in .vscode/mcp.json and needs the transport spelled out.

{
  "servers": {
    "january": {
      "type": "http",
      "url": "https://mcp.january.ai/mcp",
      "headers": { "Authorization": "Bearer sk-your-key" }
    }
  }
}

{% endtab %}

{% tab title="Other clients" %} Cursor and most other clients accept this configuration block. Windsurf takes the same block with serverUrl in place of url.

{
  "mcpServers": {
    "january": {
      "url": "https://mcp.january.ai/mcp",
      "headers": { "Authorization": "Bearer sk-your-key" }
    }
  }
}

{% endtab %} {% endtabs %}

A successful answer lists three foods from the catalog. Each time you create a key, the dashboard shows the Claude Code, Codex and JSON setups with the new key already filled in.

{% hint style="warning" %} The client stores the key in its own configuration on that machine. Use a key created for this purpose and delete it from the dashboard when you no longer need it. {% endhint %}

Tools

Tool names follow the REST resources. IDs are strings, amounts are { value, unit }, and errors carry the API's code values plus two of the server's own, described under Errors and cost.

Group	Tool	What it does
Look up	january_search_foods	Find generic, branded and recipe foods by name.
	january_get_food	One food's complete record and serving list, by id or by barcode (US barcodes only).
	january_suggest_food_alternatives	Healthier alternatives that honor allergens to avoid and dietary patterns to match.
Interpret	january_analyze_food	Detect foods and nutrition in a photo (URL or data URI) or a plain-English meal description.
	january_correct_food_analysis	Revise an analysis conversationally and recalculate its totals.
Record	january_list_food_logs	One end user's diary over a range of local calendar days.
	january_create_food_log	Record a meal from food and serving selections.
	january_update_food_log	Change a saved log's foods, time or name.
	january_delete_food_log	Delete one saved log.
Predict	january_predict_glucose	Predict the glucose curve a meal produces for a described person.
Nearby	january_search_restaurants	Restaurants near a coordinate.
	january_search_menu_items	Dishes with nutrition near a coordinate.
	january_get_restaurant_menu	One restaurant's menu, paged.
Account	january_get_credits	The current month's credit allowance and usage. Free.

Two resources are published alongside the tools: january://openapi.json, the live OpenAPI document, and january://error-codes, every error code with its retry rule and what to do next.

Before an agent writes data

The food-log tools act on a real end user's diary under your account. Give the agent a designated test end_user_id: the server's instructions tell it never to invent or reuse one and to state which end user each write went to.

Updating or deleting a log requires the etag returned by a listing of that log within the last fifteen minutes. An agent working from a stale plan cannot delete what it has not just read, and there is no bulk delete.

Food analysis never writes a log. Glucose predictions are estimates from a model, not measurements or medical advice.

Errors and cost

Every tool error carries the API's stable code together with retryable, retry_after_seconds, next_step and request_id, so an agent can decide whether to change the request, wait, or stop. Two codes come from the MCP server itself: precondition_failed for a missing or stale etag, and cancelled when the client aborts a call.

january_get_credits costs nothing and answers even when the balance is spent. Every other tool is priced like the endpoint behind it; see Credits. When the monthly allowance is exhausted, the error includes the current balance and the reset date, and the agent is told not to retry.

Next steps

• Quickstart for the same first call with curl.
• REST API reference for every endpoint the tools call.