Jina AI Remote MCP Server

Versión CLI

Un servidor remoto del Model Context Protocol (MCP) que proporciona acceso a las APIs de Jina Reader, Embeddings y Reranker con un conjunto de herramientas de URL a markdown, búsqueda web, búsqueda de imágenes y herramientas de embeddings/reranker:

Las herramientas opcionales funcionan sin una API key, pero tienen límites de tasa. Para límites de tasa más altos y mejor rendimiento, usa una Jina API key. Puedes obtener una Jina API key gratuita en https://jina.ai

Uso

[!WARNING] Algunos clientes no admiten variables de entorno, por lo que es posible que tengas que sustituir ${JINA_API_KEY} a continuación por una API key real fija jina_xxx.

[!NOTE] El servidor usa transporte Streamable HTTP (spec MCP 2025-03-26). El endpoint /sse se conserva como alias para la compatibilidad con versiones anteriores. Consulta la FAQ para más detalles.

Para clientes que admiten un servidor MCP remoto:

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}" // optional
      }
    }
  }
}

Para clientes que aún no admiten un servidor MCP remoto, necesitas mcp-remote, un proxy local para conectarse al servidor MCP remoto.

{
  "mcpServers": {
    "jina-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.jina.ai/v1",
        "--header",
        "Authorization: Bearer ${JINA_API_KEY}"
      ]
    }
  }
}

Para Claude Code:

[!WARNING] ¿Actualizando versión desde /sse? Si anteriormente se agregó con el --transport sse, elimínalo primero con claude mcp remove -s user jina y vuelve a añadirlo con el comando de abajo.

claude mcp add -s user --transport http jina https://mcp.jina.ai/v1 \
  --header "Authorization: Bearer ${JINA_API_KEY}"

Para OpenAI Codex: abre ~/.codex/config.toml y añade lo siguiente:

[mcp_servers.jina-mcp-server]
command = "npx"
args = [
    "-y",
    "mcp-remote",
    "https://mcp.jina.ai/v1",
    "--header",
    "Authorization: Bearer ${JINA_API_KEY}"]

Related MCP server: Sentinel Core Agent

Filtrado de herramientas antes del registro

Cada herramienta MCP requiere que el LLM preasigne tokens en su ventana de contexto para el nombre, descripción y esquema de la herramienta. Para LLMs con ventanas de contexto limitadas, registrar las 22 herramientas puede consumir un espacio importante antes de empezar el trabajo real.

Al filtrar las herramientas del lado del servidor mediante parámetros de consulta en la URL del endpoint (/v1?...), las herramientas excluidas no pasan a registrarse nunca en el cliente de MCP. El cliente y el LLM nunca las ven, lo que ahorra espacio en la ventana de contexto para lo que importa.

Parámetros de consulta

Etiquetas disponibles

Precedencia

Los filtros se aplican en este orden (de mayor a menor prioridad):

1. exclude_tools: excluye siempre las herramientas especificadas.

2. exclude_tags: excluye las herramientas de las etiquetas especificadas.

3. include_tools: incluye las herramientas especificadas.

4. include_tags: empieza solo con las herramientas de las etiquetas especificadas.

Ejemplos

Excluir las herramientas paralelas (ahorra los tokens de contexto de unas ~4 herramientas):

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tags=parallel",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

Incluir solo las herramientas de búsqueda y lectura:

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?include_tags=search,read",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

Excluir herramientas específicas:

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tools=search_images,deduplicate_images",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

Solución de problemas

Me quedé atrapado en un bucle de llamadas a herramientas, ¿qué ha pasado?

Es un problema habitual con LM Studio cuando la ventana de contexto predeterminada es de 4096 y usas un modelo de razonamiento como gpt-oss-120b o qwen3-4b-thinking. A medida que continúan el razonamiento y las llamadas a herramientas, cuando alcanzas el límite de la ventana de contexto, la IA pierde el rastro del inicio de la tarea. Así es como acaba atrapada en una ventana de contexto que se va desplazando.

La solución es cargar el modelo con una longitud de contexto suficiente para que quepan la cadena completa de llamadas a herramientas y el proceso de razonamiento.

No puedo ver todas las herramientas

Algunos clientes MCP usan caché local y no actualizan activamente las definiciones de herramientas. Si no ves todas las herramientas disponibles o si parecen obsoletas, quizá tengas que eliminar y volver a añadir el jina-mcp-server en la configuración de tu cliente MCP. Así obligarás al cliente a refrescar la caché de definiciones de herramientas. En Claude Desktop puedes hacer clic en el botón de actualizar para cargar las herramientas nuevas.

Claude Desktop dice "Server disconnected" en Windows

Cursor y Claude Desktop (Windows) tienen un bug en el que los espacios en args no se escapan cuando se invoca npx, lo que acaba distorsionando estos valores. Puedes evitarlo con:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://mcp.jina.ai/v1",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <JINA_API_KEY>" // spaces OK in env vars
  }
},

Cursor muestra un punto rojo en el estado de este MCP

