MCP소셜 데이터API 튜토리얼

SocQ MCP 가이드: Cursor, Claude, Codex에서 소셜 데이터 가져오기

Codex, Claude, Cursor, VS Code를 SocQ MCP에 연결하고, 도구 범위를 선택해 비동기 작업으로 공개 소셜 데이터를 수집하는 방법을 안내합니다.

SocQ2026년 9월 10일 업데이트약 11분 소요

AI 클라이언트는 어떤 엔드포인트를 호출해야 하는지 몰라도 소셜 데이터에 대해 이야기할 수 있습니다. 이것은 별도의 카탈로그가 필요한 문제가 아니라 라우팅 문제입니다. SocQ MCP는 REST와 같은 공개 데이터 API를 노출합니다. 호스팅 주소 하나, 도구 범위 세 가지, 동일한 비동기 작업 모델을 사용합니다.

이 가이드에서는 Codex, Claude, Cursor, VS Code를 연결하고, 범위를 고르고, 수집을 제출하고, 같은 작업을 계속 폴링하는 방법을 설명합니다. 설정 방법은 MCP 페이지에 있습니다. 필드를 임의로 만들지 말고 그 페이지에서 생성된 설정을 복사하세요.

SocQ MCP

빠른 답변: 호스팅된 Streamable HTTP 엔드포인트 https://api.socq.ai/mcp에 연결하세요. 탐색은 키 없이 사용할 수 있고, 수집에는 SocQ API 키가 필요합니다. Compact 모드는 socq_search_endpoints → socq_describe_endpoint → socq_execute 순서로 진행한 뒤, 반환된 작업을 이어서 조회합니다. 이 execute 호출을 모든 행을 한 번에 돌려주는 동기 방식으로 생각하지 마세요.

공식 플랫폼 API와 공개 MCP 중 무엇을 쓸까

사용자가 게시, 메시지 전송, 광고, 비공개 인사이트를 승인하는 경우에는 Instagram, X, YouTube 같은 공식 제품이 여전히 맞는 창구입니다. MCP는 그런 권한을 추가해 주지 않습니다.

SocQ MCP는 공개 데이터를 위한 창구입니다. 에이전트는 API 카탈로그에 이미 있는 기능만 호출할 수 있습니다. 게시할 수 없고, 비공개 계정을 읽을 수 없으며, 레지스트리에 없는 엔드포인트를 만들어 낼 수도 없습니다. REST, MCP, CLI는 동일한 작업을 실행합니다. Agent Skill은 에이전트가 엔드포인트를 고르고 크레딧을 추정하도록 돕는 도구이며, 별도의 데이터 서비스가 아닙니다. 제품이 이미 HTTP를 쓰고 있다면 REST를 유지하세요. 운영자가 터미널이나 CI 작업에서 일한다면 CLI를, IDE 에이전트라면 MCP를 사용하세요.

엔드포인트를 짐작하지 말고 도구 범위를 선택하기

MCP 클라이언트에는 현재 연결이 노출하는 도구만 보입니다. /mcp에서 범위를 고른 뒤 해당 주소를 복사하세요.

범위주소노출되는 범위적합한 용도
Compact/mcp탐색, 실행, 작업, 파일, 계정 도구여러 플랫폼을 오갈 수 있는 탐색
플랫폼/mcp?platforms=youtube,tiktok최대 5개 플랫폼의 타입별 수집 도구와 작업·파일·계정 도구정해진 플랫폼에서만 작업하는 에이전트
정확한 도구/mcp?tools=youtube_comments,x_search최대 30개의 타입별 도구와 작업·파일·계정 도구도구 목록을 통제하는 안정적인 워크플로

platforms와 tools는 함께 쓸 수 없습니다. 필터를 바꾼 뒤에는 클라이언트를 다시 연결해 tools/list를 새로 가져오게 하세요. 다시 연결하지 않은 Compact 연결은 이전 도구 목록을 계속 제공합니다.

그 범위 안에서도 구체적인 카탈로그 기능은 직접 선택해야 합니다. Compact 모드는 레지스트리를 검색합니다. 플랫폼 모드와 정확한 도구 모드는 입력 스키마가 해당 리소스의 REST 본문과 일치하는 타입별 도구를 호출합니다.

