MCP

Croma Legal exposes the portfolio as tools over the Model Context Protocol (MCP), served over Streamable HTTP at:

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

Every tool is read-only and runs scoped to your organization. Two ways to authenticate are accepted:

OAuth, for interactive clients (Claude, ChatGPT, Cursor, and any client that supports dynamic client registration). The user signs in with their Croma Legal account and the tools run against their organization. Every member of the organization can connect this way; no API key needed.
API key, for your own code (AI SDK, scripts, agents). Send the same key as the REST API as a bearer token; the tools resolve straight to the organization that owns it. Usage and rate limits are shared with the REST API.

Connect Claude or ChatGPT

The dashboard’s Desarrolladores → Conexión MCP tab walks through the same steps with copy buttons. In short:

Claude
ChatGPT

Click Add Croma Legal to Claude: Claude opens Add custom connector with the name Croma Legal and the server URL https://api.legal.usecroma.com/mcp already filled in. (By hand: open Settings → Connectors, click + Add custom connector and paste them.)
Check the values and click Add.
Click Connect on the new connector and sign in with your Croma Legal account. The tools appear in every new chat.

In ChatGPT, go to Settings → Security and turn on Developer mode (custom connections need a paid plan).
Open Connectors, click +, name it Croma Legal and paste https://api.legal.usecroma.com/mcp.
Sign in with your Croma Legal account when prompted, then enable Croma Legal from the + menu in a chat.

The account you sign in with must belong to a Croma Legal organization. If it doesn’t, the connection succeeds but every tool answers that the account has no organization; ask an administrator to add you and reconnect.

Use it from the AI SDK

The AI SDK can load the tools directly and hand them to a model. Pass your key in the Authorization header of the transport:

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}` },
      },
    },
  ),
});

// The portfolio, exposed as tools the model can call.
const tools = await mcp.tools();

const { text } = await generateText({
  model: anthropic("claude-opus-4-8"),
  tools,
  // Consult the AI SDK docs for the multi-step setting in your version
  // (`stopWhen` / `maxSteps`) so the model can call tools and then answer.
  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);

Treat the key as a secret: load it from an environment variable or secrets manager, never commit it, and close the client (mcp.close()) when you are done so the connection is released.

Because the endpoint speaks standard MCP over Streamable HTTP, the official MCP TypeScript SDK, LangChain, and other MCP-aware frameworks connect the same way: point them at the URL and set the Authorization: Bearer header.

Tools

Thirteen tools cover the same data as the REST API, plus helpers that only make sense for an agent. Tool results are JSON; empty results come back as a short Spanish sentence, since the people reading them are Spanish speakers.

Tool	What it does	REST equivalent
`list_processes`	Search and list cases by radicado, defendant, office, city, status, priority, filing-date range and whether they have actuaciones.	`GET /v1/processes`
`get_process`	One case fully enriched, with its actuaciones timeline and the defendant’s imported data.	`GET /v1/processes/{id}`
`get_process_actions`	A case’s actuaciones, newest first, paginated.	`GET /v1/processes/{id}/actions`
`list_actions`	The organization-wide feed of recent actuaciones, filterable by radicado, keyword, defendant, office and `since`.	`GET /v1/actions`
`list_stale_processes`	Cases with no actuaciones in the last N days, most stale first. For impulso procesal reviews.	none
`list_defendants`	Defendants with case counts and imported data, searchable by identification number or name.	`GET /v1/defendants`
`get_defendant_processes`	Every case linked to one defendant.	`GET /v1/defendants/{id}/processes`
`get_analytics`	KPIs and distributions by office, city, status, priority, assignee and time.	`GET /v1/analytics`
`lookup_values`	Resolves a human-provided name into the exact stored value for `office`, `city`, `metadata`, `assignee` or `defendant`. Agents call it before filtering.	none
`export_data`	Generates a CSV or JSONL file with the complete filtered dataset. Waits inline up to 40 seconds, otherwise returns a `job_id`.	`POST /v1/exports`
`get_export`	Checks an export started with `export_data` and returns the download URL when ready.	`GET /jobs/{id}`
`describe_data`	Lists the views, columns, your organization’s own metadata fields and the rules for `query_data`.	none
`query_data`	Runs one read-only PostgreSQL `SELECT` over the `processes`, `actions`, `defendants` and `requests` views of your organization. For aggregations, joins and ad-hoc questions the other tools don’t cover.	none

Call mcp.tools() to get the full input schema of each tool.

Notes on `query_data`

The views are already filtered to your organization; there is no organization column to filter on.
One statement per call, SELECT (or WITH … SELECT) only. Results are capped at 500 rows (200 by default); when truncated is true, use export_data for the complete set.
Unfiltered queries over the full actuaciones history can exceed the statement timeout; bound them by date, office or defendant.
Measure procedural activity with the judicial dates (registration_date, last_action_date), never with action_created_at or last_discovery_date. describe_data spells out each column’s meaning.

Discovery

The server publishes its card at https://api.legal.usecroma.com/.well-known/mcp/server-card.json (name, description and the current tool list) and the OAuth metadata at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp, so clients that support auto-discovery need nothing beyond the URL.

REST API Reference

The same data over plain HTTP, with a playground.

Get Started

Guides

API Reference

Connect Claude or ChatGPT

Use it from the AI SDK

Tools

Notes on `query_data`

Discovery

REST API Reference

​Connect Claude or ChatGPT

​Use it from the AI SDK

​Tools

​Notes on query_data

​Discovery

REST API Reference

Connect Claude or ChatGPT

Use it from the AI SDK

Tools

Notes on `query_data`

Discovery