Cómo añadir Parallel Search MCP a un agente: búsqueda sin clave, lectura web y límites de coste

Puedes conectar Parallel Search MCP sin mantener un buscador propio ni solicitar una API Key de búsqueda. Parallel publica el endpoint Streamable HTTP https://search.parallel.ai/mcp, que expone dos herramientas al agente: web_search y web_fetch.

Guardar una configuración no demuestra que la integración funcione. La comprobación útil consiste en ver el estado de conexión, confirmar que ambas herramientas aparecen, inspeccionar el evento de llamada en la conversación y abrir las URL devueltas. Los datos siguientes se contrastaron con páginas oficiales abiertas el 11 de octubre de 2026; los registros y la facturación de tu entorno siguen siendo la prueba final.

Elige primero el endpoint y el modo de autenticación

Objetivo	Endpoint	Autenticación	Uso recomendado
Probar búsqueda y lectura	https://search.parallel.ai/mcp	Ninguna	Exploración ligera con límites anónimos más bajos
Usar créditos de cuenta y límites superiores	https://search.parallel.ai/mcp	Bearer API Key	Carga periódica o de producción
Dejar que el cliente gestione el inicio de sesión	https://search.parallel.ai/mcp-oauth	OAuth o Bearer API Key	Evitar una clave fija en configuraciones compartidas

El endpoint /mcp no anuncia OAuth, por lo que un cliente compatible puede conectarse de forma anónima sin abrir el navegador. /mcp-oauth sí exige autenticación y devuelve 401 a una petición anónima. Que /mcp no muestre una pantalla de acceso no es un fallo; un 401 en /mcp-oauth suele indicar que la autorización no terminó.

Separa cliente, herramienta web y proveedor de modelo

Una respuesta puede recorrer tres conexiones independientes:

1. El cliente del agente gestiona conversación, permisos y selección de herramientas.
2. Parallel Search MCP ejecuta web_search y web_fetch.
3. El proveedor del modelo razona y contabiliza tokens de entrada, salida y resultados de herramientas.

Añadir MCP no sustituye el Base URL del modelo. Cambiar el proveedor del modelo tampoco añade búsqueda web. Al diagnosticar, plantea tres preguntas distintas: ¿se conectó el cliente al MCP?, ¿se llamó realmente a la herramienta?, ¿qué proveedor facturó la petición del modelo?

Claude Code: empieza por el endpoint anónimo

Ejecuta desde el proyecto en el que utilizas Claude Code:

claude mcp add --transport http "Parallel-Search-MCP" https://search.parallel.ai/mcp
claude mcp get "Parallel-Search-MCP"
claude mcp list

Claude Code guarda el servidor en el ámbito local por defecto. Añade --scope user solo cuando quieras usarlo en todos tus proyectos. Si compartes .mcp.json con un equipo, revisa el archivo y no incluyas un bearer token fijo.

Dentro de Claude Code abre el panel:

/mcp

El mensaje Added confirma que se escribió la configuración; el estado Connected confirma que el cliente actual alcanza el servidor. Para OAuth usa en su lugar:

https://search.parallel.ai/mcp-oauth

Completa la autorización desde /mcp y no mezcles los fallos de /mcp con los de /mcp-oauth.

Codex CLI: anónimo, bearer desde una variable u OAuth

Configuración anónima:

codex mcp add parallel-search --url https://search.parallel.ai/mcp
codex mcp list

Para usar límites asociados a una cuenta, guarda PARALLEL_API_KEY en el sistema operativo o en un gestor de secretos. Pasa a Codex el nombre de la variable, no el valor real, para que la clave no quede en el historial del shell ni en un archivo compartido:

codex mcp add parallel-search --url https://search.parallel.ai/mcp \
  --bearer-token-env-var PARALLEL_API_KEY
codex mcp list

Con OAuth:

codex mcp add parallel-search --url https://search.parallel.ai/mcp-oauth
codex mcp list

Inicia una sesión nueva de Codex después de añadir el servidor. Otros clientes MCP usan el mismo endpoint, pero no el mismo esquema: VS Code tiene el objeto superior servers, Cursor suele usar mcpServers y algunos clientes requieren type: "streamable-http". No copies el JSON de un cliente a otro sin revisarlo.

Demuestra qué herramienta se llamó realmente

Un servidor conectado solo demuestra accesibilidad. Para verificar una respuesta concreta, utiliza un prompt que deje evidencia observable:

Para esta comprobación, usa obligatoriamente Parallel-Search-MCP y no respondas de memoria.
1. Llama a web_search para localizar la documentación oficial de Parallel Search MCP y la página de precios actual.
2. Muestra las URL de origen devueltas por web_search.
3. Elige dos URL oficiales y llama a web_fetch para leer el texto original.
4. Para cada fuente, indica nombre de herramienta, URL y un fragmento breve de apoyo.
Si falla una llamada, detente e informa de la herramienta, el endpoint y el estado HTTP.

Comprueba después cuatro niveles:

• el registro de herramientas contiene web_search;
• aparece una llamada posterior a web_fetch, no solo un resumen de snippets;
• el resultado incluye URL reales que se pueden abrir;
• la afirmación final existe en el contenido recuperado.

La frase «he buscado en la web» no es una prueba. Si el cliente permite desactivar temporalmente su buscador integrado, hazlo durante esta prueba aislada para evitar confundir dos herramientas parecidas.

Busca primero y recupera después las páginas originales

La división oficial es clara:

