> ## 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 도구 레퍼런스

> Data Hub 범용 MCP의 안정적인 여섯 가지 도구와 Data App 결과를 검색, 실행, 조회하는 표준 흐름을 정리한 레퍼런스입니다. 동기 및 비동기 실행과 대용량 결과 처리도 다룹니다.

이 페이지는 **Data Hub 범용 MCP**를 설명합니다. 먼저 에이전트가 알맞은 Data App을 발견하도록 돕고, 앱의 최신 계약을 읽은 뒤 실행합니다. "특정 앱을 먼저 고른 뒤 연결" 튜토리얼과 같은 Data Hub 기능을 사용하며, 유일한 차이는 앱을 고르는 시점입니다.

<Note>
  Data App의 수, 이름, 게시자, 가격, 입력, 출력은 계속 바뀝니다. MCP 프로토콜 도구는 비교적 안정적입니다. 따라서 이 페이지는 도구 계약과 일반 흐름에 집중하며, 특정 시점의 카탈로그를 고정된 목록으로 취급하지 않습니다.
</Note>

## 두 가지 기능 계층

| 계층          | 내용                                           | 사용 방법                       |
| ----------- | -------------------------------------------- | --------------------------- |
| **프로토콜 계층** | 검색, 상세 조회, 실행, 상태 조회, 결과 조회, 실행 취소의 여섯 가지 도구 | 에이전트나 시스템이 통합하기 위한 안정적인 흐름  |
| **데이터 계층**  | 각 Data App의 기능, 가격, 필드, 공개 범위, 실행 모드         | 호출 전마다 실시간으로 검색하고 상세 정보를 읽음 |

고정 앱을 장기적으로 통합할 때는 `app_id`를 기록해 두세요. `namespace/app_name`으로도 앱을 참조할 수 있지만 게시자나 앱 이름이 바뀌면 동작하지 않을 수 있습니다.

## 여섯 가지 MCP 도구

### `search_data_apps`: 카탈로그 검색

비즈니스 키워드로 Data App을 발견합니다. `query`는 모든 언어의 키워드를 지원합니다. 비워 두면 볼 수 있는 카탈로그를 페이지 단위로 조회합니다. `type`으로 수집 또는 조회 앱(`data`)과 처리 앱(`transform`)을 필터링하고, `scope`로 `all`, `public`, `private`, `shared`를 선택할 수도 있습니다.

| 매개변수              | 설명                            |
| ----------------- | ----------------------------- |
| `query`           | 선택적 비즈니스 키워드. 비어 있으면 카탈로그를 나열 |
| `type`            | 선택: `data` 또는 `transform`     |
| `scope`           | 선택적 공개 범위, 기본값 `all`          |
| `offset`, `limit` | 페이징. `limit`은 `1-20`, 기본값 `5` |

각 결과 카드에는 `app_id`, 이름, 요약, 실행 모드(`sync` / `async`), 입출력 힌트, 시작 가격, 공개 범위가 포함됩니다. 먼저 검색하고 비교하세요. 확인 전에는 실행하지 마세요.

### `get_data_app_details`: 전체 계약 읽기

실행 전에 호출합니다. `app_id` 또는 `<namespace>/<app_name>`을 전달하면 다음을 얻습니다.

* `input_schema`: 이 실행이 충족해야 하는 표준 JSON Schema.
* `output_schema`: 반환될 수 있는 필드.
* `knowledge`: 기능 경계, 예상 지연 시간, 주의 사항.
* `pricing`: 과금 설명.
* `examples`: 시작점으로 사용할 입력 예시.

<Tip>
  가장 안전한 방법은 `examples`에서 `input`을 복사하여 조정하는 것입니다. 페이지 제목, 채팅 설명, 이전 작업에서 필드 이름을 추측하지 마세요.
</Tip>

### `run_data_app`: 실행 시작

`app`, `input_schema`를 충족하는 `input`, 필요하면 결과 수를 제한하는 `max_records`를 전달합니다. 입력이 계약과 맞지 않으면 도구가 즉시 `[invalid-input]`을 반환하고 문제 필드를 알려 줍니다.

일반적인 반환값에는 `run_id`, `state`, `progress`, `usage`, `billing`, `next_step`이 포함됩니다. 첫 시도에서는 작은 `max_records`를 사용하여 데이터, 소요 시간, 비용을 확인하세요.

### `get_run_status`: 실행 상태 확인

