Cómo conectar el agente Pi a la web: Guía de integración del servidor MCP sin scrapear

Conclusiones clave:

• Pi Agent es un agente de codificación basado en terminal deliberadamente minimalista. Viene con cuatro herramientas (read, write, edit, bash) y añade todo lo demás a través de extensiones opcionales, lo que mantiene la ventana de contexto pequeña, pero significa que el acceso a la web no está integrado.
• pi-mcp-adapter conecta a Pi con cualquier servidor MCP a través de un único proxy de aproximadamente 200 tokens. Los servidores son perezosos por defecto: solo comienzan cuando el agente llama a una de sus herramientas, por lo que conectar varios servidores MCP no inflará el presupuesto de contexto.
• El Scrapeless MCP Server expone 21 herramientas a través de stdio y mediante un endpoint HTTP transmisible en https://api.scrapeless.com/mcp. La cobertura abarca google_search, google_trends, la superficie completa de 16 herramientas browser_* (un navegador anti-detección alojado en la nube con proxies residenciales en más de 195 países) y tres herramientas de raspado sin estado (scrape_html, scrape_markdown, scrape_screenshot).
• Un archivo .mcp.json conecta a Pi con Scrapeless. El adaptador lee el formato de configuración MCP estándar que ya utilizan Claude Desktop, Cursor y otros clientes MCP, por lo que el mismo fragmento de JSON se puede usar en cualquiera de ellos.
• El patrón de extremo a extremo: prompt → Pi → pi-mcp-adapter → scrapeless-mcp-server → navegador en la nube → resultados clasificados o Markdown extraído → código generado basado en datos en vivo. Pi deja de generar a partir de conocimientos solo de entrenamiento y comienza a fundamentar la salida en la página que acaba de raspar.
• Gratis para comenzar. Las nuevas cuentas de Scrapeless incluyen tiempo de ejecución gratuito para el Raspador de Navegación — regístrate en app.scrapeless.com.

Introducción: un agente de codificación minimalista con herramientas web en vivo

La mayoría de los agentes de codificación en terminal vienen con docenas de características que es posible que nunca uses. Pi Agent adopta la postura opuesta: cuatro herramientas, total transparencia, todo lo demás agregado a pedido. Esto mantiene al agente rápido y la ventana de contexto económica, pero también significa que Pi no puede buscar la documentación más reciente para una biblioteca, leer una página de lanzamiento que fue publicada la semana pasada o extraer datos en vivo de una página web pública por sí solo.

La solución es conectar a Pi con un servidor del Protocolo de Contexto del Modelo (MCP) que exponga herramientas web. El paquete scrapeless-mcp-server hace exactamente eso — respaldado por el Raspador de Navegación Scrapeless, un navegador anti-detección alojado en la nube que accede a través de proxies residenciales en más de 195 países.

Este post describe cómo conectar ambos a través de pi-mcp-adapter (la extensión comunitaria MCP para Pi) y un único archivo .mcp.json. El endpoint al que se conecta Pi es el mismo que utilizan Claude Desktop, Cursor y otros clientes MCP; el mismo fragmento de JSON funciona en todos ellos.

Qué Puedes Hacer Con Esto

• Generar código basado en documentación en vivo. Haz que Pi busque el README actual de una biblioteca antes de generar un ejemplo — no más API obsoletas derivadas del conocimiento de modelos entrenados.
• Buscar y raspar en una sola acción. Pi llama a google_search para clasificar páginas candidatas, luego scrape_markdown para extraer la más relevante como Markdown limpio.
• Controlar un navegador en la nube anti-detección desde un prompt de terminal. Herramientas como browser_goto, browser_click, browser_type, y browser_get_html dan a Pi control total sobre un verdadero Chromium en la nube con persistencia de sesión.
• Extraer datos específicos de la región a través de proxies residenciales. Limita una búsqueda a gl=us o gl=de directamente desde la llamada a la herramienta del agente.
• Permanecer dentro de una sesión de terminal. Sin cambios entre pestañas del navegador, sin copiar y pegar la salida de curl, sin CLI de raspado separado para supervisar.

