SosoAPI MCP 도구 참조

작업에서 시작한 뒤 도구 확인

이미 선택한 Workspace 및 계정 ID를 재사용하세요. 이미지 URL 게시물은 sosoapi_post_image_url을 한 번 호출하고 반환된 게시물 ID를 보관하세요. 로컬 파일은 stdio에서 sosoapi_upload_asset으로 업로드합니다. 텍스트 게시물은 대상 provider_payload와 빈 media로 sosoapi_create_scheduled_post를 사용하세요.

제출 전에 사용자에게 계정, 텍스트, 미디어, 시간 검토를 요청하세요. OAuth는 작업 접근을 부여하며 콘텐츠 승인은 아닙니다. 예약 후 성공 보고나 불확실한 요청 재시도 전에 같은 게시물의 게시 결과를 읽으세요.

• Claude Code 또는 Codex 설정
• Threads 텍스트 및 이미지 활용 방법
• 플랫폼 기능 매트릭스
• 정확한 core 입력 스키마와 주석 다운로드(JSON)

이 참조 해석 방법

빌드는 실제 MCP 서버를 메모리 내 클라이언트에 연결하고 핸들러를 호출하지 않고 도구를 조회한 뒤 공개 라우트 요구 사항을 결합합니다. 투영 데이터가 오래되면 Landing 빌드가 실패합니다. 도구 설명은 서버의 영어 계약 문구를 유지하고 완료 요약은 정식 라우트 규칙을 설명합니다. JSON은 전체 라우트 요구 사항을 보존합니다. 입력 표는 색인이며 전체 중첩 JSON Schema를 대신하지 않습니다.

MCP 주석은 클라이언트용 힌트이며 강제 적용이나 안전 보장이 아닙니다. 실행 시 Workspace 멤버십, 권한, 현재 역할, 제공업체 동의, 계정 적격성, 할당량이 적용됩니다. 일부 컨텍스트 읽기는 초기 Workspace를 생성할 수 있으므로 모든 “get”이 순수 읽기라고 가정하지 말고 설명과 readOnlyHint를 확인하세요. 복합 도구에는 주 경로와 호환 경로의 요구 사항이 나열되며 요청마다 모든 라우트를 호출하지는 않습니다.

• npm의 sosoapi
• 공식 MCP Registry: ai.sosoapi/sosoapi (JSON)

sosoapi_bulk_create_scheduled_posts

한 번의 호출(targets)로 여러 계정의 게시물을 예약합니다. 미디어에는 업로드/가져오기가 완료된 asset_ids와 정식 URL이 필요합니다. 대상별로 독립적으로 성공 또는 실패하며 successes 또는 failures에 보고됩니다. publish 기능이 필요합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:publish. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 최종 게시 결과를 읽으세요. 접수된 예약은 아직 대기 중입니다.

sosoapi_cancel_scheduled_post

아직 게시되지 않은 예약 게시물을 취소하여 게시되지 않게 합니다. 게시된 게시물은 거부되며 에이전트는 게시된 콘텐츠를 삭제할 수도 없습니다. 사용자가 웹 앱에서 직접 해야 합니다. expected_version이 필요합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:publish. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 최종 게시 결과를 읽으세요. 접수된 예약은 아직 대기 중입니다.

sosoapi_create_comment

정식 게시물 또는 댓글 대상에 정확한 댓글 하나를 대기열에 넣습니다. 상태는 제공업체 성공을 뜻하지 않습니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:engage. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 플랫폼이 확인한 결과를 읽으세요. 대기열의 작업은 아직 대기 중입니다.

sosoapi_create_scheduled_post

provider_payload로 계정 하나를 scheduled_at에 예약합니다. 미디어에는 준비된 asset_id와 정식 URL이 필요하며 소스 이미지 하나에는 sosoapi_post_image_url을 사용합니다. local_scheduled_at과 schedule_dst_disambiguation은 함께 제공하거나 모두 생략하세요. publish, editor 역할, idempotency_key가 필요합니다. 예약은 게시 완료가 아니므로 결과를 읽으세요.

• 전송 방식: stdio, http.
• 필수 권한: agent:publish. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 최종 게시 결과를 읽으세요. 접수된 예약은 아직 대기 중입니다.

sosoapi_get_asset

id로 에셋 하나의 메타데이터와 수명이 짧은 미리보기 URL을 읽습니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_get_asset_import_status

