Skip to main content
A conexão MCP da AgencyHandy permite falar com o Claude ou o Cursor em linguagem natural e executar o trabalho diário no seu workspace AgencyHandy — sem abrir cada tela você mesmo. Você continua no controle. Claude e Cursor só agem com a chave de API do workspace que você gera e pedem confirmação quando um nome corresponde a mais de uma pessoa.

​
Duas formas de conectar

Os dois usam a mesma chave de API do espaço de trabalho e dão ao agente as mesmas ferramentas.
Você precisa de um papel que possa abrir o Workspace Config e gerenciar API keys (normalmente SuperAdmin ou Admin). Para a instalação local você também precisa de Node.js 20+ na máquina onde o Claude Desktop ou o Cursor roda — o servidor hospedado não exige instalação alguma.

​
Requisitos

O pacote MCP no npm é agencyhandy-mcp. Claude e Cursor o executam com npx -y agencyhandy-mcp@1.

​
Configurar Claude ou Cursor MCP

Use este caminho quando o Claude Desktop ou o Cursor roda no seu próprio computador. Se o agente roda na nuvem, pule para Conectar um agente na nuvem.
1

Abrir Workspace Config

No AgencyHandy, abra Workspace Config (configurações da empresa) e vá para a aba API Key.
2

Gerar uma chave de API do workspace

Crie uma nova chave de API do workspace (ou use uma já salva). Copie a chave quando aparecer — o AgencyHandy não poderá mostrar a chave completa depois.
3

Copiar a config MCP

Na mesma aba API Key, use o painel de setup Claude / Cursor MCP. Clique em Copy MCP config para que o JSON inclua sua chave e a URL do backend.
4

Colar no Cursor ou Claude Desktop

Cole a config em:
  • Cursor: projeto ou usuário .mcp.json
  • Claude Desktop: claude_desktop_config.json
Mantenha o comando npx -y agencyhandy-mcp@1 e sua chave de API como gerados.
5

Reiniciar e testar um prompt

Feche completamente e reabra o Cursor ou o Claude Desktop. Depois peça algo simples, como um briefing matinal do workspace.
Se Claude ou Cursor não encontrarem o servidor MCP, confirme que o Node.js 20+ está instalado e que você reiniciou o app após salvar a config.

​
Conectar um agente na nuvem (servidor hospedado)

Se seu agente roda onde você não pode instalar um pacote — Cloudflare Workers, funções da Vercel, n8n, ou um Claude ou Cursor hospedado — aponte-o para o servidor MCP que hospedamos para você:
Não há nada para instalar nem servidor para manter no ar. Autentique cada requisição com a mesma chave de API do espaço de trabalho como bearer token. O espaço de trabalho é lido da chave, então cada usuário se conecta com a sua. Cursor, Claude Code e qualquer host que envie cabeçalhos personalizados:
Claude Desktop não consegue enviar cabeçalhos personalizados — faça a ponte com mcp-remote:
Claude Code pela linha de comando:
O endereço é a raiz — https://mcp.agencyhandy.com/, não /mcp. Para conferir se o servidor responde, abra https://mcp.agencyhandy.com/health.
Está construindo sua própria integração com a API HTTP? Envie um cabeçalho User-Agent nas requisições. Alguns runtimes — incluindo o fetch() do Cloudflare Workers — não enviam nenhum por padrão, e requisições sem ele são rejeitadas antes de chegar à API.

​
Exemplos de prompts

Use linguagem natural. Prefira nomes completos ou e-mails ao atribuir trabalho para selecionar a pessoa certa.

​
Quando duas pessoas têm o mesmo nome

Se duas colegas se chamam Sara, o Claude pergunta a qual você se refere. Ele não inventa IDs nem adivinha em silêncio. Inclua sempre um nome completo ou e-mail no prompt quando os nomes puderem colidir.

​
O que funciona agora vs ainda não

O MCP permite ler seu workspace e executar ações (criar, atribuir, enviar, atualizar) com sua chave de API. Respostas do chat do cliente ainda não estão expostas pelo MCP — use o AgencyHandy para essas conversas.

​
Relacionado

  • Gere chaves e copie a config no app em Workspace Config → API Key
  • Servidor hospedado para agentes na nuvem: https://mcp.agencyhandy.com/ (verificação em /health)
  • Pacote: agencyhandy-mcp no npm (npx -y agencyhandy-mcp@1)
Latest package on the 1 tag is 1.7.2+. Claude can read ah://api-context (also inside ah://full-context) for API path gotchas: leads, projects/orders, tasks, comments, labels, clients, invoices, vouchers, and forms.