January AI Nutrition

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

Para o índice completo da documentação, consulte llms.txt. Versões em Markdown das páginas de documentação estão disponíveis adicionando .md às URLs das páginas; esta página está disponível como Markdown.

Servidor MCP

Use o January a partir de um agente de codificação. O servidor MCP hospedado expõe a API REST v1.2 como ferramentas que Claude Code, Codex e outros clientes MCP podem chamar enquanto constroem sua integração.

Cada chamada de ferramenta é uma solicitação de API comum feita com a chave de API da sua conta, então créditos, o teto diário de solicitações e o uso exibido no Painel do Desenvolvedor January se aplicam exatamente como ao seu próprio código. O servidor não mantém estado e não armazena nada.

https://mcp.january.ai/mcp

Conectar

Crie uma chave de API sk-… no Painel do Desenvolvedor e registre o servidor no seu cliente. A chave é enviada como credencial de portador em cada solicitação.

{% tabs %} {% tab title="Claude Code" %} --scope user disponibiliza o servidor em todos os projetos desta máquina. O último comando faz uma pergunta sem abrir o agente; --allowedTools mcp__january permite que essa execução chame as ferramentas do January sem um prompt de permissão.

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" %} O Codex lê o token de portador de uma variável de ambiente a cada inicialização, então mantenha o export no seu perfil de shell. O último comando faz uma pergunta sem abrir o agente; --skip-git-repo-check permite que ele execute fora de um repositório Git.

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

O Codex para de esperar por uma ferramenta após 60 segundos por padrão, e uma análise de imagem pode demorar um pouco mais. Aumente o limite na seção [mcp_servers.january] que o comando gravou em ~/.codex/config.toml:

[mcp_servers.january]
tool_timeout_sec = 90

{% endtab %}

{% tab title="VS Code" %} O VS Code lista servidores em servers em .vscode/mcp.json e precisa que o transporte seja especificado.

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

{% endtab %}

{% tab title="Outros clientes" %} O Cursor e a maioria dos outros clientes aceitam este bloco de configuração. O Windsurf aceita o mesmo bloco com serverUrl no lugar de url.

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

{% endtab %} {% endtabs %}

Uma resposta bem-sucedida lista três alimentos do catálogo. Cada vez que você cria uma chave, o painel mostra as configurações do Claude Code, Codex e JSON com a nova chave já preenchida.

{% hint style="warning" %} O cliente armazena a chave na própria configuração dessa máquina. Use uma chave criada para esse fim e exclua-a do painel quando não precisar mais dela. {% endhint %}

Ferramentas

Os nomes das ferramentas seguem os recursos REST. IDs são strings, quantidades são { value, unit }, e erros carregam os valores de code da API, além de dois próprios do servidor, descritos em Erros e custo.

Grupo	Ferramenta	O que faz
Consulta	january_search_foods	Encontra alimentos genéricos, de marca e receitas por nome.
	january_get_food	Registro completo e lista de porções de um alimento, por id ou por código de barras (somente códigos de barras dos EUA).
	january_suggest_food_alternatives	Alternativas mais saudáveis que respeitam alérgenos a evitar e padrões alimentares a corresponder.
Interpretação	january_analyze_food	Detecta alimentos e nutrição em uma foto (URL ou data URI) ou em uma descrição de refeição em linguagem simples.
	january_correct_food_analysis	Revisa uma análise de forma conversacional e recalcula seus totais.
Registro	january_list_food_logs	Diário de um usuário final em um intervalo de dias de calendário local.
	january_create_food_log	Registra uma refeição a partir de seleções de alimentos e porções.
	january_update_food_log	Altera alimentos, hora ou nome de um registro salvo.
	january_delete_food_log	Exclui um registro salvo.
Previsão	january_predict_glucose	Prevê a curva de glicose que uma refeição produz para uma pessoa descrita.
Próximos	january_search_restaurants	Restaurantes próximos a uma coordenada.
	january_search_menu_items	Pratos com nutrição próximos a uma coordenada.
	january_get_restaurant_menu	Cardápio de um restaurante, paginado.
Conta	january_get_credits	Cota de créditos e uso do mês atual. Gratuito.

Dois recursos são publicados junto com as ferramentas: january://openapi.json, o documento OpenAPI ao vivo, e january://error-codes, todos os códigos de erro com sua regra de nova tentativa e o que fazer em seguida.

Antes de um agente gravar dados

As ferramentas de registro de alimentos atuam no diário real de um usuário final sob sua conta. Dê ao agente um end_user_id de teste designado: as instruções do servidor dizem para nunca inventar ou reutilizar um e para informar a qual usuário final cada gravação foi feita.

Atualizar ou excluir um registro exige o etag retornado por uma listagem desse registro nos últimos quinze minutos. Um agente trabalhando com um plano desatualizado não pode excluir o que não acabou de ler, e não há exclusão em massa.

A análise de alimentos nunca grava um registro. As previsões de glicose são estimativas de um modelo, não medições ou conselhos médicos.

Erros e custo

Cada erro de ferramenta carrega o code estável da API junto com retryable, retry_after_seconds, next_step e request_id, para que um agente possa decidir se deve alterar a solicitação, aguardar ou parar. Dois códigos vêm do próprio servidor MCP: precondition_failed para um etag ausente ou desatualizado, e cancelled quando o cliente aborta uma chamada.

january_get_credits não custa nada e responde mesmo quando o saldo está esgotado. Todas as outras ferramentas são precificadas como o endpoint por trás delas; consulte Créditos. Quando a cota mensal é esgotada, o erro inclui o saldo atual e a data de redefinição, e o agente é instruído a não tentar novamente.

Próximos passos

• Início rápido para a mesma primeira chamada com curl.
• Referência da API REST para todos os endpoints que as ferramentas chamam.