En Scrapeless, solo accedemos a datos disponibles públicamente mientras cumplimos estrictamente con las leyes, regulaciones y políticas de privacidad de sitios web aplicables. El contenido de este post es solo para fines de demostración.

¿Qué es Pi Agent?

Pi Agent es un agente de codificación basado en terminal creado por Mario Zechner (el creador del framework de juegos libGDX). De forma predeterminada, le da al modelo cuatro herramientas:

• read — leer archivos y directorios
• write — crear y editar archivos
• edit — hacer ediciones específicas a archivos existentes
• bash — ejecutar comandos de shell

Todo lo demás es opcional. Puedes extender Pi a través de extensiones de TypeScript, habilidades y plantillas de prompt empaquetadas como paquetes e instalables a través de npm o git. El agente se ejecuta en cuatro modos: interactivo (conversacional), print/JSON (escrito), RPC (integración stdin/stdout) y SDK (incorporado). El soporte de proveedores es amplio: Anthropic, OpenAI, Google, Mistral, Groq, y más.

Instálalo globalmente con npm:

npm install -g @mariozechner/pi-coding-agent

El compromiso es explícito: una superficie de inicio pequeña que puedes ampliar para adaptarla a tu flujo de trabajo, en lugar de una caja de herramientas de talla única.

Por qué Pi necesita acceso a la web

El razonamiento de Pi está limitado por lo que se entrenó el modelo subyacente. Eso significa que no puede:

• Buscar los últimos cambios de API de una biblioteca después de la fecha de corte de entrenamiento.
• Obtener las páginas de documentación actuales, registros de cambios o notas de lanzamiento.
• Leer una página pública para extraer una tabla de configuración, un precio o un esquema.
• Verificar que un ejemplo en sus datos de entrenamiento todavía se compila con la versión del paquete actual.

Para ecosistemas de rápida evolución — cualquier cosa relacionada con la web, frontend, herramientas de IA, infraestructura — esto es importante. Conecte Pi a un servidor MCP habilitado para la web y obtendrá un agente de codificación que busca información actual y extrae las páginas exactas que necesita antes de generar código. La producción deja de ser una mejor suposición de memoria obsoleta y empieza a estar fundamentada en la página que acaba de renderizar.

¿Qué es el Servidor MCP Scrapeless?

El Servidor MCP Scrapeless es un servidor de Protocolo de Contexto de Modelo que expone el navegador de nube Scrapeless, búsqueda y APIs de raspado como herramientas MCP. Cualquier cliente compatible con MCP — Pi, Claude Desktop, Cursor, Codex CLI, Gemini CLI, Windsurf, VS Code Copilot Chat — puede llamarlos directamente desde una conversación.

A la publicación, el servidor expone 21 herramientas en tres categorías:

• Búsqueda y tendencias — google_search, google_trends
• Automatización del navegador (16 herramientas) — browser_create, browser_close, browser_goto, browser_go_back, browser_go_forward, browser_click, browser_type, browser_press_key, browser_wait, browser_wait_for, browser_screenshot, browser_snapshot, browser_get_html, browser_get_text, browser_scroll, browser_scroll_to
• Raspado sin estado — scrape_html, scrape_markdown, scrape_screenshot

Se admiten dos modos de transporte:

• Stdio — npx -y scrapeless-mcp-server ejecuta el servidor como un proceso hijo del cliente MCP. Este es el predeterminado correcto para agentes de escritorio y terminal como Pi.
• HTTP transmitible — apunte el cliente a https://api.scrapeless.com/mcp. Este es el predeterminado correcto para agentes alojados en la nube que no pueden ejecutar npx.

