# API y MCP de RuleX · Referencia para desarrolladores y agentes

Interfaces públicas y verificables de RuleX: el servidor MCP `2025-06-18` de Rulex Data, la API REST equivalente, la consulta SECOP, el liquidador de intereses y el estado del sistema. Todas las herramientas son de solo lectura.

## Descubrimiento

- **OpenAPI 3.1:** https://rulex.org/api/openapi.json
- **Servidor MCP (Streamable HTTP):** https://rulex.org/api/mcp
- **Ficha del servidor MCP:** https://rulex.org/.well-known/mcp.json
- **Catálogo de API:** https://rulex.org/.well-known/api-catalog
- **Inventario para agentes:** https://rulex.org/llms.txt

## Autenticación

El servidor MCP responde **sin credencial** con las herramientas públicas (`buscar_licitaciones_secop`, `liquidar_intereses_cgp`) y un límite por minuto y por IP.

Con **API Key** se sirve el catálogo completo de Rulex Data. La clave se obtiene con sesión de navegador en https://rulex.org/dashboard, sección **API / MCP**, y se envía de tres formas equivalentes:

```http
Authorization: Bearer rx_data_live_...
X-API-Key: rx_data_live_...
POST /api/mcp?apiKey=rx_data_live_...
```

Regenerar la clave en el panel **revoca la anterior de inmediato**: las peticiones con la clave vieja devuelven 401.

## Cuotas

- Plan gratuito: **150 solicitudes/día**.
- RuleX Pro: **1500 solicitudes/día**.
- El día se corta a medianoche **hora de Colombia** (`America/Bogota`).
- Cada respuesta trae `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RuleX-Plan`.
- Una petición malformada no consume cuota: primero se valida y después se cobra.

## Herramientas de Rulex Data

| Herramienta | Qué consulta | Parámetros | Obligatorios |
| --- | --- | --- | --- |
| `rulex_rag_juridico` | RAG Jurídico de Colombia (Cortes y Doctrina) | query, fuente, limit | query |
| `rulex_secop_contratos` | Buscar Contratos y Licitaciones SECOP I y II | query, nit, tipo, modalidad, estado, limit | — |
| `rulex_rues_empresas` | Consulta Mercantil RUES y Cámaras de Comercio | query, nit, limit | — |
| `rulex_consulta_judicial` | Consulta Judicial de Procesos Rama Judicial | radicado, include_actuaciones, limit | radicado |
| `rulex_superfinanciera_trm` | TRM e Indicadores Oficiales Superfinanciera | tipo, fecha, limit | — |
| `rulex_sentencias_constitucionales` | Catálogo de Sentencias Corte Constitucional | query, limit | query |
| `rulex_liquidar_intereses` | Liquidador de Intereses CGP Superfinanciera | capital, fecha_inicio, fecha_corte, tipo_interes, tipo_proceso | capital, fecha_inicio, fecha_corte, tipo_interes |
| `rulex_supersociedades_financieros` | Estados Financieros NIIF Supersociedades | nit, query, statement, limit | — |
| `rulex_invima_registros` | Registros Sanitarios INVIMA | query, estado, limit | query |

Alias históricos conservados por compatibilidad: `buscar_licitaciones_secop`, `liquidar_intereses_cgp`.

## Llamarlas por MCP (JSON-RPC)

El endpoint implementa `initialize`, `ping`, `tools/list` y `tools/call`. Es stateless: no hay sesión que mantener ni stream SSE, y `GET /api/mcp` responde 405 a propósito.

```bash
curl -X POST "https://rulex.org/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rx_data_live_TU_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "rulex_rag_juridico",
      "arguments": {"query":"estabilidad laboral reforzada fuero de salud","limit":3}
    }
  }'
```

La respuesta trae el resultado dos veces: como texto en `result.content[0].text` y ya estructurado en `result.structuredContent`, validable contra el `outputSchema` que publica `tools/list`. Un fallo de ejecución llega como `result.isError: true`, no como error JSON-RPC.

## Llamarlas por REST

Para lenguajes o automatizaciones que no hablan JSON-RPC, el mismo catálogo está en `POST /api/data/query`.

```bash
curl -X POST "https://rulex.org/api/data/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rx_data_live_TU_API_KEY" \
  -d '{ "tool": "rulex_secop_contratos", "args": {"query":"suministro de medicamentos","tipo":"ambos","limit":5} }'
```

Devuelve `{ ok, tool, data, usage }`. El contenido de `data` es idéntico al `structuredContent` de MCP.

## Códigos de error

| Código | Cuándo aparece | Qué hacer |
| --- | --- | --- |
| 400 | Cuerpo inválido, argumentos que no son objeto o argumentos que la herramienta rechaza. | No consume cuota si el fallo es de formato. |
| 401 | Falta la API Key, es inválida o fue revocada al regenerarla. | Copia la clave vigente en el panel. |
| 403 | Petición de navegador desde otro origen y sin API Key. | Llama desde el servidor o autentícate. |
| 404 | La herramienta pedida no existe. | La respuesta lista los nombres válidos. |
| 413 | Cuerpo mayor a 200 KB. | Reduce la petición. |
| 429 | Cuota diaria agotada. | La cabecera Retry-After indica los segundos hasta la medianoche de Colombia. |

