MCP

Croma Legal expone el portafolio como herramientas sobre el Model Context Protocol (MCP), servido por Streamable HTTP en:

https://api.legal.usecroma.com/mcp

Todas las herramientas son de solo lectura y corren limitadas a tu organización. Se aceptan dos formas de autenticación:

OAuth, para clientes interactivos (Claude, ChatGPT, Cursor y cualquier cliente que soporte registro dinámico de clientes). El usuario inicia sesión con su cuenta de Croma Legal y las herramientas corren contra su organización. Todos los miembros de la organización pueden conectarse así; no hace falta clave de API.
Clave de API, para tu propio código (AI SDK, scripts, agentes). Envía la misma clave de la API REST como token bearer; las herramientas resuelven directamente a la organización dueña de la clave. El uso y los límites de tasa se comparten con la API REST.

Conecta Claude o ChatGPT

La pestaña Desarrolladores → Conexión MCP del dashboard recorre estos mismos pasos con botones de copiar. En resumen:

Claude
ChatGPT

Haz clic en Agregar Croma Legal a Claude: Claude abre Add custom connector con el nombre Croma Legal y la URL del servidor https://api.legal.usecroma.com/mcp ya diligenciados. (A mano: abre Configuración → Conectores, haz clic en + Add custom connector y pégalos.)
Revisa los valores y haz clic en Add.
Haz clic en Connect sobre el nuevo conector e inicia sesión con tu cuenta de Croma Legal. Las herramientas aparecen en cada chat nuevo.

En ChatGPT, ve a Configuración → Seguridad y activa Developer mode (las conexiones personalizadas requieren un plan de pago).
Abre Connectors, haz clic en +, nómbralo Croma Legal y pega https://api.legal.usecroma.com/mcp.
Inicia sesión con tu cuenta de Croma Legal cuando te lo pida y habilita Croma Legal desde el menú + en un chat.

La cuenta con la que inicias sesión debe pertenecer a una organización de Croma Legal. Si no, la conexión se establece pero cada herramienta responde que la cuenta no tiene organización; pide a un administrador que te agregue y vuelve a conectar.

Úsalo desde el AI SDK

El AI SDK puede cargar las herramientas directamente y entregárselas a un modelo. Pasa tu clave en el encabezado Authorization del transporte:

import { experimental_createMCPClient as createMCPClient, generateText } from "ai";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { anthropic } from "@ai-sdk/anthropic";

const mcp = await createMCPClient({
  transport: new StreamableHTTPClientTransport(
    new URL("https://api.legal.usecroma.com/mcp"),
    {
      requestInit: {
        headers: { Authorization: `Bearer ${process.env.CROMA_LEGAL_API_KEY}` },
      },
    },
  ),
});

// El portafolio, expuesto como herramientas que el modelo puede llamar.
const tools = await mcp.tools();

const { text } = await generateText({
  model: anthropic("claude-opus-4-8"),
  tools,
  // Consulta en la documentación del AI SDK el ajuste multi-paso de tu versión
  // (`stopWhen` / `maxSteps`) para que el modelo llame herramientas y luego responda.
  prompt: "¿Cuántos procesos llevan más de 90 días sin actuaciones? Lista los diez más antiguos.",
});

await mcp.close();
console.log(text);

Trata la clave como un secreto: cárgala desde una variable de entorno o un gestor de secretos, nunca la incluyas en el control de versiones y cierra el cliente (mcp.close()) cuando termines para liberar la conexión.

Como el endpoint habla MCP estándar sobre Streamable HTTP, el SDK oficial de MCP para TypeScript, LangChain y otros frameworks compatibles con MCP se conectan igual: apúntalos a la URL y configura el encabezado Authorization: Bearer.

Herramientas

Trece herramientas cubren los mismos datos que la API REST, más ayudas que solo tienen sentido para un agente. Los resultados son JSON; los resultados vacíos vuelven como una frase corta en español.

