Cómo Reducir los Tokens de Investigación Web de Claude Code con Extracción Estructurada

TL;DR:

• Los tokens de investigación web de Claude Code están impulsados por lo que llega al modelo, no solo por lo que cruza la red. HTML en bruto, navegación repetida, URLs duplicadas, metadatos de herramientas y resultados verbosos pueden consumir contexto.
• Reduce el contenido antes del paso de razonamiento. Prefiere la extracción de contenido principal, selectores restringidos, extracción a nivel de campo y un esquema JSON que rechace resultados incompletos.
• Mantén las URLs de origen y fragmentos de evidencia. Un payload más pequeño es útil solo si la respuesta sigue siendo auditable y completa.
• MCP puede separar adquisición de razonamiento. Claude Code elige una herramienta Scrapeless limitada; la herramienta devuelve solo los campos que requiere la tarea.
• Nuestra prueba de proxy reproducible redujo una entrada fija de 181,892 a 434 tokens de comparación. Utilizó una página de documentación pública, una pregunta y cl100k_base; estos no son tokens de facturación de Claude.

Claude Code puede buscar en la web, obtener una página, llamar a herramientas MCP y razonar sobre el material devuelto. Eso hace que la investigación sea conveniente, pero la conveniencia puede ocultar un problema básico de costo: una pregunta que necesita seis hechos puede atraer decenas de miles de caracteres irrelevantes al contexto.

La solución no es "resumir de manera más agresiva". La búsqueda de resúmenes es otra tarea del modelo y puede eliminar la evidencia que necesitabas. Un mejor flujo de trabajo reduce el contenido en el momento de adquisición, valida el resultado y envía al modelo principal un pequeño contrato de evidencia.

Este tutorial construye ese flujo de trabajo para Claude Code con Scrapeless MCP Server y patrones de API de Scraping Universal.

De Dónde Vienen los Tokens de Investigación Web de Claude Code

Trata el camino de investigación como cuatro volúmenes separados:

bytes adquiridos → caracteres extraídos → tokens de contexto del modelo → tokens de respuesta estructurada

Están relacionados, pero no son intercambiables.

Volumen de adquisición de página

Esto es lo que recibe el navegador, fetcher o servicio de scraping. Una página renderizada puede incluir scripts, estilos, navegación, banners de cookies, estado embebido y contenido para varias rutas. El volumen de adquisición afecta el coste de la red y del scraping, pero no tiene que entrar en el contexto de Claude.

Caracteres devueltos

La herramienta elige lo que devuelve: HTML en bruto, Markdown legible, elementos seleccionados o un objeto JSON. Este es el punto de control más útil. Eliminar el boilerplate aquí ahorra cada paso posterior de procesarlo.

Contexto del modelo principal

Claude Code ve instrucciones del sistema, historial de conversación, definiciones de herramientas, resultados de herramientas y tu solicitud actual. Una respuesta concisa de la herramienta aún puede estar al lado de un gran contexto de proyecto. Utiliza la actual documentación de la ventana de contexto de Claude Code para entender cómo se gestiona el contexto, pero mide tu propio flujo de trabajo en lugar de asumir una capacidad o precio fijo.

Salida de respuesta estructurada

Un esquema JSON restringe la respuesta final. No reduce automáticamente el contenido de la página que lo precedía. Aplica estructura tanto a los resultados de la herramienta como a la respuesta final.

Establecer una Línea Base Antes de Optimizar

Utiliza una pregunta de investigación y un conjunto de fuentes fijas. Registra:

• URLs de origen solicitadas;
• caracteres devueltos por cada herramienta;
• versión del modelo y de Claude Code;
• campos de uso de tokenizador o API utilizados para medición;
• conteos de tokens de entrada y salida;
• campos de respuesta requeridos y resultados de completitud.