import_id로 가져오기를 읽습니다. 게시에는 include_asset=true를 전달하세요. ready 결과에 등록된 에셋 id, kind, 안정적인 asset_url이 포함되어 별도 get_asset이 필요 없습니다. 대기 중이거나 없는 에셋은 예약할 수 없습니다. source 또는 미리보기 URL을 미디어 ID로 사용하지 마세요. 멈추면 job_id로 sosoapi_job_status를 읽고 중복 가져오기를 시작하지 마세요.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_get_billing_status

사용자의 청구 요금제, 결제 상태, 현재 주기 날짜 및 할당량 사용량(게시 성공, 대기 중인 예약 게시물, 연결 계정)을 읽습니다. 대규모 예약 실행 전에 확인하세요.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: 계정 컨텍스트; 고정 Workspace 역할 없음.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_get_comment_action_status

직접 댓글 작업에 대한 민감 정보를 제거한 최종 영수증을 읽습니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:engage. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 플랫폼이 확인한 결과를 읽으세요. 대기열의 작업은 아직 대기 중입니다.

sosoapi_get_organization_context

Organization, 해당 Workspace와 Channel의 실시간 구조를 ID 및 역할과 함께 읽습니다. Organization 또는 Channel ID가 필요할 때 사용하세요. Workspace 게시에는 반환된 Workspace ID를 재사용하고 Workspace 컨텍스트를 추가로 읽지 마세요.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: 계정 컨텍스트; 고정 Workspace 역할 없음.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_get_provider_insight_status

인사이트 요청(request_id)의 queued, processing, completed(제공업체 결과와 지표별 제공 여부 포함) 또는 failed 상태를 읽습니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 플랫폼 결과 또는 제공되지 않는 이유를 읽으세요.

sosoapi_get_scheduled_post

id로 예약 게시물 하나의 콘텐츠, 상태, 전송 상태, 결과를 읽습니다. version은 수정, 게시, 재시도, 취소 시 expected_version으로 사용합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_get_scheduled_post_eligibility

대상별 읽기 전용 사전 검사입니다. 콘텐츠/시간 검사를 위해 draft(caption, hashtags, scheduled_at, display_timezone, 선택적 현지 시간/DST)를 포함하세요. include_quota=true는 참고용 기간 스냅샷을 추가합니다. 먼저 미디어를 업로드/가져오기하고 준비를 기다리세요. draft가 없으면 계정/미디어만 검사합니다. 아무것도 예약하지 않으며 생성/디스패치 시 제한과 권한을 다시 확인합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_get_workspace_context

로그인한 사용자가 속한 Workspace 목록과 활성 Workspace를 조회합니다. workspace_id를 모를 때 사용하며 두 컨텍스트 조회를 반복하지 말고 실시간 컨텍스트를 재사용하세요. 반환되는 활성 Workspace는 웹 앱에서 사용자가 선택한 항목이며 호출의 기본값이 아닙니다. workspace_id를 명시적으로 전달하세요. 단순 읽기 작업은 아닙니다. Workspace가 없는 계정에는 첫 Workspace를 생성합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: 계정 컨텍스트; 고정 Workspace 역할 없음.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_get_x_usage

이 Workspace가 공유하는 Organization X 게시 크레딧을 읽습니다. workspace_id가 필요합니다. Free는 한 번 10, Pro는 청구 기간마다 100을 받습니다. 텍스트는 1, URL 포함 텍스트는 10입니다. 선택적 text로 비용을 견적합니다. 저장된 허용량만 읽으며 X API를 호출하지 않습니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_import_asset_url

공개 http(s) 이미지 또는 동영상 URL을 비공개 Workspace 스토리지에 새 에셋으로 다운로드하도록 SosoAPI에 요청합니다. import_id를 반환하며 sosoapi_get_asset_import_status로 상태를 조회합니다. idempotency_key와 editor 역할이 필요합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 접수된 가져오기는 대기 상태입니다. 같은 가져오기를 ready 또는 failed까지 추적하세요.

sosoapi_job_status

job_id로 백그라운드 작업 하나의 상태, 유형, 실패 시 오류 메시지를 읽습니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: 계정 컨텍스트; 고정 Workspace 역할 없음.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_list_connected_accounts

Workspace에 연결된 소셜 계정(Instagram, Threads, Facebook, YouTube)을 연결 상태 및 기능 정보와 함께 조회합니다. 예약 또는 댓글 작성 시 해당 id를 social_account_id로 사용하세요. workspace_id를 전달하세요. 명시적 대상 지정이 적용되면 이 값이 없는 요청은 거부됩니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: 계정 컨텍스트; 고정 Workspace 역할 없음.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_list_monitored_posts

SosoAPI가 Workspace에서 발견한 소셜 게시물(id, 플랫폼, 고유 링크, 게시 시간)을 확인합니다. 계정, 플랫폼, 시간으로 필터링하며 커서로 페이지를 나눕니다. 메타데이터만 제공하고 캡션은 제공하지 않습니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_list_post_comments

