> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Referencia de herramientas MCP de Data Hub
> Las seis herramientas del MCP general de Data Hub y el flujo estándar para buscar, ejecutar y recuperar los resultados de una Data App.
Esta página describe el **MCP general de Data Hub**. Primero ayuda a un agente a descubrir una Data App adecuada, luego lee el contrato actualizado de la aplicación y la ejecuta. Usa las mismas capacidades de Data Hub que los tutoriales de «elegir primero una aplicación específica y luego conectar». La única diferencia es cuándo se elige la aplicación.
El número, los nombres, los editores, los precios, las entradas y las salidas de las Data Apps cambian continuamente. Las herramientas del protocolo MCP son relativamente estables. Por eso esta página se centra en los contratos de las herramientas y en el flujo general, y no trata ninguna instantánea del catálogo como una lista duradera.
## Dos niveles de capacidad
| Nivel | Contenido | Cómo usarlo |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Nivel de protocolo** | Seis herramientas: buscar, obtener detalles, ejecutar, obtener estado, obtener resultado y cancelar ejecución | Un flujo estable para que agentes o sistemas se integren |
| **Nivel de datos** | Capacidad, precio, campos, visibilidad y modo de ejecución de cada Data App | Buscar y leer los detalles actualizados antes de cada llamada |
Para una integración a largo plazo con una aplicación fija, anota su `app_id`. `namespace/app_name` también referencia una aplicación, pero puede dejar de funcionar si se cambia el nombre del editor o de la aplicación.
## Las seis herramientas MCP
### `search_data_apps`: buscar en el catálogo
Descubre Data Apps con palabras clave de negocio. `query` acepta palabras clave en cualquier idioma. Déjalo vacío para recorrer el catálogo visible para ti. También puedes filtrar con `type` para aplicaciones de recopilación o consulta (`data`) y de procesamiento (`transform`), y con `scope` para `all`, `public`, `private` o `shared`.
| Parámetro | Descripción |
| ----------------- | --------------------------------------------------------------------- |
| `query` | Palabras clave de negocio opcionales. Lista el catálogo si está vacío |
| `type` | Opcional: `data` o `transform` |
| `scope` | Alcance de visibilidad opcional, `all` por defecto |
| `offset`, `limit` | Paginación. `limit` va de `1-20`, `5` por defecto |
Cada tarjeta de resultado incluye el `app_id`, el nombre, el resumen, el modo de ejecución (`sync` / `async`), indicaciones de entrada y salida, el precio inicial y la visibilidad. Busca y compara primero. No ejecutes antes de confirmar.
### `get_data_app_details`: leer el contrato completo
Llama a esta herramienta antes de ejecutar. Pasa un `app_id` o `/` para obtener:
* `input_schema`: el JSON Schema estándar que esta ejecución debe cumplir.
* `output_schema`: los campos que pueden devolverse.
* `knowledge`: límites de la capacidad, latencia esperada y advertencias.
* `pricing`: descripción de la facturación.
* `examples`: entradas de ejemplo para usar como punto de partida.
El enfoque más seguro es copiar un `input` de `examples` y ajustarlo. No adivines los nombres de los campos a partir del título de la página, las descripciones del chat o tareas antiguas.
### `run_data_app`: iniciar una ejecución
Pasa `app`, un `input` que cumpla el `input_schema` y, si es necesario, `max_records` para limitar el número de resultados. Si la entrada no coincide con el contrato, la herramienta devuelve de inmediato `[invalid-input]` y señala el campo problemático.
Los valores de retorno habituales incluyen `run_id`, `state`, `progress`, `usage`, `billing` y `next_step`. Usa un `max_records` pequeño en el primer intento para confirmar los datos, la duración y el coste.
### `get_run_status`: comprobar el estado de la ejecución
Pasa un `run_id` para comprobar el progreso, los detalles del fallo, el uso y el coste, sin leer datos. Para tareas asíncronas, usa `wait_seconds` (`0-60`) para long polling. Espera 60 segundos por llamada en lugar de consultar rápidamente sin pausas.
Los estados habituales son `QUEUED`, `RUNNING`, `SUCCEEDED`, `PARTIALLY_SUCCEEDED`, `FAILED` y `CANCELLED`. En caso de fallo, revisa `error.code`, `error.category`, `error.message` y `error.retryable`.
### `get_run_result`: leer los resultados
Lee como máximo 50 registros por llamada. Pagina con `offset` y usa `fields` para solicitar un subconjunto de campos separados por comas, como `title,price,url`, para que los campos grandes innecesarios no saturen la conversación.
Cuando la respuesta contiene un `handoff`, el resultado es grande o no es adecuado para seguir paginando en la conversación. Sigue el comando SDK o REST del `handoff` para exportar un archivo en lugar de hacer que el agente mueva el JSON completo una y otra vez.
### `cancel_run`: cancelar una ejecución
Pasa un `run_id` para cancelar una tarea en cola o en ejecución. Una tarea en ejecución puede tardar unos segundos en detenerse de forma cooperativa. Los resultados parciales ya producidos se conservan y aún pueden leerse con `get_run_result`. Solo se facturan los datos producidos.
## Flujo de trabajo estándar
```text theme={null} theme={null}
search_data_apps
→ get_data_app_details
→ run_data_app
→ get_run_status (solo async, long polling)
→ get_run_result
→ cancel_run (cuando necesites detener)
```
### Aplicaciones síncronas y asíncronas
| Modo de ejecución | Comportamiento | Recomendación |
| ----------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `sync` | Termina en segundos. Los resultados pequeños pueden devolver `records` directamente | Comprueba primero el retorno y luego continúa con `next_step` |
| `async` | Devuelve un `run_id` de inmediato y ejecuta la extracción real en segundo plano | Envía varios objetivos seguidos y luego espera con `get_run_status(wait_seconds=60)` |
Recibir un `run_id` para una tarea asíncrona no significa que la extracción haya tenido éxito. Confirma el estado final antes de leer los resultados, y no vuelvas a enviar el mismo objetivo por la espera.
## Cómo trabajar con las Data Apps
Las Data Apps son las capacidades de datos concretas de Data Hub. Aparecen nuevas y las existentes cambian, así que esta página no mantiene ninguna lista fija. Antes de usarlas, busca con `search_data_apps` y confirma las entradas, salidas, precio y límites actuales con `get_data_app_details`.
## Consejos de conexión y uso
* **Aplicación aún sin elegir**: sigue Conexión general: elegir una aplicación dentro del agente para conectar primero el MCP de Data Hub y luego buscar, comparar y confirmar.
* **Aplicación fija usada a largo plazo**: usa Codex: conectar una aplicación específica o Claude Code: conectar una aplicación específica para reducir el alcance de las herramientas.
* **Costes o grandes volúmenes de datos de por medio**: llama primero a la herramienta de detalles para comprobar `pricing` y `examples`, prueba con un volumen de datos pequeño y gestiona el `handoff` cuando necesites un resultado grande.
El MCP general de Data Hub se basa en `https://mcp-v2.octoparse.com` y admite clave API u OAuth. La configuración de conexión y los parámetros actuales son los que genera la Data Hub Open Platform. Es distinto del servidor MCP de scraping de Octoparse de la navegación superior. No mezcles sus direcciones, autenticación ni nombres de herramientas.