기본 선택 기준은 다음과 같습니다.

  • 질문이 YouTube 댓글에서 X 검색, Shop 쿼리로 옮겨 갈 수 있다면 Compact로 시작하세요.
  • 에이전트가 두세 개 네트워크에서만 작업한다면 플랫폼 모드로 전환하세요.
  • 실서비스 평가에서 도구 목록이 고정되어 있어야 한다면 정확한 도구 모드로 전환하세요.

5개 플랫폼 연결을 유지한 채 모델에게 "Amazon도 시도해 봐"라고 요청하지 마세요. 필터에 Amazon을 넣어 다시 연결하거나 Compact로 돌아가세요.

클라이언트를 연결하고 키를 Git에 올리지 않기

설정은 MCP 페이지와 같은 수준으로, 세 단계로 진행합니다.

  1. Compact, 플랫폼, 정확한 도구 중에서 선택합니다.
  2. Codex, Claude, Cursor, VS Code 중에서 선택합니다.
  3. 생성된 설정을 복사하고 다시 연결합니다.

클라이언트별 파일과 연결 방식:

클라이언트설정 파일연결 방식
Codex~/.codex/config.toml호스팅된 Streamable HTTP URL에 원격 HTTP로 연결
Claudeclaude_desktop_config.json@socq/mcp stdio 브리지, Node.js 20+
Cursor.cursor/mcp.json@socq/mcp stdio 브리지
VS Codemcp.jsonstdio 브리지, 키는 프롬프트 입력으로 전달

플랫폼, 엔드포인트, 스키마 탐색에는 키가 필요하지 않습니다. 수집, 계정, 작업 결과, 파일에는 키가 필요합니다. SOCQ_API_KEY는 환경 변수나 클라이언트의 보호된 프롬프트 입력에 저장하세요. 키를 커밋하지 마세요.

일반적인 Streamable HTTP 설정의 예시는 다음과 같습니다. 가능하면 MCP 페이지가 클라이언트별로 만들어 주는 파일을 사용하고, 문서화되지 않은 필드는 추가하지 마세요.

{
  "mcpServers": {
    "socq": {
      "url": "https://api.socq.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${SOCQ_API_KEY}"
      }
    }
  }
}

Codex는 그 호스팅 URL에 직접 연결합니다. Claude, Cursor, VS Code는 일반적으로 공개된 @socq/mcp 브리지를 통해 연결합니다. 저장한 뒤에는 클라이언트에서 SocQ 서버를 재시작하거나 다시 연결하세요.

REST와 MCP는 하나의 기능을 공유함

수집마다 REST 경로, 엔드포인트 ID, 타입별 도구 이름이 있습니다. Compact 모드에서는 비즈니스 필드를 input 안에 넣고, 타입별 도구는 그 스키마를 직접 노출합니다.

POST /v1/tiktok/profiles
  = endpoint id tiktok-profiles
  = typed tool tiktok_profiles

창구를 바꿔도 과금, 제한, 작업 응답 형식은 달라지지 않습니다. 탐색 도구는 수집 작업을 만들지 않습니다. REST가 사용자 이름 목록을 거부한다면 MCP도 거부합니다.

수집을 제출한 뒤 같은 작업을 폴링하기

Compact 모드는 도구 세 개를 거친 뒤 작업을 이어서 조회하는 흐름입니다.

natural-language request
  → socq_search_endpoints
  → socq_describe_endpoint
  → socq_execute(endpoint, input)
  → task_id
  → socq_get_task
  → results.items

socq_execute는 비즈니스 입력을 검증하고 비동기 수집을 만듭니다. 잠시 기다린 뒤 현재 상태를 돌려줄 수 있습니다. 작업이 아직 queued 또는 running이면 같은 task_id로 계속 조회하세요. 클라이언트 타임아웃이 수집을 취소하지는 않습니다.

작업이 성공하면 results.items를 읽으세요. has_more가 true인 동안에는 next_cursor를 그대로 전달합니다. 첫 페이지가 짧다는 이유로 같은 Instagram 프로필이나 TikTok 사용자 이름을 다시 제출하지 마세요.

플랫폼 모드와 정확한 도구 모드는 타입별 도구가 이미 컨텍스트에 있으면 검색 단계를 건너뜁니다. 작업 사양은 달라지지 않습니다. 한 번 만들고, ID를 저장하고, 폴링하고, 페이지를 넘기면 됩니다.

Compact 모드의 요청 예시입니다. 채팅 화면 캡처가 아닙니다.

Collect the public TikTok profile for @tiktok.
Describe the tiktok/profiles input first.
Execute, wait for the task, then return username, name, visible metrics, and collected_at.

