> ## 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.

# Data Hub MCP tool reference

> Reference for the six stable tools of the Data Hub general MCP and the standard flow for searching, running, and retrieving Data App results.

This page describes the **Data Hub general MCP**. It first helps an agent discover a suitable Data App, then reads the app's live contract and runs it. It uses the same Data Hub capabilities as the "pick a specific app first, then connect" tutorials. The only difference is when the app is chosen.

<Note>
  The number, names, publishers, prices, inputs, and outputs of Data Apps change continuously. The MCP protocol tools are relatively stable. This page therefore focuses on the tool contracts and the general flow, and does not treat any snapshot of the catalog as a long-term list.
</Note>

## Two layers of capability

| Layer              | Content                                                                     | How to use it                                      |
| ------------------ | --------------------------------------------------------------------------- | -------------------------------------------------- |
| **Protocol layer** | Six tools: search, get details, run, get status, get result, and cancel run | A stable flow for agents or systems to integrate   |
| **Data layer**     | Each Data App's capability, price, fields, visibility, and run mode         | Search and read the details live before every call |

For long-term integration with a fixed app, record its `app_id`. `namespace/app_name` also references an app, but it may stop working if the publisher or app is renamed.

## The six MCP tools

### `search_data_apps`: search the catalog

Discover Data Apps with business keywords. `query` accepts keywords in any language. Leave it empty to page through the catalog visible to you. You can also filter with `type` for collection or lookup apps (`data`) and processing apps (`transform`), and with `scope` for `all`, `public`, `private`, or `shared`.

| Parameter         | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `query`           | Optional business keywords. Lists the catalog when empty |
| `type`            | Optional: `data` or `transform`                          |
| `scope`           | Optional visibility scope, default `all`                 |
| `offset`, `limit` | Paging. `limit` is `1-20`, default `5`                   |

Each result card includes the `app_id`, name, summary, run mode (`sync` / `async`), input and output hints, starting price, and visibility. Search and compare first. Do not run before confirming.

### `get_data_app_details`: read the full contract

Call this before running. Pass an `app_id` or `<namespace>/<app_name>` to get:

* `input_schema`: the standard JSON Schema this run must satisfy.
* `output_schema`: the fields that may be returned.
* `knowledge`: capability boundaries, expected latency, and caveats.
* `pricing`: billing description.
* `examples`: example inputs to use as a starting point.

<Tip>
  The safest approach is to copy an `input` from `examples` and adjust it. Do not guess field names from the page title, chat descriptions, or old tasks.
</Tip>

### `run_data_app`: start a run

Pass `app`, an `input` that satisfies the `input_schema`, and if needed `max_records` to cap the result count. If the input does not match the contract, the tool immediately returns `[invalid-input]` and points out the problem field.

Common return values include `run_id`, `state`, `progress`, `usage`, `billing`, and `next_step`. Use a small `max_records` on the first attempt to confirm the data, duration, and cost.

### `get_run_status`: check run status

Pass a `run_id` to check progress, failure details, usage, and cost, without reading data. For asynchronous tasks, use `wait_seconds` (`0-60`) for long polling. Wait 60 seconds per call instead of polling rapidly without pauses.

Common states are `QUEUED`, `RUNNING`, `SUCCEEDED`, `PARTIALLY_SUCCEEDED`, `FAILED`, and `CANCELLED`. On failure, look at `error.code`, `error.category`, `error.message`, and `error.retryable`.

### `get_run_result`: read results

Reads at most 50 records per call. Page with `offset`, and use `fields` to request a comma-separated subset of fields, such as `title,price,url`, so unneeded large fields do not flood the conversation.

When the response contains a `handoff`, the result is large or unsuitable for further paging in the conversation. Follow the SDK or REST command in the `handoff` to export a file instead of having the agent move the full JSON repeatedly.

### `cancel_run`: cancel a run

Pass a `run_id` to cancel a queued or running task. A running task may take a few seconds to stop cooperatively. Partial results that were already produced are kept and can still be read with `get_run_result`. Only the data that was produced is billed.

## Standard workflow

```text theme={null} theme={null}
search_data_apps
  → get_data_app_details
  → run_data_app
  → get_run_status (async only, long polling)
  → get_run_result
  → cancel_run (when you need to stop)
```

### Synchronous and asynchronous apps

| Run mode | Behavior                                                                      | Recommendation                                                                    |
| -------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `sync`   | Completes in seconds. Small results may return `records` directly             | Check the return first, then continue with `next_step`                            |
| `async`  | Returns a `run_id` immediately and runs the real extraction in the background | Submit several targets in a row, then wait with `get_run_status(wait_seconds=60)` |

Receiving a `run_id` for an asynchronous task does not mean the extraction succeeded. Confirm the final state before reading results, and do not resubmit the same target because of the wait.

## How to work with Data Apps

Data Apps are the concrete data capabilities on Data Hub. New apps appear and existing ones change, so this page keeps no fixed list. Before use, search with `search_data_apps` and confirm the current inputs, outputs, price, and boundaries with `get_data_app_details`.

## Connection and usage advice

* **App not chosen yet**: follow <a href="/docs/en/datahub/quick-start/agent-connection/general" target="_blank" rel="noopener noreferrer">General connection: choose an app inside the agent</a> to connect the Data Hub MCP first, then search, compare, and confirm.
* **Fixed app used long term**: use <a href="/docs/en/datahub/quick-start/agent-connection/codex" target="_blank" rel="noopener noreferrer">Codex: connect a specific app</a> or <a href="/docs/en/datahub/quick-start/agent-connection/claude-code" target="_blank" rel="noopener noreferrer">Claude Code: connect a specific app</a> to narrow the tool scope.
* **Cost or large data volumes involved**: call the details tool first to check `pricing` and `examples`, test with a small data volume, and handle the `handoff` when you need a large result.

<Note>
  The Data Hub general MCP is based on `https://mcp-v2.octoparse.com` and supports API key or OAuth. The connection configuration and current parameters are whatever the Data Hub Open Platform generates. It is different from the Octoparse scraping <a href="/docs/en/mcp/index" target="_blank" rel="noopener noreferrer">MCP Server</a> in the top navigation. Do not mix their addresses, authentication, or tool names.
</Note>