Probablemente sea un error del interfaz de Cursor, pero el MCP funciona correctamente y sin problemas. Si te molesta el punto rojo, puedes desactivarlo y activarlo para "reiniciar" el MCP (en realidad, al usarlo como MCP remoto, no es un "reinicio de servidor" de verdad, sino sobre todo un reinicio del proxy local).

Mi LLM nunca usa algunas herramientas

Si todas las herramientas están habilitadas en tu cliente MCP pero el LLM sigue sin usar algunas o prefiere unas sobre otras, es algo frecuente cuando el LLM se ha entrenado con un conjunto específico de herramientas. Por ejemplo, rara vez vemos que las herramientas parallel_* se usen de forma orgánica a menos que se les indique explícitamente. Algunas investigaciones sugieren que los LLM deben entrenarse para usar parallel_*. Modelos como Qwen3-Next prefieren de forma nativa llamar a la versión singleton pero con varias consultas en un array (lo que nuestro MCP también soporta ahora). En cualquier caso, en Cursor puedes añadir esta regla a tu archivo .mdc:

---
alwaysApply: true
---

When you are uncertain about knowledge, or the user doubts your answer, always use Jina MCP tools to search and read best practices and latest information. Use search_arxiv and read_url together when questions relate to theoretical deep learning or algorithm details. Use search_ssrn for social sciences, economics, law, and finance research. search_web, search_arxiv, and search_ssrn cannot be used alone - always combine with read_url or parallel_read_url to read from multiple sources. Remember: every search must be complemented with read_url to read the source URL content. For maximum efficiency, use parallel_* versions of search and read when necessary.

¿Por qué se trunca mi contenido?

Claude Code, Claude Desktop y Cursor aplican un límite fijo de 25k tokens a las respuestas de herramientas del MCP. Para evitar que estos clientes rechacen una respuesta grande por completo, este servidor aplica una protección de tokens a read_url y parallel_read_url.

Los elementos se conservan enteros en su orden original mientras quepan. El primero que no cabe se recorta hasta un prefijo que sí cabe y se descarta todo lo posterior. Se añade una nota breve [jina-mcp] ... en la que se dice qué se ha truncado u omitido, para que el modelo sepa que está viendo un documento parcial y no completo. Siempre sobrevive al menos un elemento, incluso si ese elemento solo supera el presupuesto.

El servidor busca a propósito quedarse por debajo del límite, no justo en él. Debe hacerlo: el servidor cuenta los tokens con cl100k, mientras que el cliente usa su propio tokenizador; el recorte es una estimación proporcional en caracteres, y el cliente mide el JSON serializado, no el texto crudo. Además del presupuesto de tokens, el servidor impone un límite fijo de 3 bytes por token permitido, que se mantiene tanto en la prosa ASCII (~3.6 bytes/token) como en CJK (~3 bytes/token), sea cual eres. Una respuesta rechazada no aporta nada, así que quedarse corto es el error más barato.

Cualquier cliente puede fijar su propio presupuesto con max_tokens en la URL del endpoint (por ejemplo https://mcp.jina.ai/v1?max_tokens=50000), y max_tokens=0 desactiva el truncado por completo. Los clientes con un límite configurable, como OpenAI Codex (tool_output_token_limit), no se tocan por lo demás.

Uso de herramientas parallel_* en lugar de las herramientas de clase única con arrays

Claude Code ha empezado a preferir recientemente las herramientas parallel_* (como parallel_search_web, parallel_read_url) para operaciones concurrentes. Sin embargo, a modelos como Qwen3-800: preferir llamar a herramientas de clase única con varias consultas en una array. Ambos enfoques funcionan: las versiones de clase única (search_web, search_arxiv, search_ssrn, read_url) usan no permitir ni una sola cadena o un array de cadenas para el será igual. Cuando se les da un array, estas herramientas ejecutan automáticamente todas las consultas en paralelo, de la misma forma concurrente que si se llamar explícitamente a las herramientas parallel_*. Usa la opción que prefiera tu modelo. El array tiene un máximo de 5 entradas, el mismo límite que funciona.

¿Por qué el endpoint se llama /sse y usa Streamable HTTP?

La URL del endpoint /sse se mantiene por compatibilidad con los usuarios existentes. El endpoint recomendado ahora es /v1. Ambos usan el mismo transporte Streamable HTTP (el nuevo estándar MCP de la especificación 2025-03-26), no el transporte SSE obsoleto.

Todo funciona bien porque:

• Claude Desktop de escritorio, Cursor y Windsurf usan mcp-remote, que por defecto intenta http-first (probar Streamable HTTP primero).

• **Claude Code tiene soporte nativa para ambos transportes.

• LM Studio soporta conexión direct a endpoints Streamable HTTP.

La respuesta en streaming sigue usando el formato SSE (Content-Type: text/event-stream+), tanto el protocolo en sí (gestión de sesión, inicialización) sigue la especificación Streamable HTTP. Todos los clientes MCP importantes son compatibles.

Filtrado de herramientas en el lado del cliente con mcp-remote

Si usasmcp-remote como proxy local, también puedes filtrar herramientas desde el cliente con el flag --ignore-tool:

{
  "mcpServers": {
    "jina-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.jina.ai/v1",
        "--header",
        "Authorization: Bearer ${JINA_API_KEY}",
        "--ignore-tool", "parallel_search_web",
        "--ignore-tool", "parallel_search_arxiv",
        "--ignore-tool", "parallel_read_url"
      ]
    }
  }
}

