A Croma expõe cada fonte de dados como uma ferramenta por meio do Model
Context Protocol (MCP), servido sobre
Streamable HTTP em:
Qualquer cliente MCP pode se conectar. Os clientes interativos (Claude,
ChatGPT, Cursor) usam o fluxo de OAuth:
adicione a Croma ao Claude em um clique
e faça login com sua conta Croma. Para o seu próprio código você se autentica
com a mesma chave de API da API REST: envie-a como token bearer e as
ferramentas são executadas com o escopo da sua organização, compartilhando os
mesmos limites de taxa e uso.
Use a partir do AI SDK
O AI SDK pode carregar as ferramentas da Croma
diretamente e entregá-las a um modelo para chamadas de ferramentas. Envie sua
chave no cabeçalho Authorization do transporte:
Trate a chave como um segredo: carregue-a de uma variável de ambiente ou de um
gerenciador de segredos, nunca a envie ao repositório e feche o cliente
(mcp.close()) quando terminar para liberar a conexão.
Comece pelo template de chat
Croma Chat Template é um
chat open source em Next.js construído sobre este endpoint com o AI SDK e o
AI Elements: respostas em streaming, chamadas de
ferramentas sobre todas as fontes da Croma, um seletor de fontes por mensagem e
limite de uso opcional. Experimente a implantação ao vivo em
chat.usecroma.com, ou use a implantação de um
clique na Vercel do repositório: ela pede sua CROMA_API_KEY e uma chave de
modelo e fica pronta para usar.
Nomes das ferramentas
As ferramentas são nomeadas conforme a sua fonte, com sublinhados em vez de
hifens, por exemplo policia_criminal_records, rues_entity_by_nit e
rama_judicial_cases_by_radicado. Chame mcp.tools() para listar o conjunto
completo com seus esquemas de entrada, ou consulte a referência da
API para os campos que cada uma aceita.
As consultas assíncronas sempre aguardam de forma síncrona sobre MCP:
a chamada da ferramenta retorna o resultado pronto, sem 202, polling
nem callbacks.
Qualquer cliente MCP
O AI SDK é uma opção. Como o endpoint fala MCP padrão sobre Streamable
HTTP, o
SDK oficial de MCP para TypeScript,
o LangChain e outros frameworks compatíveis com MCP se conectam da mesma forma:
aponte-os para https://api.croma.run/mcp e defina o cabeçalho
Authorization: Bearer.