Ambos modos están respaldados por la misma clave de API de Scrapeless. El código fuente del servidor se encuentra en github.com/scrapeless-ai/scrapeless-mcp-server; referencia completa de herramientas en docs.scrapeless.com. Obtenga su clave API en el plan gratuito en app.scrapeless.com.

El Puente MCP: pi-mcp-adapter

Pi no viene con soporte MCP de serie. Esa es una elección deliberada: Mario argumenta que las definiciones de herramientas MCP son demasiado pesadas en tokens para un agente minimalista. Servidores MCP populares como Playwright MCP exponen 21 herramientas y consumen alrededor de 13.7k tokens; Chrome DevTools MCP expone 26 herramientas y consume alrededor de 18k tokens. Conectar unos pocos servidores puede consumir una parte significativa de una ventana de contexto antes de que comience la conversación.

La respuesta de la comunidad es pi-mcp-adapter: una extensión de Pi que expone una única herramienta proxy (~200 tokens) en lugar de cargar todas las definiciones de herramientas MCP de antemano. El agente busca y llama a herramientas individuales bajo demanda:

mcp({ search: "screenshot" })
mcp({ tool: "scrapeless_scrape_markdown", args: '{"url": "https://example.com"}' })

Los servidores son perezosos por defecto — solo se inician cuando el agente llama por primera vez a una de sus herramientas y se desconectan después de 10 minutos de inactividad (configurable). Los metadatos de las herramientas se almacenan en caché en el disco, por lo que la búsqueda y la descripción funcionan sin conexiones en vivo.

El adaptador lee los archivos de configuración MCP estándar en este orden de precedencia:

1. ~/.config/mcp/mcp.json (compartido por el usuario de manera global)
2. <directorio del agente Pi>/mcp.json (anulación global de Pi, típicamente ~/.pi/agent/mcp.json)
3. .mcp.json (compartido a nivel de proyecto)
4. .pi/mcp.json (anulación de proyecto Pi)

Instálelo con un comando (ejecutar dentro de Pi o a través de la CLI de Pi):

pi install npm:pi-mcp-adapter

La versión del adaptador al momento de la publicación es 2.6.1.

Cómo Conectar el Agente Pi al Servidor MCP Scrapeless

Requisitos previos

• Node.js 18 o superior. El Agente Pi y pi-mcp-adapter lo requieren; la variante Gemini CLI del soporte de Pi necesita Node 20 o más reciente.
• Una cuenta de Scrapeless y clave API. Regístrese en app.scrapeless.com. Las nuevas cuentas incluyen un entorno de ejecución de navegador de raspado gratuito.
• Una clave API de un proveedor de modelos que Pi soporte — Anthropic, OpenAI, Google Gemini, Mistral, DeepSeek, Groq, o cualquiera de los otros que Pi lista en /login.

Paso 1 — Instalar el Agente Pi

Abra su terminal y ejecute:

npm install -g @mariozechner/pi-coding-agent

Verifique la instalación:

pi --version

El binario de Pi al momento de la publicación es @mariozechner/pi-coding-agent versión 0.73.1.

Paso 2 — Instalar pi-mcp-adapter

Con Pi instalado, agregue la extensión del adaptador MCP:

pi install npm:pi-mcp-adapter

Reinicia Pi después de la instalación. El adaptador incorpora una única herramienta proxy mcp que cuesta alrededor de 200 tokens, además del comando de barra /mcp para la gestión interactiva del servidor.

Paso 3 — Obtén tu clave API de Scrapeless

Inicia sesión en app.scrapeless.com, abre Configuración → Claves API, y copia tu clave. Mantenla en el portapapeles para el siguiente paso.

Paso 4 — Configura .mcp.json

En tu carpeta del proyecto, crea un archivo llamado .mcp.json. Este es el formato estándar del archivo de configuración MCP que pi-mcp-adapter lee al iniciar (no se requiere sintaxis específica de Pi):

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": {
        "SCRAPELESS_KEY": "TU_CLAVE_SCRAPELESS"
      }
    }
  }
}

