> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n

> Conecta el AI Agent de n8n al MCP Server de Ayrshare para publicar, programar y analizar en 13 redes sociales, sin escribir código específico por plataforma.

export const XByoNotice = () => <Info>
  <strong>Targeting X/Twitter?</strong> Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
  <br /><br />
  <code>X-Twitter-OAuth1-Api-Key</code> — Your API Key (Consumer Key)<br />
  <code>X-Twitter-OAuth1-Api-Secret</code> — Your API Key Secret (Consumer Secret)
  <br /><br />
  <strong>One-time setup per Ayrshare account.</strong> You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do <em>not</em> create a new app per customer.
  <br /><br />
  Not linked yet? See the <a href="/dashboard/connect-social-accounts/x-twitter-byo-keys">full setup guide</a> to connect your X account.
  <br /><br />
  Your keys are never logged or stored by Ayrshare.
</Info>;

n8n es donde conectas tus herramientas. Ayrshare es la única API que publica en Facebook, Instagram, LinkedIn, YouTube, TikTok, Pinterest, Reddit, Threads, Bluesky, Telegram, Google Business Profile, Snapchat y X en una sola llamada. Conéctalos con el [MCP Server de Ayrshare](/additional/mcp-action-server) y tu AI Agent de n8n podrá ejecutar todo el ciclo por sí solo: redactar un post, validarlo contra las reglas de cada red, publicarlo o programarlo, y luego leer las analíticas.

<img class="center" src="https://mintcdn.com/ayrshare-docs/bAaTGuhaX8NvaXu8/images/packages-guides/n8n-mcp-workflow.webp?fit=max&auto=format&n=bAaTGuhaX8NvaXu8&q=85&s=a04e6040568f404db97046feb0066c53" alt="The n8n starter workflow on the canvas: a chat trigger into an AI Agent, with an Anthropic chat model and the Ayrshare MCP tool node attached below, plus setup and usage sticky notes." width="2000" height="1100" data-path="images/packages-guides/n8n-mcp-workflow.webp" />

Como el MCP Server es un endpoint alojado con Streamable HTTP, lo conectas con el nodo **MCP Client Tool** que trae n8n. No hay nada que alojar, ni código personalizado, ni un nodo de la comunidad que instalar. Apuntas un nodo a una URL y tu agente obtiene las 27 herramientas sociales.

<Card title="Descargar el workflow de inicio para n8n" icon="download" href="/files/ayrshare-n8n-mcp-workflow.json" horizontal>
  El workflow mostrado arriba, listo para importar: Chat Trigger, AI Agent, un modelo de chat de Anthropic y el nodo MCP de Ayrshare precableado con el system prompt de validar primero.
</Card>

Para usarlo: en n8n, **Workflows → Import from file**, selecciona el JSON y crea las dos credenciales que espera (una credencial **Bearer Auth** con tu clave de Ayrshare y una credencial **Anthropic API**). Las dos etiquetas de advertencia desaparecen cuando las credenciales quedan conectadas. Las instancias autoalojadas necesitan acceso saliente a `api.ayrshare.com` y a tu proveedor del modelo.

