> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Query your litigation portfolio as tools over MCP, from Claude, ChatGPT, Cursor or your own agent.
Croma Legal exposes the portfolio as tools over the [Model Context
Protocol](https://modelcontextprotocol.io) (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](/legal/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:
1. Click [Add Croma Legal to Claude](https://claude.ai/new?modal=add-custom-connector\&connectorName=Croma%20Legal\&connectorUrl=https%3A%2F%2Fapi.legal.usecroma.com%2Fmcp#settings/customize-connectors):
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.)
2. Check the values and click **Add**.
3. Click **Connect** on the new connector and sign in with your Croma Legal
account. The tools appear in every new chat.
1. In ChatGPT, go to **Settings → Security** and turn on **Developer mode**
(custom connections need a paid plan).
2. Open **Connectors**, click **+**, name it `Croma Legal` and paste
`https://api.legal.usecroma.com/mcp`.
3. 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](https://ai-sdk.dev) can load the tools directly and hand them to
a model. Pass your key in the `Authorization` header of the transport:
```ts theme={"dark"}
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](https://github.com/modelcontextprotocol/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`](/legal/api-reference/list-processes) |
| `get_process` | One case fully enriched, with its actuaciones timeline and the defendant's imported data. | [`GET /v1/processes/{id}`](/legal/api-reference/get-process) |
| `get_process_actions` | A case's actuaciones, newest first, paginated. | [`GET /v1/processes/{id}/actions`](/legal/api-reference/list-process-actions) |
| `list_actions` | The organization-wide feed of recent actuaciones, filterable by radicado, keyword, defendant, office and `since`. | [`GET /v1/actions`](/legal/api-reference/list-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`](/legal/api-reference/list-defendants) |
| `get_defendant_processes` | Every case linked to one defendant. | [`GET /v1/defendants/{id}/processes`](/legal/api-reference/list-defendant-processes) |
| `get_analytics` | KPIs and distributions by office, city, status, priority, assignee and time. | [`GET /v1/analytics`](/legal/api-reference/get-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`](/legal/api-reference/create-export) |
| `get_export` | Checks an export started with `export_data` and returns the download URL when ready. | [`GET /jobs/{id}`](/legal/api-reference/get-job) |
| `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.
The same data over plain HTTP, with a playground.