La API v1 y el servidor MCP

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; la especificación, en OpenAPI 3.1; y las instrucciones para modelos, en /api/v1/llms.txt.

Los verbos

Base: https://scholaris-v2.jlsf2005.workers.dev/api/v1

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.

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-v2.jlsf2005.workers.dev/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-v2.jlsf2005.workers.dev/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-v2.jlsf2005.workers.dev/api/v1/verificar -H "Authorization: Bearer $SCHOLARIS" -H "Content-Type: application/json" \
  -d '{"afirmacion": "El Transformer prescinde de la recurrencia."}'

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

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:

{ "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-v2.jlsf2005.workers.dev/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-v2.jlsf2005.workers.dev/mcp, por HTTP («Streamable HTTP», sin estado). Ofrece cuatro herramientas:

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-v2.jlsf2005.workers.dev/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:

claude mcp add --transport http scholaris https://scholaris-v2.jlsf2005.workers.dev/mcp \
  --header "Authorization: Bearer sch_…"

{
  "mcpServers": {
    "scholaris": {
      "url": "https://scholaris-v2.jlsf2005.workers.dev/mcp",
      "headers": { "Authorization": "Bearer sch_…" }
    }
  }
}

Los metadatos de OAuth están donde los buscan los clientes: /.well-known/oauth-authorization-server y /.well-known/oauth-protected-resource/mcp. Hay además una tarjeta del servidor en /.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.