Reemplaza TU_CLAVE_SCRAPELESS con la clave del Paso 3. El servidor MCP lee la clave API de la variable de entorno SCRAPELESS_KEY — ese nombre es la fuente de la verdad; no lo cambies a SCRAPELESS_API_KEY.

En la primera ejecución, npx -y scrapeless-mcp-server descarga el paquete e inicia el servidor a través de stdio. No se necesita un comando de instalación separado.

Si prefieres omitir stdio y utilizar el transporte HTTP transmisible, cambia la entrada a:

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "TU_CLAVE_SCRAPELESS"
      }
    }
  }
}

Ambas formas utilizan la misma clave API de Scrapeless y presentan las mismas 21 herramientas. Stdio es el valor predeterminado adecuado para una estación de trabajo; HTTP es el valor predeterminado adecuado si Pi se está ejecutando en un host en la nube que no puede hacer shell a npx.

Paso 5 — Conéctate a un proveedor de modelo

Inicia Pi:

pi

Deberías ver pi-mcp-adapter listado bajo Extensiones. Escribe /login y elige tu método de autenticación (suscripción o clave API). Escoge el proveedor que deseas utilizar, pega la clave API, y Pi guardará la credencial para futuras sesiones. Escribe /model para abrir el panel de selección de modelos y elige un modelo.

Obtén tu clave API de Scrapeless en el plan gratuito: app.scrapeless.com

Paso 6 — Verifica la conexión

Escribe /mcp para abrir el panel MCP. El servidor scrapeless está listado pero es perezoso — al principio puede mostrar 0/21 porque la conexión aún no se ha abierto. Destaca la fila con las teclas de flecha y presiona Ctrl+R para reconectar (o llama a cualquier herramienta de Scrapeless, lo que activa una conexión perezosa).

Una vez conectado, la parte inferior de la terminal muestra MCP: 1/1 servidores. Las 21 herramientas ahora son descifrables. Para confirmarlo listándolas:

mcp({ search: "scrapeless" })

Deberías ver las herramientas google_search, google_trends, browser_*, y scrape_* en el resultado. Presiona Esc para cerrar el panel.

Paso 7 — Ejecuta una tarea real

Dale a Pi un aviso que necesite datos web en vivo. Por ejemplo:

Busca en la web la documentación oficial de axios npm, raspa la página más relevante,
y genera un ejemplo de JavaScript que realice una solicitud GET con un manejo de errores adecuado. Guárdalo como axios-example.js.

Pi llama primero a scrapeless_google_search, retornando una lista clasificada de resultados con títulos, URL y fragmentos de la documentación oficial de axios. Luego elige la URL más relevante y llama a scrapeless_scrape_markdown para extraer la página como Markdown limpio — el navegador en la nube maneja el renderizado de JavaScript y cualquier desafío de detección en el camino, y Pi recibe el contenido extraído en lugar de HTML sin procesar.

Con la documentación en contexto, Pi genera axios-example.js en función de la versión de la API que acaba de leer. Si aparece un error transitorio os error 10054 o HTTP 503, vuelve a intentar la llamada — la flota de navegadores en la nube recicla sesiones y un nuevo intento generalmente tiene éxito.

Paso 8 — Explora la salida

Pi escribe axios-example.js en tu carpeta de proyecto. El archivo contiene un ejemplo que refleja los patrones que acaba de raspar — async/await, ramificación de códigos de estado, e inspección de errores consistente con lo que las actuales docs de axios recomiendan:

async function fetchPost() {
  try {
    const response = await axios.get('https://jsonplaceholder.typicode.com/posts/1');
    console.log('Estado:', response.status);
    console.log('Título:', response.data.title);
    console.log('Cuerpo:', response.data.body);
  } catch (error) {
    if (error.response) {
      console.error('Estado:', error.response.status);
      console.error('Datos:', error.response.data);
    } else if (error.request) {
      console.error('No se recibió respuesta del servidor');
    } else {
      console.error('Error en la configuración de la solicitud:', error.message);
    }
  }
}

