Cómo usar de verdad CrawlForge MCP en Claude Code

Instalaste CrawlForge MCP. Claude Code dice que está conectado. Luego pides una página y Claude te la resume de memoria, o tira de su herramienta de fetch integrada, o pide permiso cuatro veces antes de hacer nada útil.

Eso no es una instalación rota. Es un hueco en cómo se invocan las MCP tools, y se arregla con unos cinco minutos de configuración.

claude mcp list
# crawlforge: npx -y crawlforge-mcp-server - ✔ Connected

Esta guía cubre lo que viene después de instalar: cómo decide Claude llamar a una herramienta, cómo hacer que prefiera CrawlForge frente a sus utilidades web integradas, cómo acabar con las peticiones de permiso y cómo elegir la herramienta que hace el trabajo con el menor gasto de credits.

Tabla de contenidos

• Por qué Claude ignora tu MCP server
• Cómo funcionan realmente las llamadas a herramientas
• Paso 1: confirma que el servidor está conectado
• Paso 2: nombra la herramienta cuando haga falta
• Paso 3: escribe una política de CrawlForge en CLAUDE.md
• Paso 4: acaba con las peticiones de permiso
• Elegir la herramienta adecuada
• Protege tu ventana de contexto
• Patrones de prompt que funcionan
• Comparte la configuración con tu equipo
• Ejecútalo en modo headless en scripts y CI
• Solución de problemas

Por qué Claude ignora tu MCP server

Hay tres fallos distintos, y cada uno necesita una solución diferente.

Claude todavía no sabe que las herramientas existen. Claude Code activa la búsqueda de herramientas por defecto. Al arrancar la sesión solo carga los nombres de las herramientas y las instrucciones del propio servidor; las definiciones completas quedan aplazadas hasta que una tarea las necesita. Esto mantiene libre tu ventana de contexto, pero significa que «no veo las 27 herramientas en la lista» es lo normal y no es síntoma de nada.

Claude tiene una herramienta integrada que se parece bastante. Claude Code incluye WebFetch y WebSearch. Si pides «el contenido de esta página», un modelo razonable puede muy bien tirar de la integrada en lugar de buscar una MCP tool que antes tiene que descubrir. No hay nada roto: simplemente no le has dicho cuál prefieres.

La llamada sí ocurre, pero cada una necesita aprobación. Cada llamada a una MCP tool lanza una petición de permiso hasta que la permites. A la cuarta interrupción en una tarea de investigación, parece que la integración esté peleándose contigo.

El resto de esta guía arregla los tres.

Cómo funcionan realmente las llamadas a herramientas

Tú no llamas a una MCP tool. Describes un resultado y Claude elige una herramienta, igual que elige entre Read y Grep.

Cada MCP tool tiene un nombre canónico con la forma mcp__<server>__<tool>. Con CrawlForge registrado bajo el nombre crawlforge, sus herramientas son:

mcp__crawlforge__scrape
mcp__crawlforge__search_web
mcp__crawlforge__deep_research
mcp__crawlforge__stealth_mode

Normalmente no vas a escribir esos nombres. Importan para dos cosas: las reglas de permisos, que hacen match sobre el nombre canónico, y el recurso de nombrar una herramienta de forma explícita cuando Claude elige la equivocada.

Paso 1: confirma que el servidor está conectado

Antes de depurar prompts, confirma que el transporte funciona. Desde tu shell:

claude mcp list

Cada servidor recibe un estado de salud. Los cuatro que vas a ver de verdad:

Dentro de una sesión, /mcp abre la misma vista con un panel de detalle por servidor, incluida una fila Issue: cuando un servidor ha fallado.

Un matiz que conviene conocer: claude mcp add imprime Added ... en cuanto la configuración queda escrita, sin validar nada. Una errata en tu API key sigue imprimiendo una línea de éxito. La comprobación que importa es claude mcp list.

Paso 2: nombra la herramienta cuando haga falta

Cuando Claude elija la herramienta equivocada —o ninguna—, dile cuál quieres. Las dos formas funcionan:

Use scrape to get https://example.com/pricing as markdown.

Use mcp__crawlforge__deep_research to compare the three vendors on
that page, then write the findings to research.md.

En la práctica basta con el nombre a secas. Recurre a la forma completa mcp__crawlforge__* cuando un nombre sea ambiguo entre varios servidores, o cuando escribas un slash command o un script que deba ser inequívoco.

Nombrar la herramienta es un buen recurso de depuración y una mala costumbre. Si acabas haciéndolo en cada prompt, arregla el comportamiento por defecto: eso es el siguiente paso.

Paso 3: escribe una política de CrawlForge en CLAUDE.md

Este es el cambio con más rendimiento de toda la guía. CLAUDE.md se carga en contexto en cada sesión, así que un bloque corto de política cambia de forma permanente a qué herramienta recurre Claude:

# Web Access Policy

Use CrawlForge MCP tools for all web search and page fetching.

- Web search: `search_web` (not the built-in WebSearch)
- Single page: `scrape` with `formats: ["markdown"]`
- Article text only: `extract_content`
- Site structure: `map_site`, then `crawl_deep` if you need page bodies
- Multi-source research: `deep_research`
- JS-rendered or anti-bot pages: `scrape_with_actions` or `stealth_mode`

