Skip to main content

​
MCP quickstart

Use SocQ MCP to call social-data collection APIs from Claude, Cursor, Codex, VS Code, or another MCP-compatible client. You describe the data you need; the client selects a SocQ tool, submits the collection, and reads the result.
You normally do not send MCP JSON-RPC requests yourself. Configure the server once, then ask your AI client in natural language.

​
Before you start

You need:
  • a SocQ API key;
  • an MCP-compatible client;
  • Node.js 20 or later only when using the stdio bridge.
Store the key in SOCQ_API_KEY rather than putting it in a URL or committed configuration. See Integration authentication.

​
Connect SocQ

Choose the transport supported by your client: Use the client-specific setup guide:

​
Complete your first collection

The following example collects YouTube comments and shows the complete asynchronous flow.
1

Ask for the data

Send this prompt after SocQ is connected:
2

The client submits the collection

On the default MCP URL, the client calls socq_execute:
endpoint is the REST resource path without /v1/. The REST JSON request body goes inside input.
3

SocQ returns a task ID

Every collection is asynchronous. A successful submission returns a task such as:
A task_id means the collection was accepted; it does not mean the final records are ready.
4

The client checks the task

If the task is still queued or running, the client calls socq_get_task with the same ID:
Keep checking the existing task instead of submitting the collection again.
5

Read the collected records

When status is succeeded, normalized records are available in results.items:
When has_more is true, pass next_cursor unchanged to the next socq_get_task call.

​
How REST APIs map to MCP

Every collection capability has one stable endpoint ID and one typed MCP tool name: The input fields stay the same across REST, typed MCP, and CLI. Compact MCP wraps those fields inside input.
Each API reference page includes its endpoint ID, typed tool name, and a ready-to-use MCP example.

​
Choose a tool mode

The default URL exposes seven compact discovery and execution tools. If you already know the platform or exact endpoints, use a filtered URL to expose typed tools with their full input schemas. See Choose MCP tools for the complete comparison and filtering limits.

​
Compact tool reference

The default MCP URL exposes:
  • socq_list_platforms — list available platforms;
  • socq_search_endpoints — find capabilities by platform, query, or tag;
  • socq_describe_endpoint — read an endpoint’s input schema, price, and docs;
  • socq_execute — submit a collection using its endpoint ID;
  • socq_get_task — read status and normalized result pages;
  • socq_get_files — retrieve raw result files;
  • socq_account — inspect authentication, credits, and limits.
For longer jobs, files, and pagination, continue with Asynchronous tasks and Pagination and files.