`run_id`를 전달하여 데이터를 읽지 않고 진행 상황, 실패 세부 정보, 사용량, 비용을 확인합니다. 비동기 작업은 `wait_seconds`(`0-60`)로 롱 폴링합니다. 간격 없이 빠르게 폴링하지 말고 호출당 60초를 기다리세요.

일반적인 상태는 `QUEUED`, `RUNNING`, `SUCCEEDED`, `PARTIALLY_SUCCEEDED`, `FAILED`, `CANCELLED`입니다. 실패 시 `error.code`, `error.category`, `error.message`, `error.retryable`을 확인하세요.

### `get_run_result`: 결과 읽기

호출당 최대 50개 레코드를 읽습니다. `offset`으로 페이징하고, `fields`로 `title,price,url`처럼 쉼표로 구분된 필드 하위 집합을 요청하여 불필요한 대용량 필드가 대화에 넘치지 않게 하세요.

응답에 `handoff`가 포함되면 결과가 크거나 대화에서 계속 페이징하기에 적합하지 않다는 뜻입니다. 에이전트가 전체 JSON을 반복해서 옮기게 하지 말고 `handoff`의 SDK 또는 REST 명령에 따라 파일로 내보내세요.

### `cancel_run`: 실행 취소

`run_id`를 전달하여 대기 중이거나 실행 중인 작업을 취소합니다. 실행 중인 작업은 협조적으로 멈추는 데 몇 초가 걸릴 수 있습니다. 이미 생성된 부분 결과는 보존되며 `get_run_result`로 계속 읽을 수 있습니다. 생성된 데이터만 과금됩니다.

## 표준 워크플로

```text theme={null} theme={null}
search_data_apps
  → get_data_app_details
  → run_data_app
  → get_run_status (async만 해당, 롱 폴링)
  → get_run_result
  → cancel_run (중단이 필요할 때)
```

### 동기 앱과 비동기 앱

| 실행 모드   | 동작                                       | 권장 사항                                                       |
| ------- | ---------------------------------------- | ----------------------------------------------------------- |
| `sync`  | 몇 초 안에 완료. 소량 결과는 `records`를 바로 반환할 수 있음 | 먼저 반환값을 확인한 뒤 `next_step`에 따라 계속 진행                         |
| `async` | 즉시 `run_id`를 반환하고 실제 추출을 백그라운드에서 실행      | 여러 대상을 연달아 제출한 뒤 `get_run_status(wait_seconds=60)`로 한꺼번에 대기 |

비동기 작업에서 `run_id`를 받았다고 추출이 성공한 것은 아닙니다. 결과를 읽기 전에 최종 상태를 확인하고, 대기 때문에 같은 대상을 다시 제출하지 마세요.

## Data App 활용 원칙

Data App은 Data Hub의 구체적인 데이터 기능입니다. 새 앱이 추가되고 기존 앱도 바뀌기 때문에 이 페이지는 고정된 목록을 두지 않습니다. 사용 전에 `search_data_apps`로 검색하고 `get_data_app_details`로 현재 입력, 출력, 가격, 경계를 확인하세요.

## 연결 및 사용 조언

* **아직 앱을 고르지 않음**: <a href="/docs/ko/datahub/quick-start/agent-connection/general" target="_blank" rel="noopener noreferrer">범용 연결: 에이전트 안에서 앱 선택하기</a>에 따라 먼저 Data Hub MCP를 연결한 뒤 검색, 비교, 확인합니다.
* **고정 앱을 장기적으로 사용**: <a href="/docs/ko/datahub/quick-start/agent-connection/codex" target="_blank" rel="noopener noreferrer">Codex: 특정 앱 연결</a> 또는 <a href="/docs/ko/datahub/quick-start/agent-connection/claude-code" target="_blank" rel="noopener noreferrer">Claude Code: 특정 앱 연결</a>로 도구 범위를 줄입니다.
* **비용이나 대량 데이터가 관련됨**: 먼저 상세 정보 도구로 `pricing`과 `examples`를 확인하고 소량 데이터로 테스트하며, 대용량 결과가 필요하면 `handoff`를 처리합니다.

<Note>
  Data Hub 범용 MCP는 `https://mcp-v2.octoparse.com`을 기반으로 하며 API 키 또는 OAuth를 지원합니다. 연결 설정과 현재 매개변수는 Data Hub 오픈 플랫폼이 생성하는 내용을 따릅니다. 이는 상단 탐색의 Octoparse 스크래핑 <a href="/docs/ko/mcp/index" target="_blank" rel="noopener noreferrer">MCP 서버</a>와 다릅니다. 주소, 인증, 도구 이름을 섞어 쓰지 마세요.
</Note>