Baixe o workflow inicial do n8n
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.
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 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:- 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_poste os parâmetros certos por conta própria. - Validação antes de qualquer coisa ir ao ar.
validate_postfaz 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. - Uma chamada, várias redes. Um único
create_postse ramifica para todas as plataformas vinculadas. - 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.
- 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.
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 emhttps://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.
Pré-requisitos
- 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.
- Uma conta Ayrshare e uma API Key (Dashboard → Settings → API Key), ou comece um teste grátis.
- Pelo menos uma conta social vinculada na Ayrshare. O agente só pode publicar onde você conectou.
- Uma credencial de modelo de chat para o nó AI Agent (Anthropic, OpenAI, etc.).
- (Opcional) Um Business Plan ou Enterprise Plan se você for gerenciar múltiplos clientes via sub-profiles.
Configure o nó MCP Client Tool
Adicione um nó AI Agent
Abra ou crie um workflow e adicione um nó AI Agent (na categoria Advanced AI).
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) |
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.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 chamevalidate_postprimeiro e relate quaisquer problemas. Só chamecreate_postapó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 comvalidate_mediaem caso de dúvida.
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.
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. 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.- Trigger: Chat Trigger (ou um Form Trigger com um campo “o que devemos publicar?”).
- 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.”
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.- Trigger: nó RSS Read no feed do seu blog, um webhook do seu CMS ou uma nova linha no Google Sheets ou Airtable.
- 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.”
- Opcionalmente, adicione uma aprovação com humano no loop antes do passo
create_postpara que uma pessoa aprove.
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.- Trigger: nó Schedule, por exemplo toda segunda-feira às 8h.
- 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.”
- O agente usa
get_social_network_analyticspara números no nível da conta eget_post_analyticspara publicações individuais, depois você direciona o resumo dele para um nó Slack, Gmail ou Notion.
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:- Por conexão: adicione um header
Profile-Keyao nó MCP Client Tool (use a autenticação Multiple Headers para poder enviarAuthorizationeProfile-Key). Toda chamada nesse nó então age como esse cliente. Bom quando um workflow atende um cliente. - 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. Bom quando um workflow roteia entre clientes.
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
No n8n, mude a Authentication do nó MCP Client Tool para Multiple Headers e adicione os dois headersX-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.
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:- Sempre valide primeiro. Coloque “chamar
validate_postantes decreate_post” no system prompt. A validação não publica nada e captura violações de regras de plataforma cedo. - 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_postpara revisar uma publicação aguardando aprovação.
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:- Método:
POST - URL:
https://api.ayrshare.com/api/post - Authentication: Header Auth,
Authorization: Bearer YOUR_API_KEY
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 intermitentes, então sempre use api.ayrshare.com.) O mesmo padrão funciona para os outros endpoints REST. 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. |
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
Conectar e Configurar
Endpoint, transporte, autenticação, direcionamento de profile e credenciais BYO.
Catálogo de Tools
As 27 tools agrupadas por domínio, com escopo e propósito.
MCP Server
O que é o MCP Server e como ele mapeia para a API da Ayrshare.
Plugin do Claude Code
O mesmo servidor, empacotado para Claude Code.