---
title: "La API v1 y el servidor MCP"
description: "Nueve verbos sobre HTTP con una clave, respuestas en JSON o Markdown, y un servidor MCP con OAuth para Claude, Cursor y otros agentes. Límites, alcances, errores y ejemplos para copiar."
url: https://scholaris.joseluissaorin.com/saber/api-y-mcp
markdown: https://scholaris.joseluissaorin.com/saber/api-y-mcp.md
lang: es
alternate_en: https://scholaris.joseluissaorin.com/en/knowledge/api-and-mcp.md
updated: 2026-10-06
author: José Luis Saorín Ferrer (https://joseluissaorin.com)
---

# La API v1 y el servidor MCP

> Nueve verbos sobre HTTP con una clave, respuestas en JSON o Markdown, y un servidor MCP con OAuth para Claude, Cursor y otros agentes. Límites, alcances, errores y ejemplos para copiar.

## En una frase

Todo lo que hace la aplicación con tus documentos se puede hacer desde fuera con una cabecera `Authorization: Bearer sch_…` y nueve verbos. La guía completa, con una sesión grabada de verdad, está en [/api](https://scholaris.joseluissaorin.com/api.md); la especificación, en [OpenAPI 3.1](https://scholaris.joseluissaorin.com/api/v1/openapi.json); y las instrucciones para modelos, en [/api/v1/llms.txt](https://scholaris.joseluissaorin.com/api/v1/llms.txt).

## Los verbos

Base: `https://scholaris.joseluissaorin.com/api/v1`

| Método | Ruta | Qué hace |
| --- | --- | --- |
| POST | /documentos | Sube un fichero (cuerpo crudo, multipart con «archivo» o JSON con «url») |
| GET | /documentos | Lista la biblioteca (q, estado, cursor; hasta 200 por página) |
| GET | /documentos/{id} | La ficha; con esperar=30 espera a que esté leído |
| DELETE | /documentos/{id} | Lo borra con todo lo derivado |
| GET | /documentos/{id}/texto | El texto por página impresa, [página física] o tramo de tiempo |
| GET, POST | /buscar | Busca pasajes (k hasta 50) |
| POST | /preguntar | Responde con notas comprobadas; por eventos con stream |
| POST | /citar | Tu texto (o tu .docx) con las citas y la bibliografía |
| POST | /verificar | ¿Respalda tu biblioteca una afirmación? |

Cualquier lectura admite `formato=markdown` o la cabecera `Accept: text/markdown`. Lo que tarda (subir y citar) espera por defecto; con `esperar=0` o `Prefer: respond-async` responde 202 con `progreso_url`.

```sh
export SCHOLARIS=sch_…   # Ajustes → Claves de API

# Subir (espera a que esté leído, hasta 60 s; si tarda más, 202 y progreso_url)
curl -s "https://scholaris.joseluissaorin.com/api/v1/documentos?nombre=articulo.pdf" -H "Authorization: Bearer $SCHOLARIS" \
  -H "Content-Type: application/pdf" --data-binary @articulo.pdf

# Buscar, en Markdown
curl -sG https://scholaris.joseluissaorin.com/api/v1/buscar -H "Authorization: Bearer $SCHOLARIS" \
  --data-urlencode "q=atención escalada" -d k=5 -d formato=markdown

# Verificar una afirmación
curl -s https://scholaris.joseluissaorin.com/api/v1/verificar -H "Authorization: Bearer $SCHOLARIS" -H "Content-Type: application/json" \
  -d '{"afirmacion": "El Transformer prescinde de la recurrencia."}'
```

```py
from scholaris.api import Scholaris

s = Scholaris("sch_…")                      # o la variable SCHOLARIS_CLAVE
doc = s.subir("articulo.pdf")                # también una URL
for p in s.buscar("atención escalada", k=3):
    print(p["cita"], p["texto"][:80], p["enlace"])
```

## Claves y alcances

Las claves se crean en Ajustes → Claves de API y se enseñan una sola vez; Scholaris solo guarda su huella SHA-256. Pueden caducar al cabo de los días que elijas. Cada clave tiene alcances:

lectura
: buscar, leer, preguntar y verificar.

escritura
: subir y borrar documentos, y citar un texto entero (la autocita guarda su trabajo).

mcp
: usar la clave en el servidor MCP.

Sin alcances explícitos, una clave nueva tiene lectura y mcp.

## Límites

| | Gratis | Pro |
| --- | --- | --- |
| Peticiones por minuto | 120 | 600 |
| Búsquedas al día | 100 | 5000 |
| Autocitas al mes | 5 | 500 |
| Páginas o minutos leídos al mes | 1500 | 60 000 |
| Fichero por petición en la API v1 | 95 MB | 95 MB |

Al pasarse del ritmo se recibe un 429 con `Retry-After`; al agotar una cuota, un 402 (`cuota_superada` o `requiere_pro`). Para reintentar sin duplicar, `Idempotency-Key` en subir y citar: con la misma clave, durante 24 horas, se devuelve el mismo recurso. Un fichero idéntico (misma huella) devuelve el que ya había, con `duplicado: true`.

## Errores

Todos tienen la misma forma, con el mensaje en castellano y en inglés:

```json
{ "error": { "codigo": "prohibido", "mensaje": "Esta clave de API es de solo lectura.", "message": "This key is not allowed to do that.", "estado": 403, "documentacion": "https://scholaris.joseluissaorin.com/api#errores" } }
```

Códigos: `no_autenticado` (401), `prohibido` (403), `peticion_invalida` (400), `no_encontrado` (404), `conflicto` (409), `demasiado_grande` (413), `cuota_superada` y `requiere_pro` (402), `limite_de_ritmo` (429), `proveedor_fallo` (502), `no_disponible` e `interno`.

## El servidor MCP

En `https://scholaris.joseluissaorin.com/mcp`, por HTTP («Streamable HTTP», sin estado). Ofrece cuatro herramientas:

| Herramienta | Qué hace |
| --- | --- |
| search | Búsqueda híbrida; pasajes con su localizador exacto |
| cite | Cita CSL de un fragmento o de un documento, en el estilo y la lengua que se pidan |
| open_page | El texto entero de una página, por posición física o por folio impreso |
| verify_claim | Veredicto sobre una afirmación, con los pasajes que la apoyan o la contradicen |

Para conectarse hay dos caminos:

- **OAuth 2.1**, para Claude (web y escritorio) y cualquier cliente que lo hable: Ajustes → Conectores → Añadir conector personalizado, con la dirección `https://scholaris.joseluissaorin.com/mcp`. El cliente se registra solo, tú entras en Scholaris y concedes acceso. Ese acceso es de solo lectura: buscar, abrir páginas, citar y verificar; no puede subir, cambiar ni borrar. Los tokens duran una hora y se renuevan.
- **Una clave** con el alcance `mcp`, para Claude Code, Cursor, Windsurf y los demás:

```sh
claude mcp add --transport http scholaris https://scholaris.joseluissaorin.com/mcp \
  --header "Authorization: Bearer sch_…"
```

```json
{
  "mcpServers": {
    "scholaris": {
      "url": "https://scholaris.joseluissaorin.com/mcp",
      "headers": { "Authorization": "Bearer sch_…" }
    }
  }
}
```

Los metadatos de OAuth están donde los buscan los clientes: [/.well-known/oauth-authorization-server](https://scholaris.joseluissaorin.com/.well-known/oauth-authorization-server) y [/.well-known/oauth-protected-resource/mcp](https://scholaris.joseluissaorin.com/.well-known/oauth-protected-resource/mcp). Hay además una tarjeta del servidor en [/.well-known/mcp/server-card.json](https://scholaris.joseluissaorin.com/.well-known/mcp/server-card.json).

## Para agentes

Las reglas de uso (citar solo lo que devuelve la API, copiar la cita tal cual, dar el enlace, decir cuándo no se encuentra nada) están en la [hoja para agentes](https://scholaris.joseluissaorin.com/agentes.md).