Claude Code expone las opciones actuales de CLI con claude --help. En la máquina usada para este artículo, Claude Code 2.1.162 listó --mcp-config, --tools, --output-format y --json-schema. La actual referencia de herramientas de Claude Code documenta WebSearch y WebFetch como herramientas integradas.

No confundas esas herramientas de Claude Code con las herramientas web de la API de Anthropic. La documentación de búsqueda web de la API describe características del lado del servidor como filtrado dinámico. Una característica documentada para la API no es automáticamente una opción WebFetch de Claude Code.

Paso 1: Prefiere el Contenido Principal Sobre HTML en Bruto

El HTML en bruto es útil para depurar selectores o preservar el marcado exacto. Generalmente es un payload de investigación pobre.

Pide a la capa de adquisición que elimine:

• contenido de script, estilo, SVG y plantillas;
• navegación del sitio y pies de página repetidos;
• consentimientos y estructuras de cuenta;
• estado oculto no requerido por la pregunta;
• recomendaciones y comentarios no relacionados.

Markdown legible es a menudo una buena primera reducción. Retiene encabezados, listas, enlaces y código mientras descarta gran parte de la capa de presentación. Aún así, valida que el título y la sección requerida estén presentes; una página de inicio de sesión limpia no es una extracción exitosa.

Paso 2: Extrae Solo los Campos que Necesita la Pregunta

El contenido principal puede seguir siendo mucho más grande que la respuesta. Convierte la pregunta en un contrato de extracción antes de obtener varias páginas.
Para una comparación de documentación, el contrato podría ser:

{
  "type": "object",
  "required": ["source_url", "tools", "complete"],
  "properties": {
    "source_url": { "type": "string", "format": "uri" },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name", "evidence"],
        "properties": {
          "name": { "type": "string" },
          "evidence": { "type": "string", "maxLength": 1200 }
        }
      }
    },
    "complete": { "type": "boolean" }
  }
}

Mantenga la evidencia breve, pero no la reduzca a un valor no soportado. Un campo como supports_web: true es compacto y difícil de auditar. La URL de origen más un fragmento de evidencia acotado permite a un revisor verificar la interpretación.

Para formas de página repetidas, use selectores específicos o un punto de extracción estructurado. Para páginas variadas, solicite contenido legible primero, luego seleccione secciones relevantes con código determinista cuando sea posible.

Paso 3: Eliminar URLs Duplicadas Antes de la Adquisición

Los agentes de investigación suelen encontrar el mismo documento a través de navegación, parámetros de búsqueda, alias de idioma o fragmentos. Normalice antes de obtener:

1. resuelva URLs relativas;
2. elimine fragmentos;
3. aplique una política de parámetros de consulta aprobada;
4. siga redireccionamientos una vez y registre la identidad canónica final;
5. haga un hash del contenido aceptado para atrapar espejos o repeticiones.

No elimine todos los parámetros de consulta. Los parámetros de localidad, versión, producto o fecha pueden cambiar el documento. La regla de normalización pertenece a la política de origen, no a un limpiador de cadenas universal.

Una pequeña caché también puede prevenir la recolección repetida en una sola ejecución. Téngalo en cuenta por fuente canónica, localidad, versión de contrato de extracción y requisito de frescura.

Paso 4: Conectar el Código Claude a MCP Sin Scrapear

MCP mantiene la interfaz orientada al agente pequeña. Claude Code ve herramientas y esquemas nombrados; Scrapeless maneja búsqueda, extracción de páginas públicas u operaciones de navegador en la nube detrás de ellas.

Requisitos previos:

• Claude Code y Node.js instalados;
• una cuenta de Scrapeless y clave API;
• un objetivo público autorizado;
• un presupuesto de página y llamada a la herramienta.

Almacene la clave en una variable de entorno. Este ejemplo a nivel de proyecto utiliza la expansión de variables para que el secreto no se comprometa:

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

