MCPソーシャルデータAPIチュートリアル

SocQ MCPガイド:Cursor・Claude・Codexでソーシャルデータを取得する方法

Codex、Claude、Cursor、VS CodeをSocQ MCPに接続し、ツールのスコープを選んで、非同期タスクで公開ソーシャルデータを取得する手順を解説します。

SocQ2026年9月10日更新約14分で読めます

AIクライアントは、どのエンドポイントを呼び出せばよいか分からなくても、ソーシャルデータについて会話はできます。これは別のカタログが必要という話ではなく、ルーティングの問題です。SocQ MCPは、RESTで使われているものと同じ公開データAPIを、1つのホスト型アドレス、3つのツールスコープ、同じ非同期タスクのモデルで公開します。

このガイドでは、Codex、Claude、Cursor、VS Codeを接続し、スコープを選び、データ取得を送信して、同じタスクをポーリングし続ける手順を紹介します。セットアップの詳細はMCPのページにあります。存在しないフィールドを自分で考えるのではなく、そこで生成された設定をコピーしてください。

SocQ MCP

結論: ホスト型のStreamable HTTPエンドポイントhttps://api.socq.ai/mcpに接続します。ディスカバリーはキーなしで使えますが、データ取得にはSocQのAPIキーが必要です。コンパクトモードでは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でスコープを選び、対応するアドレスをコピーしてください。

スコープアドレス利用できるツール向いている用途
コンパクト/mcpディスカバリー、実行、タスク、ファイル、アカウントのツールプラットフォームをまたぐ可能性のある探索
プラットフォーム指定/mcp?platforms=youtube,tiktok最大5つのプラットフォーム向けの型付きデータ取得ツールと、タスク、ファイル、アカウントのツール決まったプラットフォームだけを扱うエージェント
ツール指定/mcp?tools=youtube_comments,x_search最大30個の型付きツールと、タスク、ファイル、アカウントのツールツール一覧を管理する安定したワークフロー

platformsとtoolsは同時に指定できません。フィルターを変更したら、クライアントを再接続してtools/listを更新してください。再接続しないコンパクト接続は、以前のツール一覧を返し続けます。

そのスコープの中で、カタログの具体的な機能を選ぶのは引き続き利用者の役割です。コンパクトモードではレジストリを検索します。プラットフォーム指定とツール指定のモードでは、入力スキーマがそのリソースのRESTボディと一致する型付きツールを呼び出します。

おすすめの使い分けは次のとおりです。

  • 質問がYouTubeのコメントからX検索、Shopのクエリへと飛ぶ可能性があるなら、コンパクトで始める。
  • エージェントが2〜3のネットワークだけで作業するなら、プラットフォーム指定に切り替える。
  • 本番の評価でツール一覧を固定して見せる必要があるなら、ツール指定に切り替える。

5つのプラットフォームで接続したまま、モデルに「Amazonも試して」と頼まないでください。フィルターにAmazonを加えて再接続するか、コンパクトに戻します。

クライアントを接続し、キーをGitに入れない

セットアップは、MCPのページと同じ粒度で、次の3ステップで行います。

  1. コンパクト、プラットフォーム指定、ツール指定のいずれかを選ぶ。
  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、型付きツール名があります。コンパクトモードでは、ビジネス用のフィールドをinputの中に入れます。型付きツールは、そのスキーマを直接公開します。

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

入口を切り替えても、課金、制限、タスクのエンベロープは変わりません。ディスカバリーのツールはデータ取得ジョブを作成しません。RESTがユーザー名のリストを拒否する場合は、MCPも拒否します。

データ取得を送信し、同じタスクをポーリングする

コンパクトモードは、3つのツールを順に使い、その後タスクを継続する流れです。

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を保存し、ポーリングし、ページネーションを進めます。

コンパクトモードでの依頼の例を示します。チャットのスクリーンショットではありません。

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と正規化されたアイテムです。「プロフィールが1回の同期的なツール結果で届いた」という主張ではありません。

RESTの場合と同じ運用上の行を保存してください。

  • 選択したエンドポイントIDまたは型付きツール名。
  • 正規化されたビジネス入力。
  • タスクID。
  • 最初に確認したステータスと最終ステータス。
  • 最後に取得したnext_cursor。

エージェントのプロセスが落ちた場合は、そのタスクを再開してください。リトライのループで、まったく同じTikTokプロフィールのジョブを5つも開かせてはいけません。

入力の衛生管理は利用者の責任

MCPがRESTの検証を緩めることはありません。

  • コンパクトモードのinputは、socq_describe_endpointが返すエンドポイントのスキーマに一致させる。
  • 型付きツールは、POST /v1/{platform}/{resource}と同じ必須フィールドを公開する。
  • @は取り除くか、一貫して付ける。プロフィールのURLは、プロンプトか事前処理でユーザー名に変換する。
  • 動画のURLをユーザー名のフィールドに、ユーザー名をステータスURLのフィールドに送らない。
  • results_limitは上限として扱う。カタログは網羅性を保証しない。
  • スコープにそのプラットフォームが含まれていなければ、含まれるプラットフォーム指定またはツール指定のフィルターで再接続する。モデルに「とにかくTikTokを呼んで」と頼まない。

選択したエンドポイントID、入力、タスクIDは、自分のログに書き込んでください。エージェントは忘れますが、ジョブの管理表は忘れてはいけません。

チャットの文章ではなく、正規化されたフィールドを読む

成功したアイテムはRESTと同じエンベロープを使います。id、platform、resource、type、url、author、metrics、created_at、collected_at、および存在する場合はextraです。

