---
title: "API v1 and the MCP server"
description: "Nine verbs over HTTP with one key, answers in JSON or Markdown, and an MCP server with OAuth for Claude, Cursor and other agents. Limits, scopes, errors and examples to copy."
url: https://scholaris.joseluissaorin.com/en/knowledge/api-and-mcp
markdown: https://scholaris.joseluissaorin.com/en/knowledge/api-and-mcp.md
lang: en
alternate_es: https://scholaris.joseluissaorin.com/saber/api-y-mcp.md
updated: 2026-10-06
author: José Luis Saorín Ferrer (https://joseluissaorin.com)
---

# API v1 and the MCP server

> Nine verbs over HTTP with one key, answers in JSON or Markdown, and an MCP server with OAuth for Claude, Cursor and other agents. Limits, scopes, errors and examples to copy.

## In one sentence

Everything the app does with your documents can be done from outside with an `Authorization: Bearer sch_…` header and nine verbs. The full guide, with a real recorded session, is at [/en/api](https://scholaris.joseluissaorin.com/en/api.md); the specification, in [OpenAPI 3.1](https://scholaris.joseluissaorin.com/api/v1/openapi.json); and the instructions for models, at [/api/v1/llms.txt](https://scholaris.joseluissaorin.com/api/v1/llms.txt). Field names are in Spanish.

## The verbs

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

| Method | Path | What it does |
| --- | --- | --- |
| POST | /documentos | Upload a file (raw body, multipart field «archivo» or JSON with «url») |
| GET | /documentos | List the library (q, estado, cursor; up to 200 per page) |
| GET | /documentos/{id} | The record; with esperar=30 it waits until it is read |
| DELETE | /documentos/{id} | Delete it with everything derived |
| GET | /documentos/{id}/texto | Text by printed page, [physical page] or time range |
| GET, POST | /buscar | Search passages (k up to 50) |
| POST | /preguntar | Answer with checked footnotes; stream by events |
| POST | /citar | Your text (or .docx) back with citations and bibliography |
| POST | /verificar | Does your library support a claim? |

Every read accepts `formato=markdown` or the header `Accept: text/markdown`. What takes time (uploading and citing) waits by default; with `esperar=0` or `Prefer: respond-async` it answers 202 with `progreso_url`.

```sh
export SCHOLARIS=sch_…   # Settings → API keys

# Upload (waits until read, up to 60 s; longer, 202 with 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

# Search, in 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

# Verify a claim
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_…")                      # or the SCHOLARIS_CLAVE variable
doc = s.subir("articulo.pdf")                # a URL works too
for p in s.buscar("atención escalada", k=3):
    print(p["cita"], p["texto"][:80], p["enlace"])
```

## Keys and scopes

Keys are created in Ajustes (Settings) → Claves de API (API keys) and shown only once; Scholaris stores only their SHA-256 hash. They can expire after as many days as you choose. Each key has scopes:

lectura (read)
: search, read, ask and verify.

escritura (write)
: upload and delete documents, and cite a whole text (autocite stores its work).

mcp
: use the key with the MCP server.

Without explicit scopes, a new key gets lectura and mcp.

## Limits

| | Free | Pro |
| --- | --- | --- |
| Requests per minute | 120 | 600 |
| Searches per day | 100 | 5,000 |
| Autocites per month | 5 | 500 |
| Pages or minutes read per month | 1,500 | 60,000 |
| File per API v1 request | 95 MB | 95 MB |

Going over the rate gives a 429 with `Retry-After`; using up a quota, a 402 (`cuota_superada` or `requiere_pro`). To retry without duplicating, send `Idempotency-Key` when uploading and citing: with the same key, for 24 hours, you get the same resource back. An identical file (same hash) returns the existing one, with `duplicado: true`.

## Errors

They all have the same shape, with the message in Spanish and English:

```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" } }
```

Codes: `no_autenticado` (401), `prohibido` (403), `peticion_invalida` (400), `no_encontrado` (404), `conflicto` (409), `demasiado_grande` (413), `cuota_superada` and `requiere_pro` (402), `limite_de_ritmo` (429), `proveedor_fallo` (502), `no_disponible` and `interno`.

## The MCP server

At `https://scholaris.joseluissaorin.com/mcp`, over HTTP (stateless Streamable HTTP). It offers four tools:

| Tool | What it does |
| --- | --- |
| search | Hybrid search; passages with their exact locator |
| cite | A CSL citation for a fragment or a document, in the requested style and language |
| open_page | The full text of a page, by physical position or printed folio |
| verify_claim | A verdict on a claim, with the passages that support or contradict it |

There are two ways to connect:

- **OAuth 2.1**, for Claude (web and desktop) and any client that speaks it: Settings → Connectors → Add custom connector, with the address `https://scholaris.joseluissaorin.com/mcp`. The client registers itself, you sign in to Scholaris and grant access. That access is read-only: search, open pages, cite and verify; it cannot upload, change or delete. Tokens last an hour and are refreshed.
- **A key** with the `mcp` scope, for Claude Code, Cursor, Windsurf and the rest:

```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_…" }
    }
  }
}
```

The OAuth metadata is where clients look for it: [/.well-known/oauth-authorization-server](https://scholaris.joseluissaorin.com/.well-known/oauth-authorization-server) and [/.well-known/oauth-protected-resource/mcp](https://scholaris.joseluissaorin.com/.well-known/oauth-protected-resource/mcp). There is also a server card at [/.well-known/mcp/server-card.json](https://scholaris.joseluissaorin.com/.well-known/mcp/server-card.json).

## For agents

The rules of use (cite only what the API returns, copy the citation verbatim, give the link, say when nothing is found) are on the [page for agents](https://scholaris.joseluissaorin.com/en/agents.md).