AI 에이전트(AI agents)는 추론에는 능숙하지만 사실 관계에는 취약합니다. 특정 냉동 제품이 현재 FDA 회수 대상인지 Claude에게 물어본다면, Claude는 몇 달 전의 데이터이거나 단순히 지어낸 내용일 수도 있는 학습 데이터로부터 매우 확신에 찬 답변을 내놓을 것입니다. 식품 안전 분야에서 "아마 괜찮을 것"이라는 식의 태도는 Class I 알레르기 유발 물질이 선반에 올라가게 만드는 원인이 됩니다.

이 가이드에서는 이 문제를 해결합니다. 우리는 Claude를 공식 Apify MCP 서버에 연결하고, FDA의 식품 회수 및 집행 보고서를 읽는 단일 Actor를 노출하여, "이 제품이 회수되었나요?"라는 질문을 추측이 아닌 공식 기록(source of record)에 대한 실시간 조회로 전환합니다. 이 가이드를 마칠 때쯤이면 여러분은 Claude, Cursor 또는 모든 MCP 클라이언트가 대화 도중에 호출할 수 있는 작동 가능한 회수 모니터링 도구를 갖게 될 것이며, 실행 과정 중 어느 시점에 도구가 작동하고 무엇을 반환하는지 정확히 이해하게 될 것입니다.

아래의 모든 내용은 실제 출력값이 포함된 실제 설정입니다. 모의 응답(mocked responses)은 없습니다.

Apify MCP 서버란 무엇인가요?

