> ## 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

> Conecte o AI Agent do n8n ao MCP Server da Ayrshare para publicar, agendar e analisar em 13 redes sociais, sem 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 é onde você conecta suas ferramentas. Ayrshare é a única API que publica em Facebook, Instagram, LinkedIn, YouTube, TikTok, Pinterest, Reddit, Threads, Bluesky, Telegram, Google Business Profile, Snapchat e X em uma única chamada. Conecte os dois com o [MCP Server da Ayrshare](/additional/mcp-action-server) e seu AI Agent do n8n consegue rodar todo o ciclo sozinho: rascunhar uma publicação, validá-la contra as regras de cada rede, publicá-la ou agendá-la, e depois ler as análises de volta.

<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="O workflow inicial do n8n no canvas: um chat trigger em um AI Agent, com um modelo de chat Anthropic e o nó da tool MCP da Ayrshare conectado abaixo, além de sticky notes de setup e uso." width="2000" height="1100" data-path="images/packages-guides/n8n-mcp-workflow.webp" />

Como o MCP Server é um endpoint hospedado de Streamable HTTP, você o conecta com o nó **MCP Client Tool** embutido do n8n. Não há nada para hospedar, nenhum código customizado e nenhum nó da comunidade para instalar. Você aponta um nó para uma URL e seu agente ganha todas as 27 tools sociais.

<Card title="Baixe o workflow inicial do n8n" icon="download" href="/files/ayrshare-n8n-mcp-workflow.json" horizontal>
  O workflow mostrado acima, pronto para importar: Chat Trigger, AI Agent, um modelo de chat Anthropic e o nó MCP da Ayrshare pré-conectado com o system prompt de validar-primeiro.
</Card>

Para usá-lo: no n8n, **Workflows → Import from file**, selecione o JSON e crie as duas credenciais que ele espera (uma credencial **Bearer Auth** com sua chave da Ayrshare e uma credencial **Anthropic API**). Os dois badges de aviso somem uma vez que as credenciais estejam anexadas. Instâncias auto-hospedadas precisam de acesso de saída a `api.ayrshare.com` e ao seu provedor de modelo.