Guarde el objeto como .mcp.json en el proyecto aprobado y comience Claude Code desde ese proyecto. Ejecute claude mcp list para inspeccionar la salud de la conexión. Claude Code requiere aprobación para servidores MCP con alcance de proyecto; inspeccione los comandos y claves de entorno antes de aprobarlos.

Durante la verificación editorial, el paquete actual de Scrapeless se lanzó a través de stdio con el flujo estándar del cliente MCP. No se realizó una llamada web acreditada porque no había clave de producción presente en el entorno de verificación. Trate la primera llamada real a la herramienta como una prueba de aceptación: una URL permitida, un conjunto de campos requeridos y sin rastreo amplio.

La actual documentación de Claude Code MCP explica el alcance, transportes, descubrimiento de herramientas, límites de salida y expansión de variables de entorno. La guía de integración de Scrapeless Claude proporciona la configuración del servidor específica del producto.

Paso 5: Dar al Agente un Contrato de Investigación Acotado

"Investigue este tema" invita a la exploración. Un aviso acotado define fuentes, campos y una condición de parada.

Utilice una solicitud como esta:

Busque hasta cinco fuentes oficiales sobre el producto nombrado. Duplicar URLs canónicas. Para cada fuente aceptada, devuelva el título, la URL final, la fecha de publicación o actualización cuando sea visible, y un fragmento de evidencia que apoye la característica requerida. Deténgase después de tres fuentes completas. Marque los campos faltantes; no infiera.

Este contrato controla cuatro modos de falla a la vez: búsqueda ilimitada, adquisición duplicada, resultados verbosos y campos inventados.

También filtre el conjunto de herramientas MCP. Una tarea de documentación puede necesitar búsqueda y una sola extracción de Markdown, no cada acción de navegador. Menos herramientas visibles reducen la ambigüedad en la selección y simplifican la revisión de permisos.

Paso 6: Medir la Reducción y la Completitud Juntas

Utilizamos la página de referencia de herramientas pública de Claude Code y una pregunta fija:

¿Qué herramientas integradas de Claude Code pueden buscar o recuperar contenido web público, y qué restricciones debería aplicar un flujo de trabajo de investigación?

El mismo cl100k_base tokenizador contó la pregunta más cada variante material. Es un proxy de comparación abierto, no el tokenizador de Anthropic y no una medida de facturación de Claude.

El JSON dirigido utilizó alrededor del 95.4% menos tokens de comparación que el contenido principal y un 99.8% menos que el HTML crudo. Esos porcentajes describen esta página y este contrato de extracción solamente.

La verificación de completitud fue deliberadamente estrecha: ambos nombres de herramientas requeridas debían existir en el texto principal y en el objeto extraído, con la identidad de la fuente preservada. Una evaluación de producción también debería puntuar si cada fragmento de evidencia respalda la respuesta final.

Paso 7: Agregar una Puerta de Aceptación de Resultados

La compresión no es la corrección. Antes de que el contenido ingrese al paso principal de razonamiento, valida:

• la URL final pertenece a la lista permitida;
• la identidad de la página coincide con el documento solicitado;
• los campos requeridos existen y tienen los tipos correctos;
• la evidencia incluye la entidad o término reclamado;
• el contenido no es un error, consentimiento, inicio de sesión o un shell de desafío de acceso;
• el registro incluye el tiempo de recolección y la versión del contrato de extracción;
• los caracteres totales devueltos se mantienen por debajo del presupuesto de la tarea.

Devuelve resultados tipados como accepted, missing_fields, wrong_page, access_required, o over_budget. Claude puede decidir si detenerse o usar otra ruta aprobada sin tratar cada fallo como prosa ordinaria.

Cuándo Usar la API de Extracción Universal en su Lugar

MCP es útil cuando el Código Claude debería descubrir y elegir una capacidad web de manera interactiva. La API de Extracción Universal es un mejor límite cuando tu programa ya conoce el objetivo y desea una solicitud predecible de CI, un trabajo de datos o un servicio.