エージェントには、nullをそのまま保持させてください。非表示のフォロワー数は0ではありません。文字起こしがないことは「発話なし」を意味しません。メディアのURLは出典の参照です。

ファイルが必要な場合は、そのタスクに対応するファイルツールで取得します。別のページが必要な場合は、カーソルを保持してください。別のリソースが必要な場合は、そのリソースをdescribeしてexecuteします。最初のペイロードを加工して偽の第2のスキーマにしてはいけません。

エージェントが要約した行を信頼する前の最低限のチェックは次のとおりです。

  • platformとresourceが、実行したツールと一致している。
  • idまたはurlの少なくとも一方が存在する。
  • 指標は数値かnullで、強制的に0にされていない。
  • collected_atが存在し、created_atにコピーされていない。
  • 文章での回答が、モデルの記憶ではなくresults.itemsまでたどれる。

エージェントには、フィールドを引用させ、欠けている値を「整える」ことはさせないでください。

エージェント向けの更新頻度

MCPの接続とデータ取得ジョブは、それぞれ別の時計で動きます。

対象適切な習慣理由
ツールのスコープフィルターを変更するたびに再接続するクライアントがtools/listをキャッシュするため
ディスカバリー質問が変わったらsocq_search_endpointsをやり直すカタログは常に更新されており、前回の結果が別のリソースかもしれないため
データ取得タスク同じIDをポーリングする再送信すると作業が重複するため
プロフィールのようなエンティティ週次または月次本人情報の変化はゆっくりなため
投稿、コメント、広告、商品稼働中は1時間〜1日ごと公開指標や出品の変化が速いため
ツール指定の本番サーバー計画したリリースのときだけツールを変更する予期しないツール一覧の変更は評価を壊すため

完了したタスクを「同期的にするために」更新してはいけません。新しいタスクを開始するのは、入力または期間が実際に変わったときだけです。

よくある失敗パターン

エージェントがプラットフォームが存在しないと言う

現在の接続が、コンパクトモードを認識していないか、他のプラットフォームに限定されているか、古いtools/listを保持したままの可能性があります。/mcpを開き、スコープを設定して、設定をコピーし、再接続してください。

データ取得が、役に立つ情報のないまま拒否される

ディスカバリーにキーは不要ですが、実行には必要です。環境変数またはVS Codeのプロンプト入力でSOCQ_API_KEYを確認してください。

最初のツール呼び出しが、行のないまま「完了」した

ジョブは非同期です。タスクのステータスを確認してください。失敗と判断したり再送信したりする前に、socq_get_taskを続けて呼び出します。

エージェントが、投稿公開や非公開データのツールを作り出す

その機能はカタログにありません。そこで止めてください。書き込みや非公開のインサイトには、公式のOAuthプロダクトを使います。

ページネーションが途中で止まった

has_moreとnext_cursorは、飾りではなく結果の一部です。カーソルを最後まで進めるか、意図して止めたことを記録してください。

フィルターを変更しても何も変わらない

platformsとtoolsは組み合わせられません。切り替えたら再接続してください。

責任ある利用

正当な目的に必要な公開データだけを収集してください。エージェントに、非公開アカウント、ログイン、アクセス制御を回避させてはいけません。チケットに貼り付けるプロンプトに、キーを含めないでください。プラットフォームの利用規約と、自社のデータ保持ルールを確認してください。

エージェントに次のことをさせないでください。

  • 投稿、返信、DMの送信。
  • 非公開またはログイン状態の画面を開くこと。
  • socq_executeを完成したデータセットとして扱うこと。
  • 1つのURLでplatformsとtoolsを組み合わせること。
  • 有効なAPIキーを、コミットする設定ファイルに直接書き込むこと。

SocQ MCPは技術的な接続手段です。コンテンツに対する追加の権利を与えるものではなく、非公式のスクレイピングを公式の連携にするものでもありません。

RESTのワーカーで使うのと同じデータ最小化のルールを守ってください。チケットで必要な公開フィールドを収集したら、そこで止めます。カタログ全体にコンパクトモードでアクセスできるエージェントは、頼んでいないエンドポイントでも喜んで探し続けます。スコープを絞る仕組みは、そのためにあります。

よくある質問(FAQ)

SocQ MCPは別のソーシャルAPIですか?

いいえ。RESTやCLIで使われているのと同じカタログへの、もう1つの入口です。

APIキーなしで使えますか?

プラットフォーム、エンドポイント、スキーマのディスカバリーはできます。データ取得、アカウント、タスクの結果、ファイルにはキーが必要です。

コンパクトモードで、すべてのAPIを個別のツールとして一覧表示しないのはなぜですか?

コンパクトモードは、必要なときにエンドポイントを検索して内容を確認するため、すべてのスキーマがモデルのコンテキストに入るのを防げます。

executeはすべての行をすぐに返しますか?

いいえ。タスクを返します。そのタスクを続けて処理し、results.itemsをページ送りで読み取ってください。

エージェントはXに投稿したり、非公開のInstagramアカウントを読んだりできますか?

いいえ。呼び出せるのは、カタログにある公開データの機能だけです。

Skillはいつ追加すればよいですか?

複数ステップのジョブで、エージェントがエンドポイントを選び、クレジットを見積もる必要があるときです。実行は引き続きMCPが行います。詳細は/skillをご覧ください。

実際のクライアント設定はどこでコピーできますか?

/mcpで、スコープを選び、クライアントを選び、コピーして、再接続してください。

マルチプラットフォーム API

公開マルチプラットフォームのURLでワークフローを試す

公開データの入力を送信すると、取得元をたどれるコンテキスト付きの正規化レコードを受け取れます。

マルチプラットフォームのAPIを見る