Ejecuta:

npm install axios
node axios-example.js

Lo que Obtienes de Vuelta

Una respuesta representativa de tools/list del servidor MCP de Scrapeless tiene esta forma (el esquema refleja el servidor en vivo en la publicación; los valores de los campos son ejemplos ilustrativos):

{
  "tools": [
    {
      "name": "google_search",
      "description": "Motor de búsqueda de información universal",
      "inputSchema": {
        "type": "object",
        "properties": {
          "q":  { "type": "string", "default": "Titulares de noticias principales" },
          "gl": { "type": "string", "default": "us" },
          "hl": { "type": "string", "default": "es" }
        }
      }
    },
    {
      "name": "scrape_markdown",
      "description": "Rascar una URL y devolver su contenido como Markdown",
      "inputSchema": {
        "type": "object",
        "properties": { "url": { "type": "string", "format": "uri" } },
        "required": ["url"]
      }
    },
    { "name": "browser_create",   "description": "Crear una nueva sesión de navegador en la nube" },
    { "name": "browser_goto",     "description": "Navegar a una URL en una sesión existente" },
    { "name": "browser_get_html", "description": "Devolver el HTML renderizado de la página activa" }
    // …16 más
  ]
}

Observaciones honestas después de juntar esto:

• El costo de token es dominado por la herramienta proxy, no por las 21 herramientas subyacentes. El adaptador mantiene metadatos en una caché en disco; nada se carga en el aviso del sistema hasta que llames a directTools en un servidor.
• El inicio perezoso gana en sesiones frías. El servidor MCP de Scrapeless solo se inicia la primera vez que Pi llama a una de sus herramientas, por lo que abrir una sesión de Pi que tenga el servidor configurado no cuesta nada extra.
• google_search + scrape_markdown es el par común. Buscar para encontrar la página, rascar para leerla. Las herramientas browser_* están reservadas para flujos que necesitan inicio de sesión, clics o paginación.
• El os error 10054 / HTTP 503 transitorio sucede. Está documentado en las guías de Scrapeless y aparece en la rotación de sesiones del navegador en la nube. Reintenta la llamada a la herramienta desde Pi en lugar de reiniciar la sesión.
• SCRAPELESS_KEY es la variable de entorno canónica. Otras superficies de Scrapeless (la CLI independiente, la habilidad del agente) utilizan SCRAPELESS_API_KEY. El servidor MCP es la excepción.

Conclusión: un agente de programación mínima que lee la web en vivo

El Agente Pi se mantiene minimalista por defecto; el Servidor MCP de Scrapeless añade 21 herramientas web sin cambiar eso. El tejido conectivo es pi-mcp-adapter — una herramienta proxy, ~200 tokens, inicio de servidor perezoso — y un archivo .mcp.json que el ecosistema MCP más amplio ya entiende. El mismo fragmento JSON se integra en Claude Desktop, Cursor, Codex CLI, Gemini CLI, Windsurf o VS Code Copilot Chat sin cambios.

La diferencia cualitativa se muestra la primera vez que le pides a Pi que genere código contra una biblioteca que no has fijado: en lugar de adivinar a partir de la memoria de datos de entrenamiento, Pi busca, rasca la documentación canónica y escribe su ejemplo contra la versión que está realmente en vivo. Combina esta guía con la visión general del Servidor MCP de Scrapeless para el catálogo completo de herramientas, o con la guía de AWS Strands + Scrapeless MCP si el mismo servidor MCP se está integrando en un agente basado en un marco en lugar de uno de terminal. Fija el modo solo proxy para el uso normal, promociona herramientas individuales a directTools cuando quieras que el modelo las vea en su aviso del sistema, y mantén lifecycle: lazy para que las sesiones frías sigan siendo económicas.