Prefer one `batch_scrape` call over a loop of single fetches.

Ponlo en el CLAUDE.md de tu proyecto, o en ~/.claude/CLAUDE.md para aplicarlo en todas partes. Dos sesiones después habrás olvidado que existe, que es justo la idea.

Enuncia la preferencia una vez, con normalidad. Un bloque que grita ALWAYS y NEVER en cada línea tiende a hacer que los modelos se pasen de frenada, recurriendo a una herramienta de scraping en preguntas que nunca la necesitaron.

Paso 4: acaba con las peticiones de permiso

Añade una regla de permitido para que las herramientas de CrawlForge se ejecuten sin interrupciones. En .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__crawlforge__*"
    ]
  }
}

Las reglas de los patrones, directas de la referencia de permisos:

• mcp__crawlforge — todas las herramientas del servidor
• mcp__crawlforge__* — lo mismo, en forma de comodín
• mcp__crawlforge__scrape — solo esa herramienta
• mcp__crawlforge__extract_* — las cuatro herramientas de extracción

Las reglas de permitido deben estar ancladas a un prefijo literal de servidor. Un "mcp__*" a secas se descarta con un aviso y no aprueba nada automáticamente, porque no nombraría ningún servidor que hayas configurado.

Si prefieres aprobar las herramientas baratas y mantener la mano encima de las caras, permite las lecturas y deja que el resto siga preguntando:

{
  "permissions": {
    "allow": [
      "mcp__crawlforge__scrape",
      "mcp__crawlforge__extract_content",
      "mcp__crawlforge__search_web",
      "mcp__crawlforge__map_site"
    ]
  }
}

Así deep_research con sus 10 credits y agent con 8 siguen preguntando primero.

Elegir la herramienta adecuada

Veintisiete herramientas son mucha superficie, y Claude gastará tan contento 5 credits donde 1 habría bastado. Los costes:

Tres reglas cubren casi todo:

Escala, no empieces por arriba. Prueba primero fetch_url (1) o scrape (2). Pasa a scrape_with_actions (5) solo cuando el contenido se renderice en el cliente, y a stealth_mode (5) solo tras un bloqueo real. Muchísimos sitios que parecen protegidos responden perfectamente a una petición bien formada.

Agrupa en lote en vez de iterar. Una llamada a batch_scrape cuesta 5 credits sea cual sea el número de URLs. Doce llamadas sueltas a scrape son 24 credits y doce idas y vueltas. Di «scrapea todas estas en un solo lote» y la diferencia es real.

Ten claro a qué sustituye deep_research. Con 10 credits es la herramienta más cara, y sale a cuenta cuando reemplaza una búsqueda más ocho scrapes más la síntesis. Es un desperdicio cuando ya conoces la URL. Si tienes el enlace, haz scrape.

Protege tu ventana de contexto

Este es el fallo del que nadie te avisa: un scrape con éxito que te arruina la sesión. Las páginas web son grandes, y los resultados de MCP aterrizan directamente en la conversación.

Claude Code trae protecciones. Avisa cuando la salida de cualquier MCP tool supera los 10.000 tokens, y limita la salida a 25.000 tokens por defecto. Puedes subir el techo:

export MAX_MCP_OUTPUT_TOKENS=50000

Subirlo suele ser el instinto equivocado. Tres movimientos mejores:

Pide la forma que necesitas. scrape devuelve markdown por defecto y elimina navegación, anuncios y pies de página con Readability. Pedir rawHtml en un sitio moderno puede multiplicar los tokens por diez sin ganancia alguna.

Manda la salida masiva a disco. Para todo lo que vayas a procesar en lugar de leer, haz que Claude lo escriba:

Batch scrape these 20 URLs and write each result to data/<domain>.md.
Then give me a one-line summary of each — do not paste the bodies.

Claude mantiene 20 líneas de resumen en contexto en lugar de 20 artículos.

Usa la herramienta barata para el triaje. extract_metadata (1 credit) responde a «¿merece la pena leer esta página?» con unos pocos cientos de tokens. map_site (2) te da una lista de URLs sin descargar un solo cuerpo. Explora primero, y luego descarga lo que importe.

Patrones de prompt que funcionan

La diferencia entre una petición vaga y una concreta suele ser un par de frases más.

Nombra la forma de la salida.

Dame el pricing de esa página.

Haz scrape de https://example.com/pricing y devuelve JSON: [{ plan, monthly_price, annual_price, included_credits }]. Usa null para lo que no aparezca.

Di qué pasa con los datos. Claude por defecto imprime resultados. Si el objetivo es un archivo, un diff o un test, dilo:

Search for the top 10 results on "MCP web scraping", scrape each one,
and write a comparison table to docs/competitors.md. Skip anything
that 403s and note it at the bottom.

Dale la ruta de escalada por adelantado. Esto ahorra una ida y vuelta entera:

Scrape https://app.example.com/dashboard. If the content looks
client-rendered, retry with scrape_with_actions waiting on
.data-grid. If you get a 403, use stealth_mode.