Model Context Protocol (MCP)는 AI 클라이언트가 외부 도구를 호출할 수 있게 해주는 개방형 표준입니다. Apify MCP 서버(https://mcp.apify.com)는 Apify 플랫폼 위에서 해당 표준을 구현하며, 이는 Apify Store에 있는 수천 개의 Actor 각각이 에이전트가 호출할 수 있는 도구가 된다는 것을 의미합니다.

왜 API 호출을 하드코딩하는 대신 MCP를 통해 Actor를 라우팅할까요?

• 에이전트가 언제 가져와야 할지 결정합니다. Claude는 대화를 읽고, 자신이 가지고 있지 않은 사실을 필요로 한다는 것을 감지한 후 스스로 도구를 호출합니다. 모든 질문에 대해 연결 코드(glue code)를 작성할 필요가 없습니다.
• 구조화된 입력 및 출력. MCP 서버는 Actor의 입력 스키마를 Claude에게 전달하여 모델이 매개변수를 정확하게 채우고, 추론할 수 있는 깔끔한 데이터셋을 반환합니다.
• 하나의 연결로 여러 도구 사용. 동일한 MCP 엔드포인트가 search-actors, fetch-actor-details, 그리고 call-actor를 노출하므로, 에이전트는 새로운 설정 없이 모든 Actor를 발견하고 실행할 수 있습니다.
• 인프라 구축 불필요. 서버는 호스팅됩니다. 구성 파일에 몇 줄만 추가하면 끝입니다.

사용할 Actor

우리는 openFDA Food Recall & Enforcement Scraper (USA)를 노출할 것입니다. 이 스크래퍼는 FDA의 공식 식품 리콜 및 단속 보고서를 읽고, 각 이벤트에 대한 전체 기록(리콜 번호, 위험 등급(Class I/II/III), 제품 설명, 리콜 사유, 리콜 기업 및 주소, 제품 수량 및 코드 정보, 유통 패턴(어느 주에서 발생했는지, 전국적인지 여부), 주요 날짜)을 반환합니다.

이 필드 세트는 식료품 구매자, 수입 QA 담당자, 또는 소매 규정 준수 팀이 '우리가 재고를 보유하고 있거나 곧 보유할 제품 중 리콜 목록에 있는 것이 있는지, 그리고 그 심각도는 어느 정도인지?'라는 질문에 빠르게 답하는 데 필요한 정보입니다. 식품 리콜은 공개적이고 권위 있으며 로그인 장벽이 없어 에이전트에게 제공하기 이상적인 첫 번째 데이터 소스입니다.

1단계: Apify API 토큰 받기

Apify Console에 로그인하여 Settings → Integrations를 열고 개인 API 토큰을 복사합니다. MCP 서버는 인증을 수행하고 Actor 실행 비용을 귀하의 계정으로 청구하기 위해 이 토큰을 사용합니다.

📌 참고: 토큰은 비밀 정보입니다. 클라이언트 설정(config)에만 보관하고, 프롬프트나 커밋된 파일에 절대 포함하지 마세요.

2단계: Claude Desktop을 Apify MCP 서버로 지정하기

Claude Desktop의 설정 파일(Settings → Developer → Edit Config, 또는 macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json)을 열고 Apify 서버를 추가합니다. tools 쿼리 파라미터가 중요한 부분입니다. 이 파라미터는 서버에 어떤 Actor를 노출할지 알려주어, Claude가 전체 Store 대신 하나의 특정 도구에 집중할 수 있게 합니다.

{
  "mcpServers": {
    "apify": {
...

Cursor는 .cursor/mcp.json에서 동일한 JSON을 사용합니다. 호스팅된 엔드포인트 대신 stdio를 통해 로컬에서 실행하는 것을 선호한다면 다음과 같이 설정합니다:

{
  "mcpServers": {
    "apify": {
...

Claude Desktop을 재시작하여 새로운 서버를 인식하도록 합니다.

3단계: 도구가 로드되었는지 확인하기

재시작 후, Actor가 호출 가능한 도구로 나타납니다. Apify 서버가 노출하는 도구 목록을 확인하면 스토리지 헬퍼(storage helpers)와 함께 Store 핸들 이름을 가진 Actor 자체가 표시됩니다:

get-actor-run, get-dataset-items, get-key-value-store-record,
abort-actor-run, scrapers_lat--openfda-food-recalls-scraper

마지막 항목인 scrapers_lat--openfda-food-recalls-scraper가 바로 우리의 회수 조회(recall-lookup) 도구입니다. 이제 Claude는 이 도구가 존재한다는 것과, 무엇을 하는지(Actor의 README를 통해), 그리고 어떤 입력값을 받는지(서버가 전달하는 입력 스키마를 통해) 알고 있습니다.

4단계: Claude에게 회수 사항 확인 요청하기

이제 결과물을 확인할 차례입니다. 일반적인 채팅에서 실제 사실(ground truth) 확인이 필요한 질문을 던져보세요:

"우리는 수입된 아시아산 냉동 식료품을 재고로 보유하고 있습니다. 우리가 선반에서 치워야 할, 미표기 알레르기 유발 물질로 인한 최근 FDA Class I 회수 사례가 있나요?"

Claude는 자신의 기억만으로는 이 질문에 신뢰할 수 있는 답변을 할 수 없음을 인지하고, 회수(recall) 도구를 선택한 뒤 사용자의 질문에서 입력값을 채웁니다. 내부적으로 클라이언트는 Actor의 파라미터가 포함된 tools/call을 전송합니다:

{
  "name": "scrapers_lat--openfda-food-recalls-scraper",
  "arguments": {
...

Apify MCP 서버는 Actor를 시작하고, 실행이 완료될 때까지 기다린 후 데이터셋(dataset)을 반환합니다. 다음은 생성된 실제 실행 메타데이터(run metadata)입니다:

{
  "runId": "NmLimdVRabbDI9oSk",
  "actorName": "scrapers_lat/openfda-food-recalls-scraper",
...

FDA의 집행 보고서(enforcement reports)를 대상으로 단 3초 만에 실시간 조회가 완료되었습니다.

5단계: 실제 출력 결과 읽기

도구가 반환하는 데이터셋은 구조화된 회수 데이터입니다. 다음은 실행 결과에서 추출한 실제 기록입니다 (선반 점검에 중요한 필드 위주로 요약됨):

{
  "recallNumber": "H-0530-2026",
  "classification": "Class I",
...

Claude는 이를 읽고 쉬운 언어로 답변합니다: 네, 냉동 어묵 제품에 대해 회수 번호 H-0530-2026인 Class I (1등급) 회수가 있습니다. 그 이유는 미표기 밀 및 참깨 (둘 다 미국의 주요 알레르기 유발 물질)가 포함되어 있기 때문이며, 캘리포니아의 KOI KOI Trading of Commerce에 의해 회수되었고, 8개 주 전역의 레스토랑 및 소매 식료품점에 유통된 344건의 사례입니다. 이 모든 사실은 모델의 기억이 아니라 공식 FDA 집행 보고서에서 추적 가능한 정보입니다.

위험 등급(hazard class)은 데이터를 의사결정으로 전환하는 핵심 요소입니다. Class I는 해당 제품을 사용할 경우 심각한 건강상의 결과나 사망을 초래할 합리적인 가능성이 있음을 의미하며, 이는 "다음 검토 시 표시해 두기"와 "오늘 즉시 격리하기"를 가르는 차이입니다. 분류(classification), UPC, 정확한 유통 주를 제시하는 에이전트는 식품 안전 담당자에게 행동에 필요한 모든 정보를 제공하지만, 모델 단독으로는 이 중 어떤 것도 신뢰성 있게 제공할 수 없습니다.

실제 활용 사례: 선반 모니터링 에이전트 (shelf-monitoring agent)

맥락을 살펴보겠습니다. 식료품 체인의 식품 안전 데스크나 수입업체의 QA(품질 보증) 팀은 자신들의 선반에 있거나 컨테이너로 들어오는 물품 중 활성화된 회수(recall) 대상이 없는지 지속적으로 확인해야 합니다. 이들에게 중요한 세 가지 요소는 다음과 같습니다:

1. 판매 중인 제품이 회수 대상 명단에 포함되어 있는가,
2. 사안이 얼마나 심각한가 (Class I인지 아니면 경미한 라벨링 오류인지),
3. 유통 범위(distribution footprint)가 실제로 자신들의 매장이나 지역에 도달하는가.

도구가 없다면, 분석가는 FDA 회수 사이트를 열고 제품이나 기업별로 검색한 뒤, 각 집행 보고서(enforcement report)를 읽고, SKU(재고 관리 단위)당 한 번씩 회수 번호, 등급(class), 해당 주(states)를 추적기에 복사해야 합니다. Claude에 도구가 연결되어 있다면, 분석가는 공급업체 목록이나 제품 이름 묶음을 채팅창에 붙여넣고 에이전트에게 각각을 확인해 달라고 요청하기만 하면 됩니다. Claude는 쿼리당 Actor를 호출하고, Class I 이벤트로 필터링하며, 반환된 distributionStates를 체인의 유통 범위와 비교한 뒤, 증거로서 회수 번호가 포함된 짧은 '회수 또는 모니터링' 목록을 생성합니다. 수동 조회 단계는 사라지고, 판단은 인간의 몫으로 남습니다.

이것이 모든 훌륭한 에이전트 도구의 형태입니다. 즉, 결정(decision)을 제거하는 것이 아니라 기계적인 가져오기(mechanical fetch)를 제거하는 것입니다.

더 나아가기: 두 번째 도구 연결하기

회수 모니터링은 포장된 제품에서 그치지 않는 경우가 많습니다. 만약 외식업을 운영하거나 공급한다면, 해당 물품을 취급하는 시설이 깨끗한 검사 이력을 가지고 있는지 알고 싶을 것입니다. 동일한 MCP 연결을 통해 tools 파라미터를 확장함으로써 더 많은 Actor를 노출할 수 있습니다:

이제 에이전트는 FDA 집행 보고서에서 Class I 회수를 찾아내는 동시에 동일한 대화 내에서 레스토랑이나 시설의 위생 검사 기록을 가져올 수 있으며, 이 두 가지를 하나의 위험 요약으로 결합할 수 있습니다. 즉, "이 제품은 회수 대상이며, 해당 제품이 도달한 판매점의 검사 상태는 다음과 같습니다"라고 알려주는 것입니다. 각 Actor는 별개의 도구이므로, 에이전트는 각 단계에 맞는 적절한 도구를 스스로 선택합니다.

🏹 문제 해결 (Troubleshooting): 만약 Claude에 도구가 나타나지 않는다면, 일반적인 두 가지 원인은 tools 파라미터에 Actor 핸들(handle)이 누락되었거나 잘못 입력된 경우(Store URL에 있는 username/actor-name과 정확히 일치해야 합니다), 그리고 Claude가 실행 중인 동안 설정을 수정했을 경우입니다. 핸들을 수정하고 저장한 뒤, 클라이언트를 완전히 재시작하세요.

📌 참고: 각 도구 호출은 귀하의 Apify 계정으로 비용이 청구되는 실제 Actor 실행입니다 (이 Actor는 결과당 과금 방식입니다). 가끔씩 선반 점검을 하는 용도라면 비용은 1센트의 아주 작은 일부에 불과합니다. 만약 수천 개의 SKU를 정기적으로 스캔할 계획이라면, 채팅 메시지당 한 번씩 호출하는 대신 Apify API 또는 예약된 작업(scheduled task)을 통해 Actor를 직접 실행하고 결과를 저장하는 방식을 권장합니다.

마무리

이제 귀하는 대화 도중 필요할 때마다 공식 FDA 회수 및 집행 보고서를 바탕으로 식품 제품을 확인할 수 있는 AI 에이전트를 갖게 되었습니다. 이 에이전트는 실제 선반 의사결정에 필요한 위해 등급(hazard class) 및 유통 세부 정보를 제공합니다. 이 패턴은 재사용이 가능합니다. 권위 있는 구조화된 데이터(structured data)를 반환하는 Actor를 선택하고, tools 파라미터를 통해 Apify MCP 서버로 이를 노출시킨 뒤, 에이전트가 언제 호출할지 결정하도록 하면 됩니다.

더 나아가려면:

• Actor의 필터(분류, 주(state), 회수 기업, 날짜 범위)를 사용하여 쿼리를 좁힘으로써, 에이전트가 귀하의 사업 영역과 관련된 이벤트만 보도록 설정하세요.
• 식당 검사, 의약품 라벨 또는 의료 기기 회수 Actor를 추가하여 더 광범위한 식품 및 제품 안전 에이전트를 구축하세요.
• OAuth 설정, 리소스 읽기, 그리고 에이전트가 사전 구성되지 않은 Actor를 스스로 찾아낼 수 있게 해주는 search-actors / call-actor 도구에 대한 내용은 Apify MCP 서버 문서를 참조하세요.

이 가이드에서 사용된 Actor: openFDA Food Recall & Enforcement Scraper (USA).