Usa la ruta de la API cuando necesites:

• llamar a la extracción desde un código de aplicación determinista;
• centralizar controles de tasa y presupuesto fuera del agente;
• normalizar resultados antes de que se ejecute el Código Claude;
• almacenar en caché registros aceptados a través de muchas sesiones de investigación.

El mismo principio aplica: solicita la salida menos costosa que pueda cumplir con el contrato de aceptación, y luego envía a Claude solo los campos aceptados. Revisa la página del producto de la API de Extracción Universal y la documentación actual para los endpoints y campos de solicitud admitidos.

Errores Comunes

Enviar páginas en bruto "por si acaso"

Esto desplaza el trabajo de selección a la parte más sensible al contexto del sistema. Preserva el material en bruto fuera del aviso y envía un paquete de evidencia en su lugar.

Optimizar tokens sin un contrato de respuesta

Una respuesta pequeña que omite un hecho requerido no es eficiente. Mide las respuestas aceptadas por costo, no solo la reducción de tokens.

Omitir la identidad de origen

Sin la URL final y la evidencia, el resultado no se puede auditar ni actualizar de forma segura.

Exponer claves en avisos o configuraciones comprometidas

Usa variables de entorno y controles de secretos del proyecto. Nunca pegues una clave de producción en un aviso, ejemplo, registro o repositorio.

Suponer que los límites de salida de las herramientas garantizan relevancia

Un límite de salida evita un tamaño ilimitado. No selecciona el pasaje correcto ni valida la página.

Lista de Verificación de Producción

• Corrige la pregunta, modelo, conjunto de fuentes y esquema de salida para el punto de referencia.
• Cuenta los caracteres devueltos en cada límite de herramienta.
• Elimina URLs canónicas duplicadas antes de la recolección.
• Prefiere Markdown, selectores o campos estructurados sobre HTML en bruto.
• Preserva la URL final, evidencia, tiempo de recolección y versión del contrato.
• Rechaza resultados de página incorrecta e incompletos antes del razonamiento del modelo principal.
• Limita las herramientas MCP visibles y los objetivos aprobados.
• Mantén los secretos fuera de los avisos y del control de versiones.
• Compara el costo de resultados aceptados, no conteos de tokens aislados.

Lee el resumen del Servidor MCP de Scrapeless, inspecciona los precios de Scrapeless, y comienza con una tarea de investigación limitada.

FAQ

P: ¿Utiliza WebFetch siempre menos tokens del Código Claude que una herramienta de navegador?

No. El uso de tokens depende del material devuelto al contexto. Una extracción de navegador concisa puede ser más pequeña que una obtención verbosa, mientras que una obtención limpia puede ser más pequeña que el HTML del navegador. Mide el contenido devuelto.

P: ¿Puede JSON Schema reducir los tokens de entrada?

Puede reducir y validar salidas estructuradas, pero no automáticamente disminuir el contenido de la página. Aplica un esquema en el límite de extracción y nuevamente en la respuesta final si es necesario.

P: ¿Son los conteos de tokens en este artículo tokens de Claude?

No. Son un proxy de comparación reproducible cl100k_base. Utiliza la interfaz actual de conteo de tokens o uso de Anthropic con tu modelo exacto de Claude para números relevantes para la facturación.

P: ¿Por qué usar MCP en lugar de llamar directamente a una API de extracción?

Usa MCP cuando Claude Code deba descubrir e invocar una herramienta limitada durante una tarea interactiva. Usa la API directa cuando el código de la aplicación ya sepa cuándo y cómo recopilar la página.

P: ¿Cómo sé que la extracción no eliminó un hecho requerido?

Define campos requeridos y evidencia antes de la recopilación, luego ejecuta verificaciones de completitud y semántica. Mantén la URL de origen y la instantánea en bruto fuera del prompt para auditoría o reprocesamiento.