Guia de configuração do MCP

Conecte o Claude Desktop, o Claude Code, o ChatGPT ou qualquer agente compatível com MCP ao SociaHive: HTTP, stdio, OAuth e CLI em um só lugar.

Conecte o Claude Desktop, o Claude Code, o ChatGPT ou qualquer agente compatível com MCP à sua instância do SociaHive para gerenciar fluxos, posts e métricas em linguagem natural. Os contatos ficam no painel: o agente não os expõe como ferramentas de propósito.

Conecte seu cliente

Primeiro, gere uma chave de API em Configurações → Chaves de API no painel do SociaHive. As chaves novas já incluem o escopo agent:execute. Depois, escolha seu cliente:

No Claude (app de computador ou claude.ai): Configurações → Conectores → Adicionar conector personalizado. Cole:

https://www.sociahive.com/api/mcp

Clique em Conectar e entre no SociaHive. Não precisa de chave de API: o conector usa o seu login do SociaHive. Marque “Acesso somente leitura” na tela de login se você quiser que o Claude só consulte.

O ChatGPT também se conecta por URL e login; veja a aba do ChatGPT.

Sem configuração local, sem Node.js, sem etapas de build.

Ferramentas disponíveis

O catálogo completo de ferramentas, com parâmetros, escopos de chave de API necessários e quais pedem confirmação, está na referência de ferramentas, gerada direto do registro de ferramentas para nunca ficar defasada.

Toda ferramenta roda como o usuário autenticado, então os limites e a cobrança do seu plano valem automaticamente. Chame list_capabilities de qualquer cliente MCP para ver o conjunto exato que a sua chave pode usar: ele filtra por escopos e plano.

Em linhas gerais:

Área	Exemplos
Sessão	`whoami`, `list_capabilities`
Fluxos (leitura)	`list_flows`, `get_flow`, `list_flows_with_stats`, `search_flows`
Fluxos (escrita)	`create_flow`, `generate_flow`, `add_node`, `add_edge`, `activate_flow`
Posts (leitura)	`list_scheduled_posts`, `get_scheduler_calendar`, `get_post_analytics`
Posts (escrita)	`create_scheduled_post`, `schedule_post`, `publish_post_now`
Contas e mídia	`list_accounts`, `get_capabilities`, `search_published_media`
Métricas	`get_flow_stats`, `get_analytics_overview`, `get_content_insights`
Destrutivas	`delete_flow`, `delete_scheduled_post`, `disconnect_account`

Dois comportamentos que vale conhecer antes de começar:

Alterações no grafo rejeitam fluxos publicados. add_node / update_node / add_edge devolvem um state_error com a sugestão duplicate_then_edit: duplique o fluxo para um rascunho, edite e publique de novo.
Não existe “criar e publicar” em uma etapa só. Use create_scheduled_post para criar o rascunho e depois publish_post_now (que pede confirmação). O caminho combinado foi removido porque contornava a confirmação que protege contra publicações ao vivo por engano. O que já foi publicado na plataforma nunca é tocado: o agente não exclui nada do Instagram, do Facebook etc.

Exemplos de prompts

Experimente estes no Claude Desktop, no Claude Code ou em qualquer cliente MCP depois de conectar:

“Liste meus fluxos de automação do Instagram”
“Crie um fluxo que envie um cupom de desconto por direct para novos seguidores”
“Como foi meu engajamento no Instagram na semana passada?”
“Agende um post para amanhã às 9h: ‘Lançamento do novo produto’”
“Duplique meu fluxo de boas-vindas e renomeie para ‘Boas-vindas de fim de ano’”
“No fluxo X, adicione uma espera de 5 minutos entre a mensagem de boas-vindas e o desconto”
“Mostre as métricas do meu fluxo de captura de leads”

Escopos da chave de API

As chaves de API têm um ou mais escopos. O endpoint do MCP exige agent:execute, que já vem em toda chave nova.

As operações irreversíveis (delete_*, disconnect_account, publish_post_now) passam por uma etapa de confirmação, seja qual for o escopo. A primeira chamada devolve um token de confirmação de uso único (validade de 5 minutos); a segunda precisa devolvê-lo. Veja o Fluxo de confirmação abaixo.

Fluxo de confirmação

As ferramentas destrutivas devolvem um envelope pending_confirmation na primeira chamada. Os clientes (Claude Desktop, Claude Code, a CLI sociahive) tratam isso de forma transparente: o modelo mostra para você as entidades afetadas e pergunta antes de chamar de novo com o token de confirmação.

Para clientes programáticos, o contrato é:

A primeira chamada devolve { __mcp_envelope: 'pending_confirmation', confirmToken, summary, affectedEntities } (validade de 5 min).
Na segunda chamada, envie os mesmos argumentos mais __confirmToken: <token>. O servidor valida o token, confere que ele nunca foi usado e executa a ferramenta.

Solução de problemas

“Authentication failed” / 401

Envie a chave como Authorization: Bearer sk_... ou como X-API-Key: sk_.... Os dois cabeçalhos funcionam.
Confira se a chave tem o escopo agent:execute (concedido automaticamente no primeiro uso; confirme na tela de chaves de API).

“Connection refused” no stdio local

Rode npm run dev para iniciar o servidor Next.js local.
Defina SOCIAHIVE_API_URL=http://localhost:3000 (NÃO use /api/v1: a CLI agora acrescenta /api/mcp sozinha).

As ferramentas não aparecem

Reinicie o Claude Desktop depois de adicionar a configuração.
Confira os registros do Claude Desktop: Ajuda > Mostrar registros.

Limite de requisições

Limites por ferramenta: leituras 120/min, escritas 30/min, caras (como generate_flow) 5/min, teto diário de 1.000.
Teto de sessões simultâneas: 200 no transporte HTTP. Feche as sessões ociosas ou espere 5 min até a validade expirar.

Tempo esgotado em generate_flow

A ferramenta devolve na hora um rascunho com o link do editor. A geração com IA, que vai chegando aos poucos (streaming), acontece de fato quando você abre o fluxo no painel. O custo é medido lá, não nesta chamada.

publish_post_now devolve pending_confirmation

É o esperado: operações destrutivas exigem uma segunda chamada com o __confirmToken. Na CLI, use --yes. Clientes compatíveis com MCP cuidam disso sozinhos.

add_node / update_node / add_edge rejeita com state_error

O fluxo de destino está published. Duplique-o para um rascunho (duplicate_flow), edite a cópia e publique de novo.