Esta guía cubre la ruta MCP-first de principio a fin. Si prefieres construir un flujo de trabajo fijo, sin agente, hay un breve [fallback REST](#rest-fallback-no-agent) al final.

## Por qué MCP en lugar de escribir llamadas a la API

Puedes llamar a la REST API de Ayrshare directamente desde un nodo HTTP Request, lo cual está bien para workflows fijos y predecibles. El MCP Server destaca cuando hay un LLM en el bucle:

<ul class="custom-bullets">
  <li>**El agente elige la herramienta.** Describe el objetivo ("publica esto en nuestros canales de negocio y programa el follow-up para el martes") y el agente elige por sí solo `validate_post`, `create_post` y los parámetros correctos.</li>
  <li>**Validación antes de que algo se publique.** `validate_post` simula tu contenido contra las reglas de longitud, formato y medios de cada plataforma, así el agente no envía un post que una red vaya a rechazar.</li>
  <li>**Una llamada, muchas redes.** Un único `create_post` se distribuye a todas las plataformas vinculadas.</li>
  <li>**Los cambios de plataforma son problema de Ayrshare.** Cuando una red cambia su API, Ayrshare mantiene la integración y tu workflow sigue funcionando.</li>
  <li>**Las mismas reglas que la REST API.** Cada llamada de herramienta MCP corre en proceso a través de la misma cadena de la API de Ayrshare: misma autenticación, rate limits, cuota y validación. No hay un comportamiento aparte que aprender.</li>
</ul>

## Cómo se conecta

El nodo **AI Agent** es el cerebro. El sub-nodo **MCP Client Tool** se conecta a él, se comunica con el MCP Server de Ayrshare en `https://api.ayrshare.com/mcp`, descubre las herramientas disponibles y las expone al agente. Cuando el agente actúa, el nodo despacha la llamada a Ayrshare, que publica en las redes.

```
Trigger  ->  AI Agent (+ Chat Model)  ->  MCP Client Tool  ->  Ayrshare MCP Server  ->  13 networks
```

Para los detalles de endpoint, transporte y autenticación, consulta [Conexión y configuración](/additional/mcp-action-connect). Para la lista completa de herramientas, consulta el [Catálogo de herramientas](/additional/mcp-action-tools).

## Requisitos previos

<ul class="custom-bullets">
  <li>Una **instancia de n8n** (Cloud o autoalojada) en una versión reciente con los nodos AI Agent y MCP Client Tool. El nodo MCP Client Tool viene incorporado. No necesitas un nodo de la comunidad, porque el servidor de Ayrshare habla Streamable HTTP.</li>
  <li>Una **cuenta de Ayrshare y una API key** (Dashboard → Settings → API Key), o inicia una [prueba gratuita](https://billing.ayrshare.com/b/9B6bJ15Oidr9fz615u1Nu0h).</li>
  <li>**Al menos una cuenta social vinculada** en Ayrshare. El agente solo puede publicar donde tú hayas conectado.</li>
  <li>Una **credencial de chat model** para el nodo AI Agent (Anthropic, OpenAI, etc.).</li>
  <li>*(Opcional)* Un **plan Business o Enterprise** si vas a gestionar varios clientes con sub-perfiles.</li>
</ul>

## Configura el nodo MCP Client Tool

<Steps>
  <Step title="Añade un nodo AI Agent">
    Abre o crea un workflow y añade un nodo **AI Agent** (bajo los nodos *Advanced AI*).
  </Step>

  <Step title="Adjunta el nodo MCP Client Tool">
    En el nodo AI Agent, haz clic en el conector **Tool** y añade un nodo **MCP Client Tool**. Configúralo:

    | Campo                | Valor                                                           |
    | -------------------- | --------------------------------------------------------------- |
    | **Endpoint**         | `https://api.ayrshare.com/mcp`                                  |
    | **Server Transport** | `HTTP Streamable`                                               |
    | **Authentication**   | `Bearer Auth`                                                   |
    | **Tools to Include** | `All` (o `Selected` para exponer solo herramientas específicas) |
  </Step>

  <Step title="Añade tu clave de Ayrshare como credencial Bearer">
    En **Credential**, crea una nueva credencial **Bearer Auth** y pega tu API key de Ayrshare como token. n8n la envía como `Authorization: Bearer YOUR_API_KEY`. Al guardar, n8n se conecta y lista las 27 herramientas.
  </Step>

  <Step title="Conecta el chat model y el system prompt">
    Adjunta un sub-nodo **Chat Model** y selecciona tu credencial de modelo. Dale al agente un system prompt que establezca las reglas, por ejemplo:

    > Eres un asistente de redes sociales con acceso a las herramientas de Ayrshare. Antes de publicar cualquier cosa, llama siempre a `validate_post` primero y reporta cualquier problema. Solo llama a `create_post` después de que la validación pase. Usa por defecto las plataformas que nombre el usuario; si no nombra ninguna, pregunta. Nunca inventes URLs de medios; usa solo URLs que el usuario proporcione y confírmalas con `validate_media` en caso de duda.
  </Step>

  <Step title="Añade un trigger">
    Para probar, el **Manual Trigger** o el **Chat Trigger** son los más fáciles. Para producción, usa lo que dispare el workflow (schedule, webhook, formulario, nueva fila en una hoja).
  </Step>
</Steps>

<Note>
  **Usa HTTP Streamable, no SSE.** El MCP Server de Ayrshare usa el moderno transporte Streamable HTTP y es stateless. La opción SSE de n8n está obsoleta y el servidor rechaza el flujo SSE. Elige siempre **HTTP Streamable**.
</Note>

## La superficie de herramientas

Tu agente ve las 27 herramientas a través del único nodo MCP. Rara vez las llamas por nombre; describes la intención y el agente elige. Los dominios son Posts, History, Analytics, Comments, Messages, Profiles, Media, Generate, Webhooks y Errors. Para la lista completa con el propósito y alcance de cada herramienta, consulta el [Catálogo de herramientas](/additional/mcp-action-tools).

Dos destacan por seguridad: **`validate_post`** simula un post con la misma entrada que `create_post` pero no publica nada, y **`explain_error`** convierte cualquier código de error de Ayrshare en una causa y solución en lenguaje claro, para que el agente pueda autodiagnosticarse.

## Ejemplo 1: redactar, validar y publicar desde un mensaje de chat

El "hola mundo" de esta integración. Dispara el workflow con un mensaje de chat o un formulario, y deja que el agente haga el resto.

<ul class="custom-bullets">
  <li>**Trigger:** Chat Trigger (o un Form Trigger con un campo "¿qué debemos publicar?").</li>
  <li>**Prompt al agente:** *"Escribe un anuncio de lanzamiento amistoso para nuestro nuevo dashboard de analíticas y publícalo en LinkedIn, Facebook e Instagram. Valida primero."*</li>
</ul>

Lo que hace el agente por sí solo: llama a `validate_post` con tu copy y las tres plataformas; si Instagram marca que falta una imagen te lo dice en lugar de fallar en silencio; una vez que la validación pasa, llama a `create_post` y devuelve las URLs de los posts en vivo. Como la validación corre primero, te enteras del problema antes de que nada sea público.

## Ejemplo 2: publicar automáticamente contenido nuevo en tus canales

Convierte una fuente de contenido en publicaciones multi-red sin tocarla.

<ul class="custom-bullets">
  <li>**Trigger:** un nodo RSS Read sobre el feed de tu blog, un webhook de tu CMS o una fila nueva en Google Sheets o Airtable.</li>
  <li>**Paso del AI Agent:** *"Resume este artículo en un post social corto con 2 o 3 hashtags relevantes, luego valida y publica en LinkedIn, Facebook y Threads."*</li>
  <li>Opcionalmente, añade una aprobación con [humano en el bucle](#keep-a-human-in-the-loop) antes del paso `create_post` para que una persona dé el visto bueno.</li>
</ul>

Puedes apoyarte en `recommend_hashtags` para tags basados en datos y en `generate_post` si quieres que Ayrshare redacte el copy en lugar de tu chat model.

## Ejemplo 3: resumen semanal de analíticas

Ejecuta el ciclo al revés: lee el rendimiento y repórtalo.

<ul class="custom-bullets">
  <li>**Trigger:** nodo Schedule, por ejemplo cada lunes a las 8am.</li>
  <li>**Paso del AI Agent:** *"Extrae las analíticas de la cuenta de la semana pasada para LinkedIn, Instagram y Facebook, y resume los 3 mejores posts por engagement."*</li>
  <li>El agente usa `get_social_network_analytics` para los números a nivel de cuenta y `get_post_analytics` para posts individuales, y luego canalizas su resumen a un nodo de **Slack**, **Gmail** o **Notion**.</li>
</ul>

Una nota sobre la cadencia: la mayoría de los posts obtiene el grueso de su engagement en las primeras 24 horas, y las métricas no se actualizan al segundo. Un schedule diario o semanal es más que suficiente. No consultes analíticas cada pocos minutos o llegarás a los rate limits sin datos nuevos.

## Actuar en nombre de clientes (multi-tenant)

Si gestionas redes sociales para varios clientes, los perfiles de Ayrshare permiten que una sola cuenta publique en muchos conjuntos separados de cuentas vinculadas. En un plan Business o Enterprise tienes dos formas de apuntar a un cliente desde n8n:

<ul class="custom-bullets">
  <li>**Por conexión:** añade una cabecera `Profile-Key` al nodo MCP Client Tool (usa la autenticación **Multiple Headers** para poder enviar tanto `Authorization` como `Profile-Key`). Cada llamada en ese nodo actúa entonces como ese cliente. Ideal cuando un workflow atiende a un solo cliente.</li>
  <li>**Por llamada:** muchas herramientas aceptan un argumento `profileKey` que el agente puede fijar por acción. Cuando ambos están presentes, el [argumento por llamada gana](/additional/mcp-action-connect#precedence-argument-wins-over-header). Ideal cuando un workflow se enruta entre clientes.</li>
</ul>

Para incorporar un cliente nuevo, el agente puede llamar a `create_profile` y luego a `generate_jwt_social_linking_url` para generar una página alojada donde el cliente vincula sus propias cuentas. Ninguna credencial pasa por tu workflow.

## Publicar en X/Twitter

<XByoNotice />

En n8n, cambia la **Authentication** del nodo MCP Client Tool a **Multiple Headers** y añade las dos cabeceras `X-Twitter-OAuth1-*` junto con `Authorization`. Es una configuración única por cuenta de Ayrshare, y el mismo par de claves aplica a cada perfil. Para todo lo demás (Facebook, Instagram, LinkedIn, YouTube, TikTok y el resto) no hacen falta cabeceras adicionales. Consulta [Conexión y configuración → Credenciales BYO de X/Twitter](/additional/mcp-action-connect#xtwitter-byo-credentials).

## Mantén a un humano en el bucle

Las herramientas MCP hacen trivial que un agente publique, y por eso mismo deberías controlarlo. Dos salvaguardas simples:

<ul class="custom-bullets">
  <li>**Valida siempre primero.** Incluye "llama a `validate_post` antes de `create_post`" en el system prompt. La validación no publica nada y detecta pronto las violaciones de reglas de plataforma.</li>
  <li>**Añade un paso de aprobación.** Inserta el nodo **Send and Wait for Response** de n8n (Slack o email) entre el borrador y la acción de publicación para que una persona apruebe antes de que algo se publique. Para contenido programado, el agente puede usar `update_post` para revisar un post pendiente de aprobación.</li>
</ul>

## Fallback REST (sin agente)

Si quieres un workflow fijo y determinista, sin LLM, salta MCP y llama a la REST API con un nodo **HTTP Request**:

<ul class="custom-bullets">
  <li>**Método:** `POST`</li>
  <li>**URL:** `https://api.ayrshare.com/api/post`</li>
  <li>**Authentication:** Header Auth, `Authorization: Bearer YOUR_API_KEY`</li>
</ul>

```json theme={"system"}
{
  "post": "Excited to announce our new feature!",
  "platforms": ["facebook", "linkedin", "instagram"],
  "mediaUrls": ["https://example.com/image.jpg"],
  "scheduleDate": "2026-07-01T10:00:00Z"
}
```

Usa el host de la API `api.ayrshare.com`, no el host del dashboard `app.ayrshare.com`. (`app.ayrshare.com` aceptará llamadas de API, pero no es el endpoint documentado y puede devolver [errores 502/504 gateway](/help-center/technical-support/response_bad_gateway_502_or_504_error) intermitentes, así que usa siempre `api.ayrshare.com`.) El mismo patrón funciona para los demás [endpoints REST](/apis/overview). Esta es la herramienta correcta cuando el workflow es totalmente predecible y no necesitas que un agente decida nada.

## Solución de problemas

| Síntoma                                                                       | Causa probable                                          | Solución                                                                                                                                     |
| ----------------------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Una llamada de herramienta devuelve `403` / código `102`, "API Key not valid" | API key errónea o faltante                              | Verifica que la credencial Bearer Auth contenga exactamente tu clave de Ayrshare. Vuelve a guardar el nodo después de cambiarla.             |
| n8n no puede conectar con el MCP server                                       | Transporte o endpoint incorrectos                       | El endpoint debe ser `https://api.ayrshare.com/mcp`; el transporte debe ser **HTTP Streamable**, no SSE.                                     |
| El post en X/Twitter falla con el error `419`                                 | Faltan credenciales BYO de X                            | Añade las dos cabeceras `X-Twitter-OAuth1-*` mediante autenticación Multiple Headers.                                                        |
| El post falla solo en una plataforma                                          | Esa red no está vinculada, o falta un campo obligatorio | Vincúlala en el dashboard; añade `title` para YouTube, `title` + `subreddit` para Reddit, `mediaUrls` para Instagram.                        |
| Post de Instagram rechazado                                                   | Sin medios                                              | Instagram requiere `mediaUrls` para la mayoría de los tipos de post. Haz que el agente confirme con `validate_media`.                        |
| El medio adjuntado como archivo o binario no aparece                          | MCP es solo JSON                                        | Referencia los medios mediante `mediaUrls` con URL pública; la ruta MCP no acepta subidas de archivos. Confirma la URL con `validate_media`. |
| Las llamadas funcionan pero actúan sobre el cliente equivocado                | Direccionamiento de perfil                              | Define una cabecera `Profile-Key` (por conexión) o el argumento `profileKey` (por llamada); el argumento gana si ambos están definidos.      |
| `429 Too Many Requests`                                                       | Consultas demasiado frecuentes                          | Reduce la frecuencia de consulta de analíticas y comentarios; las métricas no se actualizan al segundo.                                      |
| El cambio de configuración no surte efecto                                    | La conexión MCP se inicializa al inicio de sesión       | Vuelve a guardar el nodo o reinicia el workflow después de cambiar la clave o las cabeceras.                                                 |

También puedes exponer la herramienta `explain_error` al agente para que decodifique cualquier código de error de Ayrshare en causa y solución por sí solo.

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Conexión y configuración" icon="plug" href="/additional/mcp-action-connect" horizontal>
    Endpoint, transporte, autenticación, direccionamiento de perfil y credenciales BYO.
  </Card>

  <Card title="Catálogo de herramientas" icon="list" href="/additional/mcp-action-tools" horizontal>
    Las 27 herramientas agrupadas por dominio, con alcance y propósito.
  </Card>

  <Card title="MCP Server" icon="server" href="/additional/mcp-action-server" horizontal>
    Qué es el MCP Server y cómo se corresponde con la API de Ayrshare.
  </Card>

  <Card title="Plugin de Claude Code" icon="terminal" href="/additional/mcp-claude-code-plugin" horizontal>
    El mismo servidor, empaquetado para Claude Code.
  </Card>
</CardGroup>