Endpoint MCP (apéndice para desarrollo)

Esta página es un apéndice técnico para desarrolladores. Si usas Paperzilla y quieres configurar MCP, empieza por Usar Paperzilla con MCP. Paperzilla expone un endpoint MCP mediante Streamable HTTP:

POST /api/mcp

Ejemplo de URL base:

https://paperzilla.ai/api/mcp

Para conocer una explicación breve del descubrimiento, consulta ¿Cómo descubren los clientes la URL y las herramientas de Paperzilla MCP?.

Autenticación

Envía tu clave de API de MCP de una de estas formas:

Authorization: Bearer pzmcp_<prefix>_<secret>

https://paperzilla.ai/api/mcp/?key=pzmcp_<prefix>_<secret>

Usa el encabezado si el cliente admite encabezados personalizados. Usa el parámetro de consulta si el cliente solo acepta una URL, incluido el flujo de conectores personalizados de Claude. En la mayoría de los casos, crea o revoca esta clave desde Clave de API de MCP, en la esquina superior derecha del panel. También puedes obtener o rotar la clave desde endpoints autenticados de la aplicación:

GET /api/auth/mcp-key
POST /api/auth/mcp-key/rotate
DELETE /api/auth/mcp-key

Estos endpoints de gestión usan el JWT normal de la aplicación, no la clave MCP.

Endpoints de gestión de claves (para desarrollo)

GET /api/auth/mcp-key
POST /api/auth/mcp-key/rotate
DELETE /api/auth/mcp-key

Métodos MCP utilizados actualmente

Paperzilla admite flujos MCP estándar, entre ellos:

initialize
tools/list
tools/call
prompts/list
prompts/get

Ejemplo de inicialización

Los ejemplos siguientes usan autenticación mediante encabezado.

curl -s -X POST https://paperzilla.ai/api/mcp \
  -H "Authorization: Bearer pzmcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-11-05",
      "capabilities":{},
      "clientInfo":{"name":"probe","version":"1.0"}
    }
  }'

Herramientas

Herramienta	Entrada
`projects_list`	`{}`
`projects_get`	`{ "project_id": "uuid" }`
`feed_get`	`{ "project_id": "uuid", "must_read"?: boolean, "since"?: string, "limit"?: 1..100, "offset"?: 0.. }`
`feed_search`	`{ "project_id": "uuid", "q": "string (3..200 chars after trim)", "feedback_filter"?: "enum", "must_read"?: boolean, "limit"?: 1..100, "offset"?: 0.. }`
`feed_atom_url`	`{ "project_id": "uuid" }`
`paper_get`	`{ "paper_id": "uuid-or-short-id-or-feed-item-id" }`
`paper_markdown`	`{ "paper_id": "uuid-or-short-id-or-feed-item-id" }`

Los nombres heredados con puntos, como paper.get, siguen aceptándose para la compatibilidad directa con tools/call, pero los clientes compatibles con Claude deben usar los nombres con guion bajo anteriores. El alias de búsqueda en la lista es feed.search. paper_get acepta los mismos tipos de identificadores que la API de artículos:

UUID del artículo
identificador del artículo short_id
project_paper identificado por UUID
project_paper short_id

projects_* y feed_* producen resultados con la misma estructura que las respuestas correspondientes de la API. feed_search es la vía MCP para buscar texto en toda la lista. Busca en el título, autor, resumen del artículo y resumen con IA de toda la lista del proyecto. feed_search.feedback_filter acepta:

all
unrated
liked
disliked
starred
not-relevant
low-quality

feed_search devuelve:

items
limit
offset
has_more
query

Semántica de búsqueda:

los términos de consulta usan coincidencia por prefijo, por lo que Proxi encuentra Proximity
la búsqueda ordena primero por relevancia, no por orden de navegación
en v1 no se devuelve un total exacto

paper_get devuelve los mismos campos de detalle que la API autenticada de artículos, incluido markdown_ready. Los detalles de artículos de PubMed usan PMID <number> como reference_label, conservan por separado el DOI cuando existe y enlazan con el registro de PubMed. pdf_url puede ser null; no supongas que un registro de PubMed dispone de texto completo público. paper_markdown siempre devuelve un objeto estructurado:

listo:

{
  "status": "ready",
  "paper_id": "uuid",
  "markdown": "# Markdown...",
  "mime_type": "text/markdown",
  "markdown_ready": true
}

queued:

{
  "status": "queued",
  "detail": "Markdown queued",
  "code": "markdown_queued",
  "job_id": "uuid",
  "created": true
}

unavailable:

{
  "status": "unavailable",
  "detail": "Markdown source unavailable",
  "code": "markdown_source_unavailable"
}

Ejemplos de llamadas a herramientas

Listar proyectos:

curl -s -X POST https://paperzilla.ai/api/mcp \
  -H "Authorization: Bearer pzmcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"projects_list",
      "arguments":{}
    }
  }'

Buscar en toda la lista de un proyecto:

curl -s -X POST https://paperzilla.ai/api/mcp \
  -H "Authorization: Bearer pzmcp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"feed_search",
      "arguments":{
        "project_id":"20a9c4fd-779a-41c7-92e9-efabc5e9eea5",
        "q":"latent retrieval",
        "feedback_filter":"all",
        "limit":20,
        "offset":0
      }
    }
  }'

Prompt

Nombre del prompt:

feed_title_filter

Argumentos:

project_id (obligatorio)
title_keyword (obligatorio)
must_read (opcional)
feedback_filter (opcional)
limit (opcional)

El prompt indica al modelo que llame a feed_search y explique que la búsqueda se realiza en el servidor sobre toda la lista.

Semántica de errores

Clave no válida o ausente: HTTP 401
No se permite el origen Origin: HTTP 403
Método MCP o estructura JSON-RPC no válidos: error de protocolo
Errores de negocio o dominio (propiedad, proyecto ausente, artículo ausente o ID corto ambiguo): resultado de herramienta con isError: true
paper_markdown en cola y los casos sin fuente disponible son resultados normales, no errores de herramienta

​Autenticación

​Endpoints de gestión de claves (para desarrollo)

​Métodos MCP utilizados actualmente

​Ejemplo de inicialización

​Herramientas

​Ejemplos de llamadas a herramientas

​Prompt

​Semántica de errores