¿Listo para construir tu pipeline de datos potenciado por IA?

Únete a nuestra comunidad para reclamar un plan gratuito y conectarte con desarrolladores que construyen pipelines de agentes impulsados por MCP: Discord · Telegram.

Regístrate en app.scrapeless.com para obtener un runtime gratuito de Scraping Browser, luego inserta el fragmento .mcp.json anterior en Pi (o cualquier otro cliente MCP) y comienza a basar la generación de código en datos web en vivo. Detalles de precios en scrapeless.com/en/pricing.

Preguntas Frecuentes

1. ¿Es legal rascar con el servidor MCP de Scrapeless a través de Pi?
El servidor MCP solo accede a contenido públicamente disponible, el mismo contenido que un usuario desconectado vería en un navegador. La legalidad depende de la jurisdicción y de los Términos del Servicio del sitio de destino. Revisa los Términos de Servicio de cualquier sitio que Pi sea solicitado a raspar y consulta con un abogado para casos de alto riesgo.

2. ¿Necesito un proxy además del servidor MCP de Scrapeless?
No. El navegador en la nube ya pasa por proxies residenciales en más de 195 países. Usa el parámetro gl en google_search (o un indicativo al estilo --proxy-country en el aviso del agente) para fijar una región.

3. ¿Qué ve Pi si una llamada a la herramienta falla con ERR_TUNNEL_CONNECTION_FAILED, os error 10054 o HTTP 503?
Estos son errores transitorios en la flota del navegador en la nube. Pi informa del error al modelo, que normalmente reintenta automáticamente; si no lo hace, vuelva a emitir el aviso. No son una señal de que el cableado del MCP esté roto.

4. Pi muestra el servidor Scrapeless pero 0/21 herramientas — ¿qué está mal?
Nada. Los servidores son perezosos por defecto en pi-mcp-adapter. El conteo cambia a 21/21 la primera vez que Pi llama a una herramienta Scrapeless. Para forzar la conexión, resalte el servidor en /mcp y presione Ctrl+R, o ejecute /mcp reconnect scrapeless desde la línea de comandos.

5. La herramienta proxy es genial, pero ¿puedo exponer las herramientas Scrapeless directamente al modelo de Pi?
Sí — añada "directTools": true (o "directTools": ["google_search", "scrape_markdown"] para promover un subconjunto) a la entrada de scrapeless en .mcp.json. Las herramientas directas cuestan entre ~150 y 300 tokens cada una en el aviso del sistema; elija las que más utilice el agente.

6. ¿Se puede usar el mismo fragmento de .mcp.json fuera de Pi?
Sí. El objeto mcpServers es el sobre de configuración estándar del MCP. Claude Desktop, Cursor, Codex CLI, Gemini CLI, Windsurf y VS Code Copilot Chat lo leen (algunos con diferencias menores en la ruta o el nombre del archivo). El bloque de Scrapeless anterior funciona en todos ellos.

7. ¿Cuántos servidores MCP puede conectar Pi a la vez?
No hay un límite estricto — pi-mcp-adapter mantiene cada servidor perezoso y se desconecta después de 10 minutos de inactividad, por lo que el costo de tokens y procesos se mantiene constante independientemente de cuántos servidores estén listados. El límite relevante es la ventana de contexto del proveedor de modelos y el presupuesto por herramienta de Pi.

8. ¿Funciona esto sin un agente de IA — puedo llamar al servidor Scrapeless MCP desde un script?
Sí. El punto final HTTP transmitible en https://api.scrapeless.com/mcp es llamable desde cualquier cliente HTTP con la secuencia JSON-RPC initialize → tools/list → tools/call; una prueba de humo curl contra él devuelve serverInfo.name: "scrapeless-mcp-server" y un encabezado mcp-session-id para llamadas posteriores. Pi es la capa de conveniencia, no una dependencia estricta.