Herramienta	Qué hace	Equivalente REST
`list_processes`	Busca y lista procesos por radicado, demandado, despacho, ciudad, estado, prioridad, rango de fecha de radicación y si tienen actuaciones.	`GET /v1/processes`
`get_process`	Un proceso completo, con su línea de tiempo de actuaciones y los datos importados del demandado.	`GET /v1/processes/{id}`
`get_process_actions`	Las actuaciones de un proceso, más recientes primero, paginadas.	`GET /v1/processes/{id}/actions`
`list_actions`	El feed de actuaciones recientes de toda la organización, filtrable por radicado, palabra clave, demandado, despacho y `since`.	`GET /v1/actions`
`list_stale_processes`	Procesos sin actuaciones en los últimos N días, los más estancados primero. Para revisiones de impulso procesal.	ninguno
`list_defendants`	Demandados con número de procesos y datos importados, buscables por número de identificación o nombre.	`GET /v1/defendants`
`get_defendant_processes`	Todos los procesos vinculados a un demandado.	`GET /v1/defendants/{id}/processes`
`get_analytics`	KPIs y distribuciones por despacho, ciudad, estado, prioridad, abogado asignado y tiempo.	`GET /v1/analytics`
`lookup_values`	Resuelve un nombre escrito por una persona al valor exacto almacenado para `office`, `city`, `metadata`, `assignee` o `defendant`. Los agentes la llaman antes de filtrar.	ninguno
`export_data`	Genera un archivo CSV o JSONL con el conjunto de datos completo y filtrado. Espera en línea hasta 40 segundos; si no, devuelve un `job_id`.	`POST /v1/exports`
`get_export`	Consulta una exportación iniciada con `export_data` y devuelve la URL de descarga cuando está lista.	`GET /jobs/{id}`
`describe_data`	Lista las vistas, columnas, los campos propios de tu organización y las reglas de `query_data`.	ninguno
`query_data`	Ejecuta un `SELECT` de PostgreSQL de solo lectura sobre las vistas `processes`, `actions`, `defendants` y `requests` de tu organización. Para agregaciones, cruces y preguntas ad hoc que las otras herramientas no cubren.	ninguno

Llama a mcp.tools() para obtener el esquema de entrada completo de cada herramienta.

Notas sobre `query_data`

Las vistas ya están filtradas por tu organización; no hay una columna de organización por la que filtrar.
Una sentencia por llamada, solo SELECT (o WITH … SELECT). Los resultados se limitan a 500 filas (200 por defecto); cuando truncated es true, usa export_data para el conjunto completo.
Las consultas sin filtro sobre todo el histórico de actuaciones pueden superar el tiempo límite; acótalas por fecha, despacho o demandado.
Mide la actividad procesal con las fechas judiciales (registration_date, last_action_date), nunca con action_created_at ni con last_discovery_date. describe_data explica el significado de cada columna.

Descubrimiento

El servidor publica su tarjeta en https://api.legal.usecroma.com/.well-known/mcp/server-card.json (nombre, descripción y la lista actual de herramientas) y los metadatos OAuth en /.well-known/oauth-authorization-server y /.well-known/oauth-protected-resource/mcp, así que los clientes con autodescubrimiento no necesitan nada más que la URL.

Referencia de la API REST

Los mismos datos por HTTP plano, con un playground.

Primeros pasos

Guías

Referencia de API

Conecta Claude o ChatGPT

Úsalo desde el AI SDK

Herramientas

Notas sobre `query_data`

Descubrimiento

Referencia de la API REST

​Conecta Claude o ChatGPT

​Úsalo desde el AI SDK

​Herramientas

​Notas sobre query_data

​Descubrimiento

Referencia de la API REST

Conecta Claude o ChatGPT

Úsalo desde el AI SDK

Herramientas

Notas sobre `query_data`

Descubrimiento