> ## 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 App을 먼저 고르지 않고 Data Hub MCP를 연결한 뒤, 에이전트가 작업마다 알맞은 데이터 기능을 검색하고 이해하고 실행하게 하는 방법을 안내합니다.

어떤 Data App을 사용할지 아직 모르거나, 에이전트가 작업마다 스스로 기능을 찾게 하고 싶다면 이 튜토리얼을 사용하세요. 범용 연결은 Data Hub의 검색 및 실행 도구를 에이전트에 추가합니다. 연결 후에는 필요한 데이터를 설명하면 에이전트가 알맞은 Data App을 검색하고 매개변수를 확인한 뒤 승인을 받아 실행합니다.

<Note>
  **범용 연결은 앱을 먼저 고를 필요가 없습니다.** 이 튜토리얼과 "Codex: 특정 앱 연결", "Claude Code: 특정 앱 연결" 튜토리얼은 서로 다른 두 가지 사용 방식입니다. 특정 앱 연결은 목적이 명확하고 장기적으로 고정된 기능에 적합합니다. 범용 연결은 요구가 변하거나 앱을 아직 고르지 않은 경우에 적합합니다.
</Note>

## 두 가지 연결 방식 이해하기

| 방식          | 작업 순서                                                | 적합한 경우                                                            |
| ----------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| **범용 연결**   | Data Hub MCP 연결 → 에이전트 안에서 앱 검색 → 상세 정보 확인 → 선택 후 실행 | 어떤 앱을 골라야 할지 모르는 경우, 작업마다 다른 데이터 기능이 필요한 경우, 에이전트가 검색을 돕길 원하는 경우. |
| **특정 앱 연결** | 목록에서 앱 선택 → 해당 앱의 설치 프롬프트 복사 → 에이전트 연결 → 바로 실행       | 고정 앱이 있는 경우, 도구 범위를 줄이고 싶은 경우, 안정적이고 반복되는 비즈니스 프로세스를 운영하는 경우.     |

두 방식 모두 Data Hub의 같은 Data App을 호출합니다. 유일한 차이는 앱을 어디서 고르느냐입니다. 두 종류의 연결을 모두 유지할 수 있지만, 에이전트가 잘못된 도구를 고르지 않도록 알아보기 쉬운 이름을 붙이세요.

## 완료 후 할 수 있는 일

이 튜토리얼을 마치면 에이전트 안에서 다음 작업을 순서대로 할 수 있습니다.

1. 키워드, 플랫폼, 시나리오로 Data App을 검색합니다.
2. 앱의 목적, 입력 매개변수, 출력 필드, 과금 정보를 확인합니다.
3. 앱과 매개변수를 확인한 뒤 실행을 시작합니다.
4. 비동기 작업의 상태를 확인하고 최종 결과를 가져옵니다.

<Note>
  `search_data_apps`, `run_data_app`, 비동기 상태 확인, 대용량 결과의 `handoff`에 대한 전체 매개변수와 처리 규칙은 <a href="/docs/ko/datahub/mcp-capabilities" target="_blank" rel="noopener noreferrer">Data Hub MCP 기능</a>을 참고하세요. 이 페이지는 연결과 첫 사용 흐름에 집중합니다.
</Note>

## 시작하기 전에

다음을 준비하세요.

* 로그인할 수 있는 Octoparse 계정.
* Claude Code, Codex, Cursor처럼 Streamable HTTP MCP를 지원하는 에이전트 클라이언트.
* API 키 방식을 선택하는 경우: Octoparse API 키를 미리 생성합니다.
* 테스트용 간단한 데이터 대상(예: "기업 정보를 보강할 수 있는 Data App 찾기").

<Warning>
  API 키는 계정 자격 증명입니다. 실제 키를 코드 저장소, 공유 설정, 공개 스크린샷, 그룹 채팅에 절대 넣지 마세요. OAuth 모드에서는 브라우저 세션의 임시 액세스 토큰을 로컬 설정에 복사하지 마세요.
</Warning>

## 1단계: 범용 MCP 연결 열기