에이전트는 "프로필이 동기 방식 도구 결과 하나로 도착했다"고 말하는 것이 아니라, 작업 ID와 정규화된 항목을 가지고 돌아와야 합니다.

REST에서 저장하는 것과 같은 운영용 행을 저장하세요.

  • 선택한 엔드포인트 ID 또는 타입별 도구 이름.
  • 정규화한 비즈니스 입력.
  • 작업 ID.
  • 처음 관찰한 상태와 최종 상태.
  • 마지막으로 사용한 next_cursor.

에이전트 프로세스가 중단되면 해당 작업을 이어서 처리하세요. 재시도 루프가 똑같은 TikTok 프로필 작업을 다섯 개나 열게 두지 마세요.

입력값 관리는 여전히 사용자의 몫

MCP를 쓴다고 REST 검증이 느슨해지지 않습니다.

  • Compact의 input은 socq_describe_endpoint가 반환한 엔드포인트 스키마와 일치해야 합니다.
  • 타입별 도구는 POST /v1/{platform}/{resource}와 같은 필수 필드를 노출합니다.
  • @를 제거하거나 일관되게 유지하세요. 프로필 URL은 프롬프트에서든 사전 단계에서든 사용자 이름으로 변환합니다.
  • 사용자 이름 필드에 동영상 URL을 보내거나, 게시물 URL 필드에 사용자 이름을 보내지 마세요.
  • results_limit은 상한으로만 사용하세요. 카탈로그는 완전한 수집을 보장하지 않습니다.
  • 범위에 해당 플랫폼이 빠져 있다면, 그 플랫폼을 포함하는 platforms 또는 tools 필터로 다시 연결하세요. 모델에게 "그냥 TikTok을 호출해 봐"라고 요청하지 마세요.

선택한 엔드포인트 ID, 입력값, 작업 ID는 직접 관리하는 로그에 기록하세요. 에이전트는 잊어버리지만, 작업 테이블은 잊어버리면 안 됩니다.

채팅 문장이 아니라 정규화된 필드를 읽기

성공한 항목은 REST와 같은 응답 형식을 씁니다. id, platform, resource, type, url, author, metrics, created_at, collected_at이 있고, 값이 있으면 extra도 포함됩니다.

에이전트가 null을 그대로 보존하도록 요청하세요. 숨겨진 팔로워 수는 0이 아닙니다. 스크립트가 없다고 해서 "음성이 없다"는 뜻이 아닙니다. 미디어 URL은 소스 참조입니다.

파일이 필요하면 해당 작업의 파일 도구로 가져오세요. 다른 페이지가 필요하면 커서를 유지하세요. 다른 리소스가 필요하면 그 리소스를 describe하고 execute하세요. 첫 번째 페이로드를 가짜 두 번째 스키마로 재구성하지 마세요.

에이전트가 요약한 행을 신뢰하기 전에 최소한 확인할 항목은 다음과 같습니다.

  • platform과 resource가 실행한 도구와 일치합니다.
  • id 또는 url 중 적어도 하나가 있습니다.
  • 지표는 숫자 또는 null이며, 억지로 0으로 바꾼 값이 없습니다.
  • collected_at이 있고 created_at에 복사되지 않았습니다.
  • 문장으로 된 답변을 모델의 기억이 아니라 results.items까지 추적할 수 있습니다.

에이전트에게 누락된 값을 "정리"하라고 하지 말고, 필드를 그대로 인용하라고 요청하세요.

에이전트용 갱신 주기

MCP 연결과 수집 작업은 서로 다른 시계로 움직입니다.

대상권장 습관이유
도구 범위필터를 바꿀 때마다 다시 연결클라이언트가 tools/list를 캐시함
탐색질문이 바뀌면 socq_search_endpoints를 다시 실행카탈로그는 실시간이며, 이전 검색 결과가 알맞은 리소스가 아닐 수 있음
수집 작업같은 ID를 폴링다시 제출하면 작업이 중복됨
프로필 성격의 엔티티주 1회 또는 월 1회신원 필드는 천천히 바뀜
게시물, 댓글, 광고, 상품활성 기간에는 1시간~1일공개 지표와 목록이 더 빠르게 변함
정확한 도구를 쓰는 실서비스 서버계획된 릴리스에서만 도구 변경예기치 못한 도구 목록 변경은 평가를 깨뜨림

완료된 작업을 "동기처럼 만들려고" 새로고침하지 마세요. 입력값이나 기간이 실제로 바뀌었을 때만 새 작업을 시작하세요.