Este enfoque filtra las herramientas en el nivel del proxy antes de que se envíen al cliente MCP. Sin embargo, el filtrado en servidor mediante parámetros de consulta (ver Filtrado de herramientas) es más eficiente porque reduce el uso de tokens desde el origen.

Tool occlusion. Leer una página con una pregunta en mente

Por defecto, read_url devuelve toda la página, y el modelo paga por cada token para responder a una pregunta. Pasa question y la página se divide en pasajes que se puntúa con Reranker v3.5, y solo se devuelven los pasajes mejor clasificados: el mismo proceso que ejecuta search_web_deep sobre sus páginas de resultados, ahora disponible sobre una URL que ya tienes.

Los tres son opcionales y question es la llave de los otros dos, por lo que las llamadas existentes no cambian byte a byte.

// full page: 13,713 bytes, 233 ms
{ "url": "https://jina.ai/news/what-late-chunking-really-is-and-what-its-not-part-ii/" }

// one passage: 756 bytes (5.5%), 569 ms
{ "url": "https://jina.ai/news/what-late-chunking-really-is-and-what-its-not-part-ii/",
  "question": "Which embedding models support late chunking?", "topk": 2 }

Una respuesta basada en una pregunta lleva question, snippets y snippet_source: content, y omite content. Cuando la extracción no puede realizarse (página vacía, inutilizable o clave API), se devuelve el cuerpo completo con snippet_source: full_content y una nota que lo explica, en lugar de un prefijo que suplanta una respuesta ordenada.

Tres cosas sobre lo que conviene saber antes de afinar:

• La puntuación también funciona como señal de confianza. Preguntar a la página algo que no sabe produce una puntuación un orden de magnitud menor que un acierto real (medido: 0.02 contra 0.51-0.81). Una puntuación máxima baja significa "esta página no lo dice", no "el ranking falló".

• Los bloques de código y las tablas se eliminan antes del ordenamiento. El chunker los elimina junto con el menú de navegación, lo que evita que el boilerplate gane por coincidencia léxica. La contra es que los comandos de instalación y las tablas de spec no son candidatos a pasaje, "cómo instalo X" es más débil para este parámetro.

• La latencia es el doble que una lectura normal, ya que la extracción de pasajes se ejecuta en paralelo con la descarga y añade una llamada adicional al rerank. parallel_read_url aumenta su tiempo de espera mínimo a 60s cuando una entrada tiene question.

¿Qué diferencia hay entre search_web y search_web_deep?

search_web devuelve el fallo que eligió el buscador, suele ser unas 20 palabras, una palabra clave usada pero que no responde a la pregunta. search_web_deep además lee cada página mediante Reader, la divide en pasajes de ~100 palabras por los límites de frase y puntúa cada pasaje de cada página en una sola llamada listwise Reranker, de forma que los pasajes de una página pueden quedar por encima de los de cualquier. snippet_source=auto (el predeterminado) añade el snippet de motor de cada página como un candidato, y el campo snippet_source de cada resultado indica cuál ha ganado; content nunca entra en el ranking y omite las páginas que no pudo leer, por los que puede devolver menos de num.

Top 5 por modo desde el servidor real. Los snippets conservan el principio y el final; el medio se sustituye por (...n caracteres...) para que se vea el tamaño:

Inglés — what is the latest model from jina ai

中国 — jina ai 最新的模型是什么

• El fragmento del motor a veces es la mejor respuesta. Los tres primeros resultados auto en inglés regresaron como serp: son breves, y el primero responde a la pregunta de forma más directa que cualquier pasaje extraído, mientras que content promueve la navegación para a la página inicial de jina.ai en su lugar. Prioriza auto a menos que un proceso posterior necesite pasajes completos.

• El reranker puntúa relevancia, no frescura. Las dos ejecuciones deep en chino ubican en primer lugar un artículo de 2023 sobre jina-embeddings-v2 para una consulta sobre cuál es el modelo más reciente. Limita la ventana de tiempo con tbs, o revisa la date de cada resultado.

• Los pasajes no son por igual de ~100 palabras. Las páginas cargadas de navegación carecen de la puntuación de oraciones para dividir bien, de modo que los primeros resultados content en inglés alcanzan ~2000 caracteres, el techo por pasaje.

Guía de desarrollo

Desarrollo local

# Clone the repository
git clone https://github.com/jina-ai/MCP.git
cd MCP

# Install dependencies
npm install

# Start development server
npm run start

Despliegue en Cloudflare Workers

Esto desplegará tu servidor MCP en una URL como: jina-mcp-server.<your-account>.workers.dev/v1