<Steps>
  <Step title="Data Hub 오픈 플랫폼으로 이동">
    Octoparse 웹사이트에 로그인하고 상단의 Data Hub 메뉴를 연 뒤 **Data Hub Open Platform**을 클릭합니다.
  </Step>

  <Step title="MCP connection 열기">
    오픈 플랫폼의 왼쪽 탐색에서 **MCP connection**을 클릭하여 Data Hub MCP Server 페이지를 엽니다. 페이지에 표시된 기본 도구 세트는 Data Hub의 모든 Data App을 검색하고 실행할 수 있습니다. Data Hub에서 앱을 먼저 고를 필요가 없습니다.
  </Step>
</Steps>

<Tip>
  각 Data App의 **Integration** 섹션 하단에도 여기로 이어지는 MCP 연결 링크가 있습니다. 이 링크는 지름길일 뿐, 해당 앱을 먼저 골라야 한다는 뜻은 아닙니다.
</Tip>

## 2단계: 인증 방식 선택

범용 연결은 API 키와 OAuth를 모두 지원합니다. 이 선택은 인증에만 영향을 미치며 Data App을 검색하고 실행하는 방식은 바뀌지 않습니다.

### 방식 1: API 키(권장)

장기적인 안정적 사용, 명령줄 클라이언트, 자동화에 적합합니다. 페이지가 생성하는 설정에는 다음이 포함됩니다.

```text theme={null} theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

`Bearer`는 API 키를 전달하는 헤더 형식일 뿐입니다. 로그인된 브라우저 세션의 임시 액세스 토큰이 아니라 Octoparse API 키를 사용하세요.

아직 키가 없다면 <a href="https://www.octoparse.kr/console/open-platform/api-keys" target="_blank" rel="noopener noreferrer">Octoparse 계정 센터</a>에서 생성하세요. API 키 전체는 보통 생성 시 한 번만 표시됩니다. 신뢰할 수 있는 비밀번호 관리자에 보관하세요.

### 방식 2: OAuth 로그인

MCP OAuth를 지원하는 대화형 클라이언트에 적합합니다. OAuth를 선택하면 설정에 API 키가 포함되지 않습니다. 클라이언트가 처음 연결할 때 브라우저가 열리고, Octoparse에 로그인하여 권한 부여를 확인합니다. 세션이 만료될 수 있으며 그 경우 다시 권한을 부여합니다.

## 3단계: 범용 설치 프롬프트 복사

**MCP connection** 페이지에서 에이전트 클라이언트와 인증 방식을 선택한 뒤 **Copy install prompt**를 클릭합니다. **Copy MCP URL**은 서버 주소만 제공합니다. 페이지가 지금 생성한 전체 내용을 복사하세요. 서버 주소, 도구 범위, 헤더를 기억에 의존해 직접 입력하지 마세요.

<Tip>
  페이지에 표시된 범용 서버 주소는 `https://mcp-v2.octoparse.com`을 기반으로 합니다. 정확한 설정과 도구 매개변수는 바뀔 수 있으므로 항상 오픈 플랫폼이 현재 생성하는 내용을 사용하세요.
</Tip>

## 4단계: 에이전트가 설정을 완료하게 하기

아래 예시는 Claude Code를 사용합니다. Codex와 Cursor는 버튼 위치가 다르지만 핵심 단계는 같습니다. 설치 프롬프트를 붙여넣고, 인증 방식을 선택하고, 현재 사용자의 MCP 설정 변경을 허용한 뒤 클라이언트를 다시 로드합니다.

<Steps>
  <Step title="설치 프롬프트를 에이전트에 보내기">
    새 대화를 시작하고 복사한 전체 프롬프트를 붙여넣습니다. 에이전트는 설정을 쓰기 전에 인증 방식을 물어야 합니다. 프로젝트 파일에 자격 증명을 쓰려고 하면 중단시키고 현재 사용자의 로컬 MCP 설정을 사용하도록 요청하세요.
  </Step>

  <Step title="인증 방식 확인">
    API 키를 선택했다면 에이전트가 요청할 때 키를 안전하게 제공합니다. OAuth를 선택했다면 키를 제공하지 말고 에이전트가 자격 증명 없는 설정을 쓰게 합니다.
  </Step>

  <Step title="클라이언트 다시 로드">
    설정 후 MCP 서버를 다시 로드하거나 클라이언트를 재시작합니다. OAuth의 경우 첫 연결에서 "인증 필요"가 표시될 수 있으며 이는 정상입니다.
  </Step>