자주 발생하는 문제

에이전트가 플랫폼이 없다고 말함

현재 연결이 Compact를 인식하지 못하거나, 다른 플랫폼으로 제한되어 있거나, 오래된 tools/list를 그대로 쓰고 있을 수 있습니다. /mcp를 열어 범위를 설정하고, 설정을 복사한 뒤 다시 연결하세요.

수집이 거부되는데 알맞은 프로필이 없음

탐색에는 키가 필요하지 않지만 실행에는 필요합니다. 환경 변수나 VS Code 프롬프트 입력의 SOCQ_API_KEY를 확인하세요.

첫 번째 도구 호출이 "끝났는데" 행이 없음

작업은 비동기입니다. 작업 상태를 읽으세요. 실패로 단정하거나 다시 제출하기 전에 socq_get_task를 계속 호출하세요.

에이전트가 게시나 비공개 데이터용 도구를 지어냄

그 기능은 카탈로그에 없습니다. 중단하세요. 쓰기와 비공개 인사이트에는 공식 OAuth 제품을 사용하세요.

페이지네이션이 일찍 끝남

has_more와 next_cursor는 결과의 일부이며 선택 사항이 아닙니다. 커서를 끝까지 소진하거나, 의도적으로 멈췄다는 사실을 기록하세요.

필터를 바꿨는데 아무 변화가 없음

platforms와 tools는 함께 쓸 수 없습니다. 전환한 뒤에는 다시 연결하세요.

책임 있는 사용

정당한 목적에 필요한 공개 데이터만 수집하세요. 에이전트에게 비공개 계정, 로그인, 접근 제어를 우회하라고 요청하지 마세요. 티켓에 붙여 넣을 프롬프트에 키가 들어가지 않게 하세요. 플랫폼 약관과 자체 보관 규칙을 검토하세요.

에이전트에게 다음을 요청하지 마세요.

  • 게시, 답글 작성, DM 전송.
  • 비공개 화면이나 로그인된 화면 열기.
  • socq_execute를 완성된 데이터셋으로 취급하기.
  • 한 URL에 platforms와 tools를 함께 쓰기.
  • 커밋되는 설정 파일에 실제 API 키를 직접 입력하기.

SocQ MCP는 기술적인 연결 수단입니다. 콘텐츠에 대한 추가 권리를 부여하지 않으며, 비공식 스크래핑을 공식 연동으로 바꿔 주지도 않습니다.

REST 워커에서 쓰는 것과 같은 데이터 최소화 원칙을 유지하세요. 티켓이 요구하는 공개 필드만 수집하고 멈추세요. 전체 카탈로그에 Compact로 접근하는 에이전트는 요청하지 않은 엔드포인트도 기꺼이 계속 탐색합니다. 범위를 좁힌 구성이 있는 이유가 바로 이것입니다.

자주 묻는 질문(FAQ)

SocQ MCP는 별도의 소셜 API인가요?

아니요. REST, CLI와 같은 카탈로그로 들어가는 또 다른 창구입니다.

API 키 없이 사용할 수 있나요?

플랫폼, 엔드포인트, 스키마는 탐색할 수 있습니다. 수집, 계정, 작업 결과, 파일에는 키가 필요합니다.

Compact 모드는 왜 모든 API를 별도 도구로 나열하지 않나요?

Compact 모드는 필요할 때 엔드포인트를 검색하고 설명하므로 전체 스키마가 모델 컨텍스트에 들어가지 않습니다.

execute가 모든 행을 바로 반환하나요?

아니요. 작업을 반환합니다. 그 작업을 이어서 조회하고 results.items를 페이지 단위로 넘기며 읽으세요.

에이전트가 X에 게시하거나 비공개 Instagram 계정을 읽을 수 있나요?

아니요. 카탈로그의 공개 기능만 호출할 수 있습니다.

Skill은 언제 추가해야 하나요?

에이전트가 여러 단계로 이루어진 작업에서 엔드포인트를 고르고 크레딧을 추정해야 할 때입니다. 실행은 여전히 MCP가 합니다. 자세한 내용은 /skill에 있습니다.

실제 클라이언트 설정은 어디서 복사하나요?

/mcp에서 범위를 고르고, 클라이언트를 고르고, 복사한 뒤 다시 연결하세요.

MULTI-PLATFORM API

공개 Multi-platform URL로 워크플로를 테스트하세요

공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.

Multi-platform API 살펴보기