Ligue o Claude e o Cursor para usar o AgencyHandy com MCP

A ligação MCP da AgencyHandy permite falar com o Claude ou o Cursor em linguagem natural e executar o trabalho diário no seu espaço AgencyHandy — sem abrir cada ecrã você mesmo. Mantém o controlo. O Claude e o Cursor só atuam com a chave API do espaço que gera e pedem confirmação quando um nome corresponde a mais do que uma pessoa.

Duas formas de ligar

Onde corre o seu agente	Como ligar	Configuração
No seu computador — Claude Desktop ou Cursor	O pacote `agencyhandy-mcp`, iniciado pela aplicação	Configurar o MCP do Claude ou Cursor, abaixo — requer Node.js 20+
Na cloud — Cloudflare Workers, Vercel, n8n, um Claude ou Cursor alojado	O nosso servidor MCP alojado em `https://mcp.agencyhandy.com/`	Ligar um agente na cloud, abaixo — nada para instalar

Ambos usam a mesma chave API do espaço de trabalho e dão ao agente as mesmas ferramentas.

Precisa de um perfil que possa abrir o Workspace Config e gerir API keys (normalmente SuperAdmin ou Admin). Para a instalação local precisa também de Node.js 20+ na máquina onde corre o Claude Desktop ou o Cursor — o servidor alojado não exige qualquer instalação.

Requisitos

Requisito	Detalhes
Espaço de trabalho AgencyHandy	Acesso a Workspace Config → API Key
Um host MCP	Claude Desktop ou Cursor no seu computador, ou qualquer agente capaz de chamar um servidor MCP por HTTP
Node.js (apenas instalação local)	Versão 20 ou mais recente (`node -v` para confirmar)
Pacote MCP (apenas instalação local)	`npx -y agencyhandy-mcp@1` (entrega 1.7.2+ na tag `1`)

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

Configurar Claude ou Cursor MCP

Use esta via quando o Claude Desktop ou o Cursor corre no seu próprio computador. Se o agente correr na cloud, avance para Ligar um agente na cloud.

Abrir Workspace Config

No AgencyHandy, abra Workspace Config (definições da empresa) e vá ao separador API Key.

Gerar uma chave API do espaço

Crie uma nova chave API do espaço (ou use uma já guardada). Copie a chave quando aparecer — o AgencyHandy não poderá mostrar a chave completa depois.

Copiar a config MCP

No mesmo separador API Key, use o painel de configuração Claude / Cursor MCP. Clique em Copy MCP config para que o JSON inclua a sua chave e o URL do backend.

Colar no Cursor ou Claude Desktop

Cole a config em:

Cursor: projeto ou utilizador .mcp.json
Claude Desktop: claude_desktop_config.json

Mantenha o comando npx -y agencyhandy-mcp@1 e a sua chave API como gerados.

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 espaço.

Se o Claude ou o Cursor não encontrarem o servidor MCP, confirme que o Node.js 20+ está instalado e que reiniciou a app após guardar a config.

Ligar um agente na cloud (servidor alojado)

Se o seu agente corre onde não pode instalar um pacote — Cloudflare Workers, funções Vercel, n8n, ou um Claude ou Cursor alojado — aponte-o para o servidor MCP que alojamos para si:

https://mcp.agencyhandy.com/

Não há nada para instalar nem servidor para manter. Autentique cada pedido com a mesma chave API do espaço de trabalho como bearer token. O espaço de trabalho é lido da chave, por isso cada utilizador liga-se com a sua. Cursor, Claude Code e qualquer host que envie cabeçalhos personalizados:

{
  "mcpServers": {
    "agency-handy": {
      "url": "https://mcp.agencyhandy.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop não consegue enviar cabeçalhos personalizados — faça a ponte com mcp-remote:

{
  "mcpServers": {
    "agency-handy": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.agencyhandy.com/",
        "--header", "Authorization:Bearer YOUR_API_KEY"
      ]
    }
  }
}

Claude Code na linha de comandos:

claude mcp add agency-handy --transport http https://mcp.agencyhandy.com/ \
  --header "Authorization: Bearer YOUR_API_KEY"

O endereço é a raiz — https://mcp.agencyhandy.com/, e não /mcp. Para confirmar que o servidor responde, abra https://mcp.agencyhandy.com/health.

Está antes a construir a sua própria integração com a API HTTP? Envie um cabeçalho User-Agent nos seus pedidos. Alguns runtimes — incluindo o fetch() dos Cloudflare Workers — não enviam nenhum por omissão, e os pedidos sem ele são rejeitados antes de chegarem à API.

Exemplos de prompts

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

Objetivo	Exemplo de prompt
Briefing matinal	“Dá-me um briefing matinal: tickets abertos, faturas por pagar e propostas à espera de clientes.”
Atribuir um ticket	“Atribui o ticket do redesign da homepage da Acme a Jordan Lee (jordan@agency.com).”
Enviar uma fatura	“Envia a fatura INV-1042 ao cliente por e-mail.”
Criar um lead	“Cria um lead para Nora Patel na Bright Studio, e-mail nora@brightstudio.com.”
Marcar uma fatura como paga	“Marca a fatura INV-1042 como paid.”

Quando duas pessoas partilham o mesmo nome

Se duas colegas se chamam Sara, o Claude pergunta a qual se refere. 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

Funciona agora	Ainda não disponível no MCP
Briefings e consultas de propostas, projetos, tickets e faturas	Responder no client chat pelo MCP
Atribuir tickets e outro trabalho da equipa	—
Criar leads	—
Enviar faturas e marcá-las como pagas	—

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

Relacionado

Gere chaves e copie a config na app em Workspace Config → API Key
Servidor alojado para agentes na cloud: 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.

Começar

Configuração do Espaço de Trabalho

CRM

Serviços & Encomendas

Propostas & Faturas

Equipa & Tarefas

Formulários & Ficheiros

Conta & Faturação

Pagamentos

Integrações

Ligue o Claude e o Cursor para usar o AgencyHandy com MCP

Duas formas de ligar

Requisitos

Configurar Claude ou Cursor MCP

Ligar um agente na cloud (servidor alojado)

Exemplos de prompts

Quando duas pessoas partilham o mesmo nome

O que funciona agora vs ainda não

Relacionado

​Duas formas de ligar

​Requisitos

​Configurar Claude ou Cursor MCP

​Ligar um agente na cloud (servidor alojado)

​Exemplos de prompts

​Quando duas pessoas partilham o mesmo nome

​O que funciona agora vs ainda não

​Relacionado

Duas formas de ligar

Requisitos

Configurar Claude ou Cursor MCP

Ligar um agente na cloud (servidor alojado)

Exemplos de prompts

Quando duas pessoas partilham o mesmo nome

O que funciona agora vs ainda não

Relacionado