## Configuración por cliente

### Claude Desktop

`claude_desktop_config.json`

```json
{
  "mcpServers": {
    "rulex-data": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://rulex.org/api/mcp",
        "--header",
        "Authorization: Bearer rx_data_live_TU_API_KEY"
      ]
    }
  }
}
```

En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
En Windows: %APPDATA%\Claude\claude_desktop_config.json
Reinicia Claude Desktop después de guardar.

### ChatGPT

`Formulario del conector personalizado`

```text
Nombre: Rulex Data
URL del servidor MCP: https://rulex.org/api/mcp
Autenticación: OAuth
```

Pega la URL en «URL del servidor MCP» y elige OAuth: autorizas con tu cuenta de RuleX, sin copiar ninguna clave, y el conector sirve las 9 herramientas del catálogo. «Regenerar clave» revoca también esta conexión.

### Cursor IDE

`.cursor/mcp.json`

```json
{
  "mcpServers": {
    "rulex-data": {
      "type": "streamable-http",
      "url": "https://rulex.org/api/mcp",
      "headers": {
        "Authorization": "Bearer rx_data_live_TU_API_KEY"
      }
    }
  }
}
```

Guarda este archivo en la raíz de tu proyecto como .cursor/mcp.json o agrégalo en Cursor Settings > Features > MCP.

### Windsurf

`~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "rulex-data": {
      "serverUrl": "https://rulex.org/api/mcp",
      "headers": {
        "Authorization": "Bearer rx_data_live_TU_API_KEY"
      }
    }
  }
}
```

Configura en ~/.codeium/windsurf/mcp_config.json o en la pestaña Cascade MCP de Windsurf.

### Claude Code CLI

`Terminal command`

```bash
claude mcp add --transport http rulex-data https://rulex.org/api/mcp \
  --header "Authorization: Bearer rx_data_live_TU_API_KEY"
```

Ejecuta el comando en tu terminal para registrar Rulex Data en Claude Code. Añade --scope user para tenerlo en todos tus proyectos, o --scope project para compartirlo por .mcp.json con tu equipo.

### cURL / REST

`Terminal cURL`

```bash
curl -X POST "https://rulex.org/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rx_data_live_TU_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "rulex_secop_contratos",
      "arguments": { "query": "suministro alimentos salud", "limit": 3 }
    }
  }'
```

Llama al endpoint MCP JSON-RPC directamente desde cualquier lenguaje o flujo de automatización (n8n, Make, scripts).

### Python (SDK / HTTP)

`rulex_data.py`

```python
import httpx

RULEX_API_KEY = "rx_data_live_TU_API_KEY"
URL = "https://rulex.org/api/mcp"

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "rulex_rag_juridico",
        "arguments": {
            "query": "estabilidad laboral reforzada fuero de salud",
            "fuente": "corte_constitucional",
            "limit": 3
        }
    }
}

headers = {
    "Authorization": f"Bearer {RULEX_API_KEY}",
    "Content-Type": "application/json"
}

with httpx.Client() as client:
    response = client.post(URL, json=payload, headers=headers)
    data = response.json()
    print("Respuesta Rulex Data:", data["result"]["structuredContent"])

```

Compatible con Python 3.9+, LangChain, LlamaIndex, CrewAI y cualquier agente de IA.

## Otras rutas públicas

- `GET /api/secop` — búsqueda de licitaciones SECOP I y II sin credencial.
- `POST /api/liquidar-intereses` — liquidación de referencia con las tasas de la Superfinanciera; la respuesta trae sus propias advertencias de alcance.
- `GET /api/status` — estado operativo público.
- `POST /api/mcp` — servidor MCP, versión 2.0.0.

## Alcance y límites

Las fuentes de este servidor son colombianas: SECOP I y II, RUES, Rama Judicial, Superfinanciera, Supersociedades, INVIMA y el corpus jurídico de las altas cortes.

Los extractos jurisprudenciales son material de consulta con enlace a la fuente oficial: verifica la providencia completa antes de citarla en estrados. El liquidador entrega un cálculo de referencia y no determina por sí solo la tasa aplicable a una obligación.

## Representación

Esta es la representación Markdown de la misma página pública. Los navegadores reciben HTML en la URL canónica. No es una página distinta.

- **Canónica (HTML):** https://rulex.org/docs/api
- **Esta representación:** https://rulex.org/docs/api.md
- **Rulex Data (producto):** https://rulex.org/data.md
- **OpenAPI:** https://rulex.org/api/openapi.json
- **Precios:** https://rulex.org/pricing.md
- **Inicio:** https://rulex.org/
- **llms.txt:** https://rulex.org/llms.txt