Agentes, LLMs e MCP

Agentes devem descobrir a documentação por /llms.txt. O arquivo separa a Nova API V1.0 do API Legado e aponta para uma representação .md de cada guia e de cada contrato OpenAPI.

Ordem de leitura

1. Leia /llms.txt e escolha Nova API V1.0.
2. Leia /md/v1/primeiros-passos.md.
3. Para API key, leia /md/v1/autenticacao.md e /md/v1/api-key-tokens.md; para aplicativos instaláveis, leia /md/v1/oauth.md.
4. Leia o .md de cada operação que será usada.
5. Use /openapi-v1.yaml quando precisar validar o documento completo.

/llms-full.txt reúne todo o corpus em um único arquivo, mas o índice compacto é melhor para limitar contexto e buscar somente as fontes necessárias.

MCP opcional

O servidor MCP somente leitura está disponível por Streamable HTTP:

https://docs.takeat.app/api/mcp

Ele pesquisa guias, lê páginas e lista contratos. Não executa requisições na API Takeat e não precisa receber credenciais.

Codex

No terminal, cadastre o servidor:

codex mcp add takeat-docs --url https://docs.takeat.app/api/mcp
codex mcp list

Alternativamente, adicione à configuração do Codex:

[mcp_servers.takeat-docs]
url = "https://docs.takeat.app/api/mcp"

Inicie uma nova sessão do cliente após configurar. Não adicione API key, Bearer token nem credenciais do restaurante. Para testar, peça:

Use o MCP takeat-docs para buscar autenticação com API Key e ler o guia
completo. Liste as operações de cardápio e leia o contrato de GET /v1/menu.
Cite as fontes e não faça chamadas à API Takeat.

O cadastro do servidor não comprova a conexão: confirme que o agente executou search_documentation, get_documentation_page e list_api_operations.

Clientes com configuração mcpServers

Para clientes que aceitam esse formato, como Cursor:

{
  "mcpServers": {
    "takeat-api-docs": {
      "url": "https://docs.takeat.app/api/mcp"
    }
  }
}

O transporte é Streamable HTTP, sem sessão persistente e com respostas JSON. Abrir a URL no navegador pode mostrar 405 Method Not Allowed, pois o cliente MCP deve enviar POST para inicializar e consultar o servidor. Um 500 durante a inicialização não é esperado e indica uma falha no servidor; não tente resolvê-lo fornecendo credenciais.

Escolha o prompt pelo contexto

Os prompts partem de contextos diferentes. Não use o prompt de aplicação nova para um projeto que ainda chama o API Legado: ele instrui o agente a ignorar endpoints antigos e não cobre compatibilidade nem rollback.

Cada guia explica o contexto antes do prompt e fornece um bloco pronto para copiar. Ambos exigem que o agente leia os contratos .md, use apenas valores fictícios e apresente um plano para aprovação antes de modificar o projeto.

Implementar o ciclo de tokens com API key

Se a escolha por API key já está definida e você quer implementar a autenticação no seu backend, use o prompt de access e refresh tokens. Ele pede a implementação e os testes do ciclo completo: access token de 900 segundos, renovação antecipada, rotação atômica, concorrência e recuperação de falhas. Use somente nomes de variáveis, nunca credenciais reais.

Limite de confiança

Os arquivos .md de referência são gerados da especificação OpenAPI publicada e são a fonte para método, path, parâmetros, request body, respostas e schemas. Se um comportamento não estiver no guia nem no contrato, o agente deve marcá-lo como dúvida em vez de inferir.