</Steps>

## 5단계: OAuth 권한 부여 완료(OAuth만 해당)

API 키를 선택했다면 다음 단계로 건너뛰세요.

<Steps>
  <Step title="클라이언트에서 연결 시작">
    Claude Code에서 `/mcp`를 실행하고 방금 추가한 Data Hub 서버(기본 이름 `octoparse_datahub`)를 선택합니다. 인증이 필요하다고 표시되면 인증을 선택합니다. 다른 클라이언트는 MCP 설정에 **Connect** 또는 비슷한 버튼이 있습니다.
  </Step>

  <Step title="브라우저에서 로그인 및 권한 부여">
    브라우저에 Octoparse 인증 페이지가 열립니다. 도메인과 현재 계정을 확인하고 요청된 권한 범위를 읽은 뒤 확인합니다. 페이지 안내에 따라 클라이언트로 돌아갑니다. 일부 클라이언트는 자동으로 돌아갑니다.
  </Step>

  <Step title="서버 활성화 확인">
    클라이언트로 돌아와 "인증 필요" 상태가 사라지고 서버가 활성화되었는지 확인합니다. 여전히 미인증으로 표시되면 클라이언트를 다시 로드하고 다시 시도하세요.
  </Step>
</Steps>

## 6단계: 먼저 검색하고 바로 실행하지 않기

범용 연결의 핵심은 에이전트가 먼저 Data App을 발견하게 하는 것입니다. 처음 사용할 때는 검색과 비교만 하고 아직 과금되는 작업을 만들지 말라고 명시적으로 요청하세요. 예시:

```text theme={null} theme={null}
Data Hub에서 "기업 정보 보강"과 관련된 Data App을 검색해 줘.
가장 관련성 높은 3개를 나열하고, 각각의 목적, 필요한 입력, 주요 출력 필드, 과금 모델을 설명해 줘.
아직 아무것도 실행하지 말고 내 확인을 기다려.
```

에이전트는 보통 `search_data_apps`로 목록를 검색한 뒤 `get_data_app_details`로 각 후보의 전체 계약을 읽습니다.

<Note>
  에이전트가 찾는 앱의 수, 이름, 플랫폼 범위는 Data Hub 목록에 따라 실시간으로 바뀝니다. 이 문서는 고정 목록을 제공하지 않습니다. 실제로 `search_data_apps`가 반환하는 내용을 기준으로 하세요.
</Note>

## 7단계: 앱을 확인한 뒤 실행

후보 중 앱 하나를 고릅니다. 에이전트가 매개변수와 예정된 작업을 다시 설명하게 한 뒤 소규모 테스트를 실행합니다.

```text theme={null} theme={null}
첫 번째 Data App을 선택해. 먼저 필수 매개변수, 기본값, 과금 모델을 알려 줘.
내가 확인하면 최소 데이터 볼륨으로만 실행하고 작업 상태, 레코드 수, 처음 5개 레코드를 반환해 줘.
```

<Steps>
  <Step title="입력과 비용 확인">
    필수 매개변수, 데이터 범위, 반환 필드, 과금 단위를 확인합니다. 불분명한 점이 있으면 매개변수를 추측하지 말고 에이전트가 상세 정보 도구를 다시 호출하게 하세요.
  </Step>

  <Step title="소규모 테스트 실행">
    확인 후에만 에이전트가 `run_data_app`을 호출하게 합니다. 동기 앱은 결과를 바로 반환합니다. 비동기 앱은 후속 상태 확인이 필요합니다.
  </Step>

  <Step title="비동기 결과 가져오기">
    비동기 작업은 에이전트가 상태 및 결과 도구로 완료를 기다린 뒤 최종 데이터를 반환하게 합니다. "작업 제출됨"을 성공적인 추출로 간주하지 마세요.
  </Step>

  <Step title="결과 확인">
    작업 상태, 실제 레코드 수, 핵심 필드를 확인합니다. 개별 레코드에 필드가 없는 것은 원본 데이터 차이 때문일 수 있습니다. 대부분의 레코드가 기대와 다르면 앱을 바꾸거나 매개변수를 조정하세요.
  </Step>
