> For the complete documentation index, see [llms.txt](https://docs.january.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.january.ai/docs/mcp-server.md).

# 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](/rest-api/credits.md), the daily request ceiling and the usage shown in the [January Developer Dashboard](https://dashboard.january.ai) 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.

```bash
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.

```bash
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`:

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

```json
{
  "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`.

```json
{
  "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](#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](/rest-api/credits.md). 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](/docs/quickstart.md) for the same first call with `curl`.
* [REST API reference](/rest-api/api-overview.md) for every endpoint the tools call.