• web_search encuentra información reciente y fuentes diversas. Requiere objective y search_queries.
• web_fetch lee URL conocidas o comprueba resultados seleccionados. Acepta hasta 20 URL por petición.

Cuando el cliente permita influir en los argumentos:

1. Escribe un único objetivo en objective, por ejemplo «comprobar las reglas oficiales de acceso anónimo y los límites de coste».
2. Usa dos o tres search_queries breves y complementarias; no copies todo el prompt.
3. Reutiliza el mismo session_id dentro de una conversación y crea otro para una conversación nueva.
4. Mantén full_content: false hasta que necesites realmente la página completa. El contenido íntegro puede consumir decenas de miles de tokens del modelo y superar el límite de salida del cliente.
5. Prioriza documentación, especificaciones y anuncios originales. Una publicación de la comunidad debe presentarse como informe de usuario, no como comportamiento universal.

El circuito búsqueda → selección de URL → lectura del original → verificación de citas es mucho más auditable que una instrucción genérica de «búscalo».

Límites de coste: lleva al menos cuatro cuentas

Los precios siguientes se verificaron en la página oficial de Parallel el 11 de octubre de 2026. Sirven para separar facturas, no para afirmar que una opción siempre sea más barata.

Capa de coste	Suscripción o membresía	Recarga mínima	Crédito del primer mes	Unidad de uso
Search MCP anónimo	La configuración anónima documentada no exige suscripción de cuenta	No exige recarga para comenzar de forma anónima	No se publica un número fijo de llamadas	Se describe como gratuito para exploración y uso ligero, con límites inferiores
Parallel Search/Extract autenticado	La página pública de precios no indica una cuota de membresía aparte	No se especifica	No se especifica un crédito inicial fijo	Precio base de Search (10 resultados incluidos por petición): fast/turbo US$1 por 1.000 peticiones; basic/advanced US$5; resultados de página y extractos adicionales: US$1 por 1.000 resultados; Extract: US$1 por 1.000 URL
Cliente del agente	Depende de Claude Code, Codex u otro cliente	Depende del cliente	Depende del cliente	Los beneficios del plan del cliente no son créditos de Parallel
API del modelo	Depende del proveedor	Depende del proveedor	Depende del proveedor	Entrada, salida, caché y contexto de resultados se facturan aparte del Search MCP

La página de Search MCP no publica una cuota anónima numérica fija. No conviertas «lower rate limits» en una promesa inventada de N búsquedas gratuitas. Tampoco presentes la tabla general de rate limits de la API como garantía del MCP anónimo.

Si una conexión autenticada devuelve 402, la documentación de Parallel lo atribuye a créditos insuficientes. Revisa el saldo y el modo de conexión antes de reintentar.

Si BetterToken aporta el modelo, mantén ambas configuraciones independientes

Puedes conservar Claude Code o Codex como cliente y añadir Parallel solo como capa de herramientas web:

• En Claude Code con BetterToken, el Base URL del modelo es https://bettertoken.ai; el cliente añade /v1/messages, por lo que no debes añadir /v1 manualmente.
• En Codex con BetterToken, el Base URL es https://www.bettertoken.ai/v1 y se mantiene wire_api = "responses".
• El endpoint de Parallel sigue siendo https://search.parallel.ai/mcp o https://search.parallel.ai/mcp-oauth.

Estas URL no son intercambiables. BetterToken gestiona las peticiones del modelo y su consumo de tokens; Parallel gestiona las herramientas web. Disponibilidad anónima, créditos, privacidad y límites siguen las reglas del servicio externo. Consulta por separado la guía de Claude Code, la guía de Codex y la documentación de Parallel Search MCP.

Fallos habituales y prueba mínima posterior

Síntoma	Revisa primero	Cómo volver a probar
El servidor está añadido, pero no aparecen herramientas	Reinicia por completo; valida sintaxis y URL exacta; abre los logs MCP	Deben aparecer web_search y web_fetch
401	Uso de /mcp-oauth, finalización de OAuth y validez del bearer	Reconecta y confirma que desaparece la petición de autenticación
402	Créditos de la cuenta autenticada	Añade saldo o vuelve a /mcp anónimo y ejecuta una búsqueda acotada
Conectado, pero sin llamadas	El agente puede usar el buscador interno o la memoria	Ejecuta el prompt forzado e inspecciona el trace
Resultado enorme o truncado	full_content, demasiadas URL u objetivo amplio	Desactiva el contenido completo y recupera solo páginas relevantes
Comportamiento distinto entre proyectos	Scope de Claude Code, aprobación del proyecto o sesión antigua de Codex	Lista de nuevo los servidores en el proyecto y repite la llamada

Cuándo merece la pena conservarlo

Es una buena opción si necesitas búsqueda alojada y lectura de páginas sin administrar SearXNG, el cliente muestra llamadas y fuentes, y el límite anónimo basta para tareas ligeras o puedes presupuestar el uso autenticado.

No lo lleves directamente a producción si necesitas un número gratuito fijo garantizado públicamente, atribución organizativa o Zero Data Retention manteniéndote anónimo, no puedes inspeccionar las llamadas reales, o necesitas control total del índice, el crawler y la residencia de datos.

La secuencia más segura es probar tareas representativas con /mcp anónimo, guardar los traces y las URL, medir límites y crecimiento de tokens del modelo, y pasar a Bearer o /mcp-oauth solo cuando el modo anónimo sea el cuello de botella. Así conexión, calidad de recuperación, coste externo y coste del modelo quedan separados y verificables.