</Steps>

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="범용 연결은 Data App을 먼저 골라야 하나요?">
    아니요. 범용 연결은 먼저 검색 및 실행 도구를 제공합니다. 연결 후 에이전트가 `search_data_apps`로 기능을 찾습니다. Data Hub에서 앱을 먼저 골라야 하는 것은 특정 앱 연결뿐입니다.
  </Accordion>

  <Accordion title="API 키와 OAuth 중 무엇을 선택해야 하나요?">
    장기 사용, 명령줄 클라이언트, 자동화에는 API 키를 우선하세요. 브라우저로 로그인하고 싶고 클라이언트가 MCP OAuth를 명시적으로 지원하면 OAuth를 선택할 수 있습니다. OAuth 세션은 만료될 수 있으며 재인증이 필요합니다.
  </Accordion>

  <Accordion title="설정은 성공했지만 search_data_apps 도구가 없어요">
    특정 앱의 제한된 설정이 아니라 오픈 플랫폼 **MCP connection** 페이지의 범용 설정을 사용했는지 확인하세요. 현재 프롬프트를 다시 복사하고 클라이언트를 다시 로드합니다.
  </Accordion>

  <Accordion title="OAuth가 계속 인증 필요라고 표시돼요">
    클라이언트의 MCP 설정에서 연결을 시작하고 브라우저에서 로그인과 권한 부여를 완료한 뒤 클라이언트로 돌아옵니다. 브라우저가 리디렉션을 차단했는지 확인하고, 권한 부여 페이지가 Octoparse 공식 인증 서비스인지 확인하세요.
  </Accordion>

  <Accordion title="에이전트가 앱을 찾자마자 바로 실행했어요">
    프롬프트에 "검색과 비교만 하고 아직 실행하지 마"라고 명시하세요. 비용이나 대량 데이터가 관련된 경우 `run_data_app`을 호출하기 전에 확인을 기다리도록 에이전트에 요청하세요.
  </Accordion>

  <Accordion title="실행 후 작업 ID만 반환되고 데이터가 없어요">
    앱이 비동기일 가능성이 높습니다. 에이전트가 작업 상태를 계속 확인하고 완료되면 결과를 가져오게 하세요. 같은 작업을 다시 제출하지 마세요.
  </Accordion>
</AccordionGroup>

## 체크리스트

* Data Hub 오픈 플랫폼의 **MCP connection** 페이지에서 범용 설치 프롬프트를 복사했습니다.
* API 키 또는 OAuth 중 하나를 선택했고 두 자격 증명을 섞지 않았습니다.
* 에이전트가 Data Hub 범용 도구를 로드했고 `search_data_apps`를 사용할 수 있습니다.
* 실행을 확인하기 전에 검색하고 앱 상세 정보를 확인했습니다.
* 최소 데이터 볼륨으로 실제 호출을 한 번 완료하고 최종 결과를 확인했습니다.

## 사용할 앱을 이미 알고 있나요?

비즈니스에서 장기적으로 고정 앱을 사용한다면 연결 범위를 줄일 수 있습니다.

<CardGroup cols={2}>
  <Card title="Codex: 특정 앱 연결" href="/docs/ko/datahub/quick-start/agent-connection/codex">
    특정 앱을 먼저 고른 뒤 고정 도구로 Codex에 추가합니다.
  </Card>

  <Card title="Claude Code: 특정 앱 연결" href="/docs/ko/datahub/quick-start/agent-connection/claude-code">
    특정 앱을 먼저 고른 뒤 고정 MCP 서버로 Claude Code에 추가합니다.
  </Card>
</CardGroup>

<Note>
  검색이 반환하는 실제 앱 수, 이름, 게시자, 가격은 Data Hub 목록에 따라 바뀝니다. 각 호출에서 도구가 반환하는 내용을 기준으로 하세요.
</Note>