Encadena con el trabajo que Claude Code ya hace bien. La verdadera ventaja de hacer scraping en tu terminal es que los datos aterrizan junto a tu código:

Scrape the Stripe webhook events reference, then check
src/lib/stripe/webhooks.ts for event types we handle that
no longer appear in their docs.

Eso es un solo prompt que cubre una descarga, una lectura del repositorio y un diff, y ninguna de las tres te la hace una pestaña del navegador.

Comparte la configuración con tu equipo

Los MCP servers se instalan en tres ámbitos. El de por defecto es local: privado para ti, limitado al proyecto actual, guardado en ~/.claude.json.

Para un equipo, usa el ámbito project, que escribe .mcp.json en la raíz del repositorio:

claude mcp add crawlforge \
  --scope project \
  --env CRAWLFORGE_API_KEY=cf_live_your_key_here \
  -- npx -y crawlforge-mcp-server

No subas ese archivo con una clave real dentro. .mcp.json admite expansión de variables de entorno, así que sube la referencia en su lugar:

{
  "mcpServers": {
    "crawlforge": {
      "command": "npx",
      "args": ["-y", "crawlforge-mcp-server"],
      "env": {
        "CRAWLFORGE_API_KEY": "${CRAWLFORGE_API_KEY}"
      }
    }
  }
}

Ahora cada desarrollador recibe el servidor al clonar y aporta su propia clave desde su shell. La forma ${VAR:-default} también funciona, y la expansión se aplica a command, args, env, url y headers.

Dos cosas que esperar con el ámbito de proyecto. Claude Code pide a cada desarrollador que apruebe el servidor la primera vez: es deliberado, ya que de otro modo un repositorio podría traer un servidor que se ejecuta al clonar. Y si la variable no está definida y no tiene valor por defecto, la configuración se carga igualmente: claude mcp list informa de un aviso de variable ausente y pasa el texto literal ${CRAWLFORGE_API_KEY}, que más tarde aparece como un 401.

Usa el ámbito user (--scope user) para un servidor que quieras en todos los proyectos de tu máquina.

Ejecútalo en modo headless en scripts y CI

Todo lo anterior funciona en modo no interactivo, con una diferencia: no hay nadie para responder a las peticiones, así que los permisos deben quedar resueltos de antemano.

claude -p "Scrape https://news.ycombinator.com and write the top 10 \
stories as JSON to hn.json" \
  --allowedTools "mcp__crawlforge__scrape,Write"

Los servidores de ámbito de proyecto desde .mcp.json se cargan en claude -p sin la petición de aprobación, ya que no puede mostrarse. Eso convierte un .mcp.json versionado en la opción natural para CI. Si necesitas dejar un servidor fuera de una ejecución automatizada, disabledMcpjsonServers lo bloquea en todos los modos.

Un monitor diario es entonces un cron job y un prompt:

claude -p "Use track_changes on https://competitor.com/pricing. \
If anything changed since the last run, append it to CHANGES.md." \
  --allowedTools "mcp__crawlforge__track_changes,Read,Write"

Solución de problemas

✘ Failed to connect — Ejecuta claude mcp get crawlforge y lee la línea Issue:, que lleva el estado HTTP o el texto del error. Para el servidor stdio, comprueba antes que npx -y crawlforge-mcp-server arranca por su cuenta.

401 en todas las herramientas — La API key está mal, o tiene espacios en blanco invisibles. Pegar una clave suele arrastrar un salto de línea final; Claude Code lo señala en claude mcp list y en /mcp con un aviso que nombra el campo. Vuelve a añadir el servidor y comprueba que la clave empieza por cf_live_.

⏸ Pending approval — Un servidor de ámbito de proyecto necesita aprobación interactiva. Ejecuta claude en el directorio y acepta. En un repositorio recién clonado también tienes que aceptar antes el diálogo de confianza del workspace: un repositorio no puede aprobar sus propios servidores. claude mcp reset-project-choices borra las respuestas anteriores.

Claude sigue usando WebFetch — Vuelve al Paso 3. Sin una preferencia declarada, la integrada es una elección defendible.

Salida de la herramienta truncada — Has alcanzado el límite de 25.000 tokens. Es preferible acotar la petición antes que subir MAX_MCP_OUTPUT_TOKENS; consulta Protege tu ventana de contexto.

Credits insuficientes — Consulta el panel de uso. Las cuentas Free obtienen 1.000 credits por única vez; Hobby son 19 USD al mes por 5.000.

Contenido vacío en una página que sí carga en tu navegador — Renderizado en cliente. Reintenta con scrape_with_actions y una espera sobre un selector que solo exista tras la hidratación.

Siguientes pasos

• ¿Nuevo en la configuración? Empieza por la guía de instalación
• Recorrido centrado en scraping: Cómo hacer scraping de sitios web con Claude Code
• Contexto del protocolo: El protocolo MCP explicado para desarrolladores
• Referencia completa de herramientas: documentación de primeros pasos

Empieza gratis con 1.000 credits en crawlforge.dev/signup. Sin tarjeta de crédito.