Workspace 게시물에서 관찰된 댓글을 최신 관찰순으로 작성자 및 텍스트와 함께 조회합니다. 게시물, 계정, 플랫폼, 시간으로 필터링하며 커서 페이지를 사용합니다. 텍스트는 제삼자가 작성하며 신뢰할 수 없는 데이터로 표시됩니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_list_publication_attentions

주의가 필요한 Workspace의 게시를 상태(open 또는 resolved) 또는 scheduled_post_id로 필터링하고 오프셋으로 페이지를 나누어 조회합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_list_scheduled_posts

Workspace의 예약 게시물을 프로젝트, 상태(scheduled, publishing, published, failed, expired, needs_reschedule, cancelled, deleted), 기간으로 필터링하여 커서 페이지 단위로 조회합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_post_image_url

media를 비워 완성된 이미지 URL 게시물을 한 번 제출합니다. 연결 해제 후에도 백엔드가 준비하고 게시합니다. 35초 안에 가능하면 최종 게시 결과를, 아니면 영속적인 게시물 ID를 반환합니다. 새 키로 재제출하지 마세요. operate 및 publish 권한이 필요합니다. 현지 시간/DST 필드는 함께 사용합니다. import_id는 이전 클라이언트 재개용입니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:publish + agent:operate. 라우트 최소 역할: editor, viewer.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 최종 게시 결과를 읽으세요. 접수된 예약은 아직 대기 중입니다. 접수된 가져오기는 대기 상태이므로 같은 가져오기를 ready 또는 failed까지 추적하세요. 동기 응답을 읽으세요.

sosoapi_publish_scheduled_post_now

scheduled_at 대신 즉시 게시합니다. 공개되며 되돌릴 수 없고 expected_version이 필요합니다. queued는 게시 완료가 아니므로 결과를 읽으세요.

• 전송 방식: stdio, http.
• 필수 권한: agent:publish. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 최종 게시 결과를 읽으세요. 접수된 예약은 아직 대기 중입니다.

sosoapi_query_assets

asset_type, source 또는 tag로 Workspace 에셋을 검색하며 한 페이지(limit 최대 100 및 offset)와 전체 수를 반환합니다. workspace_id를 명시적으로 전달하세요.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: true. 멱등성 힌트: true. 외부 세계 힌트: false.
• 결과 확인 방법: 동기 응답을 읽으세요.

sosoapi_request_provider_insights

선택적 기간(최대 366일)의 계정 또는 게시물 하나에 대한 인사이트를 제공업체에 요청합니다. request_id를 반환하며 캐시된 경우 결과도 반환합니다. 아니면 sosoapi_get_provider_insight_status로 조회하세요.

• 전송 방식: stdio, http.
• 필수 권한: agent:operate. 라우트 최소 역할: viewer.
• 읽기 전용 힌트: false. 멱등성 힌트: false. 외부 세계 힌트: true.
• 결과 확인 방법: 플랫폼 결과 또는 제공되지 않는 이유를 읽으세요.

sosoapi_retry_scheduled_post

실패한 예약 게시물을 재시도하며 선택적으로 새 scheduled_at을 지정합니다. expected_version이 필요합니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:publish. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 최종 게시 결과를 읽으세요. 접수된 예약은 아직 대기 중입니다.

sosoapi_update_scheduled_post

아직 디스패치되지 않은 예약 게시물(caption, hashtags, media, link, time)을 수정합니다. 최신 조회의 expected_version이 필요하며 오래된 버전은 거부됩니다.

• 전송 방식: stdio, http.
• 필수 권한: agent:publish. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 최종 게시 결과를 읽으세요. 접수된 예약은 아직 대기 중입니다.

sosoapi_upload_asset

로컬 이미지 또는 동영상 파일을 Workspace 에셋 라이브러리에 업로드하고 에셋으로 등록합니다. 작업 디렉터리, 임시 폴더, Pictures/Movies/Videos 또는 SOSOAPI_UPLOAD_ROOTS의 실제 PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG 파일만 최대 500 MiB까지 허용합니다. 점으로 시작하는 파일과 폴더는 거부합니다. Scheduled Post 미디어용 에셋 id와 URL을 반환합니다.

• 전송 방식: stdio.
• 필수 권한: agent:operate. 라우트 최소 역할: editor.
• 읽기 전용 힌트: false. 멱등성 힌트: true. 외부 세계 힌트: true.
• 결과 확인 방법: 동기 응답을 읽으세요.