Este guia cobre o caminho MCP-first de ponta a ponta. Se preferir montar um workflow fixo, sem agente, há um curto [fallback REST](#rest-fallback-no-agent) no final.

## Por que MCP em vez de escrever chamadas de API

Você pode chamar a REST API da Ayrshare diretamente de um nó HTTP Request, o que é ok para workflows fixos e previsíveis. O MCP Server ganha seu lugar quando um LLM está no ciclo:

<ul class="custom-bullets">
  <li>**O agente escolhe a tool.** Descreva o objetivo ("publique isso nos nossos canais empresariais e agende o follow-up para terça") e o agente escolhe `validate_post`, `create_post` e os parâmetros certos por conta própria.</li>
  <li>**Validação antes de qualquer coisa ir ao ar.** `validate_post` faz um dry-run do seu conteúdo contra as regras de tamanho, formato e mídia de cada plataforma, para que o agente não envie uma publicação que a rede vai rejeitar.</li>
  <li>**Uma chamada, várias redes.** Um único `create_post` se ramifica para todas as plataformas vinculadas.</li>
  <li>**Mudanças de plataforma são problema da Ayrshare.** Quando uma rede muda sua API, a Ayrshare mantém a integração e seu workflow continua funcionando.</li>
  <li>**Mesmas regras da REST API.** Toda chamada de tool MCP roda in-process pela mesma cadeia de API da Ayrshare: mesma autenticação, limites de taxa, cota e validação. Não há comportamento separado para aprender.</li>
</ul>

## Como se conecta

O nó **AI Agent** é o cérebro. O sub-nó **MCP Client Tool** se conecta a ele, liga ao MCP Server da Ayrshare em `https://api.ayrshare.com/mcp`, descobre as tools disponíveis e as expõe ao agente. Quando o agente age, o nó despacha a chamada para a Ayrshare, que publica nas redes.

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

Para detalhes de endpoint, transporte e autenticação, veja [Conectar e Configurar](/additional/mcp-action-connect). Para a lista completa de tools, veja o [Catálogo de Tools](/additional/mcp-action-tools).

## Pré-requisitos

<ul class="custom-bullets">
  <li>Uma **instância do n8n** (Cloud ou auto-hospedada) em uma versão recente com os nós AI Agent e MCP Client Tool. O nó MCP Client Tool é embutido. Você não precisa de um nó da comunidade, porque o servidor da Ayrshare fala Streamable HTTP.</li>
  <li>Uma **conta Ayrshare e uma API Key** (Dashboard → Settings → API Key), ou comece um [teste grátis](https://billing.ayrshare.com/b/9B6bJ15Oidr9fz615u1Nu0h).</li>
  <li>**Pelo menos uma conta social vinculada** na Ayrshare. O agente só pode publicar onde você conectou.</li>
  <li>Uma **credencial de modelo de chat** para o nó AI Agent (Anthropic, OpenAI, etc.).</li>
  <li>*(Opcional)* Um **Business Plan ou Enterprise Plan** se você for gerenciar múltiplos clientes via sub-profiles.</li>
</ul>

## Configure o nó MCP Client Tool

<Steps>
  <Step title="Adicione um nó AI Agent">
    Abra ou crie um workflow e adicione um nó **AI Agent** (na categoria *Advanced AI*).
  </Step>

  <Step title="Anexe o nó MCP Client Tool">
    No nó AI Agent, clique no conector **Tool** e adicione um nó **MCP Client Tool**. Configure-o:

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

  <Step title="Adicione sua chave da Ayrshare como credencial Bearer">
    Em **Credential**, crie uma nova credencial **Bearer Auth** e cole sua API Key da Ayrshare como o token. O n8n a envia como `Authorization: Bearer YOUR_API_KEY`. Ao salvar, o n8n se conecta e lista as 27 tools.
  </Step>

  <Step title="Conecte o modelo de chat e o system prompt">
    Anexe um sub-nó **Chat Model** e selecione sua credencial de modelo. Dê ao agente um system prompt que estabeleça as regras, por exemplo:

    > Você é um assistente de redes sociais com acesso às tools da Ayrshare. Antes de publicar qualquer coisa, sempre chame `validate_post` primeiro e relate quaisquer problemas. Só chame `create_post` após a validação passar. Use por padrão as plataformas que o usuário nomeou; se nenhuma for nomeada, pergunte. Nunca invente URLs de mídia; use apenas URLs que o usuário forneça e confirme-as com `validate_media` em caso de dúvida.
  </Step>

  <Step title="Adicione um trigger">
    Para testes, o **Manual Trigger** ou **Chat Trigger** é o mais fácil. Para produção, use o que dispara seu workflow (schedule, webhook, form, nova linha em uma planilha).
  </Step>
</Steps>

<Note>
  **Use HTTP Streamable, não SSE.** O MCP Server da Ayrshare usa o transporte moderno Streamable HTTP e é stateless. A opção SSE do n8n está obsoleta e o servidor rejeita o stream SSE. Sempre escolha **HTTP Streamable**.
</Note>

## A superfície de tools

Seu agente vê todas as 27 tools através do único nó MCP. Você raramente as chama pelo nome; descreve a intenção e o agente seleciona. Os domínios são Publicações, Histórico, Análises, Comentários, Mensagens, Profiles, Mídia, Geração, Webhooks e Erros. Para a lista completa com o propósito e escopo de cada tool, veja o [Catálogo de Tools](/additional/mcp-action-tools).

Duas se destacam pela segurança: **`validate_post`** faz o dry-run de uma publicação com a mesma entrada de `create_post`, mas não publica nada, e **`explain_error`** transforma qualquer código de erro da Ayrshare em uma causa e correção em linguagem simples, para que o agente possa se auto-diagnosticar.

## Exemplo 1: rascunhar, validar e publicar a partir de uma mensagem de chat

O "hello world" desta integração. Dispare o workflow com uma mensagem de chat ou form e deixe o agente fazer o resto.

<ul class="custom-bullets">
  <li>**Trigger:** Chat Trigger (ou um Form Trigger com um campo "o que devemos publicar?").</li>
  <li>**Prompt para o agente:** *"Escreva um anúncio de lançamento amigável para nosso novo painel de análises e publique-o no LinkedIn, Facebook e Instagram. Valide primeiro."*</li>
</ul>

O que o agente faz por conta própria: ele chama `validate_post` com seu texto e as três plataformas; se o Instagram sinalizar uma imagem faltando, ele te avisa em vez de falhar silenciosamente; assim que a validação passa, ele chama `create_post` e retorna as URLs das publicações ao vivo. Como a validação roda primeiro, você descobre um problema antes de qualquer coisa ficar pública.

## Exemplo 2: publique automaticamente novo conteúdo em seus canais

Transforme uma fonte de conteúdo em publicações multi-redes sem tocá-la.

<ul class="custom-bullets">
  <li>**Trigger:** nó RSS Read no feed do seu blog, um webhook do seu CMS ou uma nova linha no Google Sheets ou Airtable.</li>
  <li>**Passo do AI Agent:** *"Resuma este artigo em uma publicação social curta com 2 a 3 hashtags relevantes, então valide e publique no LinkedIn, Facebook e Threads."*</li>
  <li>Opcionalmente, adicione uma [aprovação com humano no loop](#keep-a-human-in-the-loop) antes do passo `create_post` para que uma pessoa aprove.</li>
</ul>

Você pode se apoiar em `recommend_hashtags` para tags baseadas em dados e em `generate_post` se quiser que a Ayrshare rascunhe o texto em vez do seu modelo de chat.

## Exemplo 3: relatório semanal de análises

Rode o ciclo ao contrário: leia o desempenho e relate.

<ul class="custom-bullets">
  <li>**Trigger:** nó Schedule, por exemplo toda segunda-feira às 8h.</li>
  <li>**Passo do AI Agent:** *"Puxe as análises da conta na última semana para LinkedIn, Instagram e Facebook, e resuma as 3 publicações principais por engajamento."*</li>
  <li>O agente usa `get_social_network_analytics` para números no nível da conta e `get_post_analytics` para publicações individuais, depois você direciona o resumo dele para um nó **Slack**, **Gmail** ou **Notion**.</li>
</ul>

Uma nota sobre cadência: a maioria das publicações recebe a maior parte do engajamento nas primeiras 24 horas, e as métricas não são atualizadas segundo a segundo. Um agendamento diário ou semanal é suficiente. Não faça polling de análises a cada poucos minutos — você vai bater em limites de taxa sem novo dado.

## Agindo em nome de clientes (multi-tenant)

Se você gerencia redes sociais para múltiplos clientes, os profiles da Ayrshare permitem que uma conta publique em muitos conjuntos separados de contas vinculadas. Em um Business Plan ou Enterprise Plan, você tem duas formas de direcionar a um cliente pelo n8n:

<ul class="custom-bullets">
  <li>**Por conexão:** adicione um header `Profile-Key` ao nó MCP Client Tool (use a autenticação **Multiple Headers** para poder enviar `Authorization` e `Profile-Key`). Toda chamada nesse nó então age como esse cliente. Bom quando um workflow atende um cliente.</li>
  <li>**Por chamada:** muitas tools aceitam um argumento `profileKey`, que o agente pode definir por ação. Quando ambos estão presentes, o [argumento por chamada vence](/additional/mcp-action-connect#precedence-argument-wins-over-header). Bom quando um workflow roteia entre clientes.</li>
</ul>

Para fazer onboarding de um novo cliente, o agente pode chamar `create_profile` e depois `generate_jwt_social_linking_url` para gerar uma página hospedada onde o cliente vincula suas próprias contas. Nenhuma credencial passa pelo seu workflow.

## Publicando no X/Twitter

<XByoNotice />

No n8n, mude a **Authentication** do nó MCP Client Tool para **Multiple Headers** e adicione os dois headers `X-Twitter-OAuth1-*` junto com `Authorization`. É uma configuração única por conta Ayrshare, e o mesmo par de chaves se aplica a todos os profiles. Para todo o resto (Facebook, Instagram, LinkedIn, YouTube, TikTok e as demais) nenhum header extra é necessário. Veja [Conectar e Configurar → Credenciais BYO do X/Twitter](/additional/mcp-action-connect#xtwitter-byo-credentials).

## Mantenha um humano no loop

As tools MCP tornam trivial para um agente publicar, e é exatamente por isso que você deve criar uma barreira. Duas salvaguardas baratas:

<ul class="custom-bullets">
  <li>**Sempre valide primeiro.** Coloque "chamar `validate_post` antes de `create_post`" no system prompt. A validação não publica nada e captura violações de regras de plataforma cedo.</li>
  <li>**Adicione um passo de aprovação.** Insira o nó **Send and Wait for Response** do n8n (Slack ou e-mail) entre o rascunho e a ação de publicar, para que uma pessoa aprove antes de qualquer coisa ir ao ar. Para conteúdo agendado, o agente pode usar `update_post` para revisar uma publicação aguardando aprovação.</li>
</ul>

## Fallback REST (sem agente)

Se você quer um workflow fixo, determinístico, sem LLM, pule o MCP e chame a REST API com um nó **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"
}
```

Use o host da API `api.ayrshare.com`, não o host do painel `app.ayrshare.com`. (`app.ayrshare.com` aceita chamadas de API, mas não é o endpoint documentado e pode retornar [erros de gateway 502/504](/help-center/technical-support/response_bad_gateway_502_or_504_error) intermitentes, então sempre use `api.ayrshare.com`.) O mesmo padrão funciona para os outros [endpoints REST](/apis/overview). Esta é a ferramenta certa quando o workflow é totalmente previsível e você não precisa de um agente decidindo nada.

## Solução de problemas

| Sintoma                                                           | Causa provável                                                      | Correção                                                                                                                              |
| ----------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Chamada de tool retorna `403` / código `102`, "API Key not valid" | API Key ruim ou faltando                                            | Verifique se a credencial Bearer Auth contém sua chave da Ayrshare exata. Salve o nó novamente após alterá-la.                        |
| n8n não consegue conectar ao MCP Server                           | Transporte ou endpoint errado                                       | O endpoint deve ser `https://api.ayrshare.com/mcp`; o transporte deve ser **HTTP Streamable**, não SSE.                               |
| Publicação no X/Twitter falha com erro `419`                      | Credenciais BYO do X faltando                                       | Adicione os dois headers `X-Twitter-OAuth1-*` via autenticação Multiple Headers.                                                      |
| Publicação falha em apenas uma plataforma                         | Essa rede não está vinculada, ou um campo obrigatório está faltando | Vincule-a no painel; adicione `title` para YouTube, `title` + `subreddit` para Reddit, `mediaUrls` para Instagram.                    |
| Publicação do Instagram rejeitada                                 | Sem mídia                                                           | O Instagram exige `mediaUrls` para a maioria dos tipos de publicação. Peça ao agente que confirme com `validate_media`.               |
| Mídia anexada como arquivo ou binário não aparece                 | MCP é somente JSON                                                  | Referencie mídia por URL pública `mediaUrls`; o caminho MCP não aceita uploads de arquivo. Confirme a URL com `validate_media`.       |
| As chamadas funcionam, mas agem no cliente errado                 | Direcionamento de profile                                           | Defina um header `Profile-Key` (por conexão) ou argumento `profileKey` (por chamada); o argumento vence se ambos estiverem definidos. |
| `429 Too Many Requests`                                           | Polling frequente demais                                            | Reduza a frequência de polling de análises e comentários; as métricas não são atualizadas segundo a segundo.                          |
| Mudança de configuração não teve efeito                           | A conexão MCP é inicializada no início da sessão                    | Salve o nó novamente ou reinicie o workflow após alterar a chave ou headers.                                                          |

Você também pode expor a tool `explain_error` ao agente para que ele decodifique qualquer código de erro da Ayrshare em causa e correção por conta própria.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Conectar e Configurar" icon="plug" href="/additional/mcp-action-connect" horizontal>
    Endpoint, transporte, autenticação, direcionamento de profile e credenciais BYO.
  </Card>

  <Card title="Catálogo de Tools" icon="list" href="/additional/mcp-action-tools" horizontal>
    As 27 tools agrupadas por domínio, com escopo e propósito.
  </Card>

  <Card title="MCP Server" icon="server" href="/additional/mcp-action-server" horizontal>
    O que é o MCP Server e como ele mapeia para a API da Ayrshare.
  </Card>

  <Card title="Plugin do Claude Code" icon="terminal" href="/additional/mcp-claude-code-plugin" horizontal>
    O mesmo servidor, empacotado para Claude Code.
  </Card>
</CardGroup>