Un cliente de IA puede hablar de datos sociales sin saber a qué endpoint llamar. Eso es un problema de enrutamiento, no un segundo catálogo. SocQ MCP expone las mismas API de datos públicos que usa REST: una dirección alojada, tres alcances de herramientas y el mismo modelo de tareas asíncronas.
Esta guía muestra cómo conectar Codex, Claude, Cursor y VS Code, elegir un alcance, enviar una recopilación y seguir consultando la misma tarea. Los detalles de la configuración están en la página de MCP. Copie allí la configuración generada en lugar de inventar campos.

Respuesta rápida: conéctese al endpoint HTTP Streamable alojado
https://api.socq.ai/mcp. El descubrimiento funciona sin clave. La recopilación necesita una clave de API de SocQ. El modo compacto recorresocq_search_endpoints→socq_describe_endpoint→socq_executey luego continúa con la tarea devuelta. No trate esa llamada de ejecución como un volcado síncrono de todas las filas.
¿API oficiales de las plataformas o un MCP público?
Los productos oficiales de Instagram, X, YouTube y similares siguen siendo la puerta correcta cuando un usuario autoriza la publicación, la mensajería, los anuncios o las estadísticas privadas. MCP no añade esos permisos.
SocQ MCP es una puerta de datos públicos. Un agente solo puede llamar a funcionalidades que ya existen en el catálogo de API. No puede publicar, no puede leer cuentas privadas y no puede inventar un endpoint que no esté en el registro. REST, MCP y la CLI ejecutan los mismos trabajos. La Agent Skill ayuda a un agente a elegir endpoints y estimar créditos; no es un segundo servicio de datos. Si el producto ya habla HTTP, conserve REST. Si quien opera trabaja en una terminal o en un trabajo de CI, use la CLI. Si quien opera es un agente de IDE, use MCP.
Elija un alcance de herramientas, no un endpoint adivinado
Un cliente MCP solo ve las herramientas que expone la conexión actual. Elija el alcance en /mcp y luego copie la dirección correspondiente.
| Alcance | Dirección | Superficie visible | Mejor opción para |
|---|---|---|---|
| Compacto | /mcp | Herramientas de descubrimiento, ejecución, tareas, archivos y cuenta | Exploración que puede pasar de una plataforma a otra |
| Plataformas | /mcp?platforms=youtube,tiktok | Herramientas de recopilación tipadas para hasta cinco plataformas, más las de tareas, archivos y cuenta | Agentes que trabajan siempre con un conjunto conocido de plataformas |
| Herramientas exactas | /mcp?tools=youtube_comments,x_search | Hasta treinta herramientas tipadas, más las de tareas, archivos y cuenta | Flujos de trabajo estables con una lista de herramientas controlada |
platforms y tools son mutuamente excluyentes. Después de cambiar un filtro, vuelva a conectar el cliente para que actualice tools/list. Una conexión compacta que nunca se reconecta seguirá sirviendo la lista de herramientas anterior.
Aun así, dentro de ese alcance usted elige una funcionalidad concreta del catálogo. El modo compacto busca en el registro. Los modos de plataformas y de herramientas exactas llaman a una herramienta tipada cuyo esquema de entrada coincide con el cuerpo REST de ese recurso.
Una pauta útil:
- Comience en modo compacto cuando la pregunta pueda saltar de los comentarios de YouTube a una búsqueda en X y a una consulta de Shop.
- Cambie al modo de plataformas cuando el agente solo trabaje con dos o tres redes.
- Cambie al modo de herramientas exactas cuando una evaluación de producción deba ver una lista de herramientas congelada.
No mantenga una conexión de cinco plataformas para luego pedirle al modelo que “pruebe también con Amazon”. Vuelva a conectar con Amazon en el filtro, o regrese al modo compacto.
Conectar un cliente y mantener la clave fuera de Git
Haga la configuración en tres pasos, al mismo nivel que la página de MCP:
- Elija compacto, plataformas o herramientas exactas.
- Elija Codex, Claude, Cursor o VS Code.
- Copie la configuración generada y vuelva a conectar.
Archivos de cada cliente y transportes:
| Cliente | Archivo de configuración | Cómo se conecta |
|---|---|---|
| Codex | ~/.codex/config.toml | HTTP remoto a la URL HTTP Streamable alojada |
| Claude | claude_desktop_config.json | Puente stdio @socq/mcp, Node.js 20+ |
| Cursor | .cursor/mcp.json | Puente stdio @socq/mcp |
| VS Code | mcp.json | Puente stdio, con la clave como entrada solicitada |
El descubrimiento de plataformas, endpoints y esquemas no requiere clave. La recopilación, la cuenta, los resultados de las tareas y los archivos sí la requieren. Guarde SOCQ_API_KEY en el entorno o en la entrada protegida que solicita el cliente. No suba la clave a un repositorio.
Un esquema genérico de HTTP Streamable se ve así. Prefiera el archivo que la página de MCP genera para su cliente; no agregue campos no documentados.
{
"mcpServers": {
"socq": {
"url": "https://api.socq.ai/mcp",
"headers": {
"Authorization": "Bearer ${SOCQ_API_KEY}"
}
}
}
}
Codex se comunica directamente con esa URL alojada. Claude, Cursor y VS Code suelen llegar a ella mediante el puente @socq/mcp publicado. Después de guardar, reinicie o vuelva a conectar el servidor de SocQ en el cliente.
REST y MCP comparten una misma funcionalidad
Cada recopilación tiene una ruta REST, un ID de endpoint y un nombre de herramienta tipada. El modo compacto coloca los campos de negocio dentro de input. Las herramientas tipadas exponen ese esquema directamente.
POST /v1/tiktok/profiles
= endpoint id tiktok-profiles
= typed tool tiktok_profiles
La facturación, los límites y el contenedor de la tarea no cambian al cambiar de puerta. Las herramientas de descubrimiento no crean trabajos de recopilación. Si REST rechazaría una lista de nombres de usuario, MCP también la rechazará.
Enviar una recopilación y luego consultar la misma tarea
El modo compacto es un salto de tres herramientas más la continuación de la tarea:
natural-language request
→ socq_search_endpoints
→ socq_describe_endpoint
→ socq_execute(endpoint, input)
→ task_id
→ socq_get_task
→ results.items
socq_execute valida la entrada de negocio y crea una recopilación asíncrona. Puede esperar brevemente y luego devolver el estado actual. Si la tarea sigue en queued o running, continúe con el mismo task_id. Un tiempo de espera agotado del cliente no cancela la recopilación.
Cuando la tarea termina con éxito, lea results.items. Mientras has_more sea true, pase next_cursor sin modificarlo. No vuelva a enviar el mismo perfil de Instagram o nombre de usuario de TikTok solo porque la primera página fue corta.
Los modos de plataformas y de herramientas exactas omiten la búsqueda cuando la herramienta tipada ya está en el contexto. El contrato de la tarea no cambia: se crea una vez, se guarda el ID, se consulta y se pagina.
Ejemplo de intención en modo compacto, no una captura de chat:
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.
El agente debe volver con un ID de tarea y elementos normalizados, no con la afirmación de que “el perfil llegó en un único resultado síncrono de la herramienta”.
Guarde la misma fila operativa que guardaría para REST:
- El ID del endpoint elegido o el nombre de la herramienta tipada.
- La entrada de negocio canónica.
- El ID de la tarea.
- El primer estado observado y el estado terminal.
- El último
next_cursorque consumió.
Si el proceso del agente termina, reanude esa tarea. No deje que un ciclo de reintentos abra cinco trabajos idénticos de perfiles de TikTok.
La depuración de entradas sigue siendo responsabilidad suya
MCP no relaja la validación de REST.
- El
inputcompacto debe coincidir con el esquema del endpoint que devuelvesocq_describe_endpoint. - Las herramientas tipadas exponen los mismos campos obligatorios que
POST /v1/{platform}/{resource}. - Quite el
@o consérvelo de forma consistente. Convierta las URL de perfil en nombres de usuario en el prompt o en un paso previo. - No envíe la URL de un video a un campo de nombre de usuario, ni un nombre de usuario a un campo de URL de estado.
- Mantenga
results_limitcomo un tope. El catálogo no promete que los resultados estén completos. - Si el alcance omitió la plataforma, vuelva a conectar con un filtro de plataformas o de herramientas que la incluya. No le pida al modelo que “llame a TikTok de todos modos”.
Anote el ID del endpoint elegido, las entradas y el ID de la tarea en su propio registro. Los agentes olvidan; su tabla de trabajos no debería.
Lea los campos normalizados, no la prosa del chat
Los elementos exitosos usan el mismo contenedor que REST: id, platform, resource, type, url, author, metrics, created_at, collected_at y extra cuando está presente.
Pídale al agente que conserve los valores null. Un conteo de seguidores oculto no es cero. Una transcripción faltante no significa “sin voz”. Las URL de los medios son referencias de origen.
Si necesita archivos, obténgalos con la herramienta de archivos de esa tarea. Si necesita otra página, conserve el cursor. Si necesita un recurso distinto, describa y ejecute ese recurso; no remodele la primera carga útil para fabricar un segundo esquema falso.
Verificaciones mínimas antes de confiar en una fila que el agente resumió:
platformyresourcecoinciden con la herramienta que se ejecutó.- Existe al menos uno de
idourl. - Las métricas son números o null, nunca ceros forzados.
collected_atestá presente y no se copia encreated_at.- La respuesta en prosa puede rastrearse hasta
results.items, no hasta la memoria del modelo.
Pídale al agente que cite los campos, no que “limpie” los valores faltantes.
Frecuencia de actualización para agentes
Las conexiones MCP y los trabajos de recopilación tienen relojes distintos.
| Objeto | Hábito razonable | Motivo |
|---|---|---|
| Alcance de herramientas | Volver a conectar tras cada cambio de filtro | Los clientes guardan tools/list en caché |
| Descubrimiento | Repetir socq_search_endpoints cuando cambie la pregunta | El catálogo está vivo; el resultado anterior puede ser el recurso equivocado |
| Tarea de recopilación | Consultar el mismo ID | Reenviar duplica el trabajo |
| Entidades tipo perfil | Semanal o mensual | Los campos de identidad cambian lentamente |
| Publicaciones, comentarios, anuncios, productos | De cada hora a diaria mientras estén activos | Las métricas públicas y los listados cambian más rápido |
| Servidores de producción con herramientas exactas | Cambiar las herramientas solo en una versión planificada | Las listas de herramientas inesperadas rompen las evaluaciones |
No actualice una tarea terminada para “hacerla síncrona”. Inicie una tarea nueva solo cuando las entradas o la ventana de tiempo hayan cambiado realmente.
Modos de falla comunes
El agente dice que falta la plataforma
La conexión actual puede no reconocer el modo compacto, estar limitada a otras plataformas o conservar una tools/list antigua. Abra /mcp, defina el alcance, copie la configuración y vuelva a conectar.
La recopilación se rechaza sin un perfil útil
El descubrimiento no necesita clave. La ejecución sí. Revise SOCQ_API_KEY en el entorno o en la entrada solicitada de VS Code.
La primera llamada de herramienta “terminó” sin filas
El trabajo es asíncrono. Lea el estado de la tarea. Continúe con socq_get_task antes de suponer una falla o de reenviar.
El agente inventa una herramienta de publicación o de datos privados
Esa funcionalidad no está en el catálogo. Deténgase. Use un producto oficial con OAuth para las escrituras y las estadísticas privadas.
La paginación se detuvo antes de tiempo
has_more y next_cursor son parte del resultado, no un adorno opcional. Agote el cursor o registre que se detuvo a propósito.
El cambio de filtro no hizo nada
platforms y tools no se pueden combinar. Vuelva a conectar después de cambiar.
Uso responsable
Recopile solo los datos públicos necesarios para un propósito legítimo. No le pida a un agente que eluda cuentas privadas, inicios de sesión o controles de acceso. Mantenga las claves fuera de los prompts que pegará en tickets. Revise los términos de las plataformas y sus propias reglas de retención.
No le pida al agente que:
- Publique, responda ni envíe un mensaje directo.
- Abra una vista privada o con sesión iniciada.
- Trate
socq_executecomo un conjunto de datos terminado. - Combine
platformsytoolsen una misma URL. - Escriba una clave de API real en un archivo de configuración que se vaya a confirmar en el repositorio.
SocQ MCP es una conexión técnica. No otorga derechos adicionales sobre el contenido y no convierte un scraping no oficial en una integración oficial.
Mantenga la misma regla de minimización de datos que usaría en un worker REST: recopile los campos públicos que necesita el ticket y luego deténgase. Un agente con acceso compacto a todo el catálogo seguirá descubriendo con gusto endpoints que usted no pidió. Los alcances restringidos existen por ese motivo.
SocQ MCP: preguntas frecuentes (FAQ)
¿SocQ MCP es una segunda API social?
No. Es otra puerta de entrada al mismo catálogo que usan REST y la CLI.
¿Puedo usarlo sin una clave de API?
Puede descubrir plataformas, endpoints y esquemas. La recopilación, la cuenta, los resultados de las tareas y los archivos necesitan una clave.
¿Por qué el modo compacto no enumera cada API como una herramienta propia?
El modo compacto busca y describe un endpoint cuando hace falta, lo que mantiene fuera del contexto del modelo el conjunto completo de esquemas.
¿La ejecución devuelve todas las filas de inmediato?
No. Devuelve una tarea. Continúe con esa tarea y recorra las páginas de results.items.
¿El agente puede publicar en X o leer una cuenta privada de Instagram?
No. Solo puede llamar a las funcionalidades públicas del catálogo.
¿Cuándo debo agregar la Skill?
Cuando el agente deba elegir endpoints y estimar créditos en un trabajo de varios pasos. MCP sigue ejecutando. Los detalles están en /skill.
¿Dónde copio la configuración real del cliente?
Desde /mcp: elija el alcance, elija el cliente, copie y vuelva a conectar.
MULTIPLATAFORMA API
Probar el flujo de trabajo con una URL pública de Multiplataforma
Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.
Ver las API de Multiplataforma