Collega Claude e Cursor per gestire AgencyHandy con MCP

La connessione MCP di AgencyHandy ti consente di parlare con Claude o Cursor in linguaggio naturale ed eseguire il lavoro quotidiano nel workspace AgencyHandy — senza aprire ogni schermata tu stesso. Restate voi al comando. Claude e Cursor agiscono solo con la chiave API del workspace che generate e chiedono conferma quando un nome corrisponde a più di una persona.

Due modi per collegarsi

Dove gira il tuo agente	Come collegarlo	Configurazione
Sul tuo computer — Claude Desktop o Cursor	Il pacchetto `agencyhandy-mcp`, avviato dall’app	Configurare Claude o Cursor MCP, qui sotto — richiede Node.js 20+
Nel cloud — Cloudflare Workers, Vercel, n8n, un Claude o Cursor ospitato	Il nostro server MCP ospitato su `https://mcp.agencyhandy.com/`	Collegare un agente cloud, qui sotto — niente da installare

Entrambi usano la stessa chiave API dello spazio di lavoro e offrono all’agente gli stessi strumenti.

Ti serve un ruolo che possa aprire Workspace Config e gestire le API keys (di solito SuperAdmin o Admin). Per l’installazione locale serve anche Node.js 20+ sul computer dove gira Claude Desktop o Cursor — il server ospitato non richiede alcuna installazione.

Requisiti

Requisito	Dettagli
Spazio di lavoro AgencyHandy	Accesso a Workspace Config → API Key
Un host MCP	Claude Desktop o Cursor sul tuo computer, oppure qualsiasi agente in grado di chiamare un server MCP via HTTP
Node.js (solo installazione locale)	Versione 20 o successiva (`node -v` per verificare)
Pacchetto MCP (solo installazione locale)	`npx -y agencyhandy-mcp@1` (include 1.7.2+ sul tag `1`)

Il pacchetto MCP su npm è agencyhandy-mcp. Claude e Cursor lo eseguono con npx -y agencyhandy-mcp@1.

Configurare Claude o Cursor MCP

Usa questa via quando Claude Desktop o Cursor gira sul tuo computer. Se il tuo agente gira nel cloud, passa a Collegare un agente cloud.

Aprire Workspace Config

In AgencyHandy, apri Workspace Config (impostazioni azienda), poi vai alla scheda API Key.

Generare una chiave API del workspace

Crea una nuova chiave API del workspace (o usa una già salvata). Copia la chiave quando compare — AgencyHandy non potrà più mostrare la chiave completa in seguito.

Copiare la config MCP

Nella stessa scheda API Key, usa il pannello di setup Claude / Cursor MCP. Fai clic su Copy MCP config così il JSON include chiave e URL del backend.

Incollare in Cursor o Claude Desktop

Incolla la config in:

Cursor: progetto o utente .mcp.json
Claude Desktop: claude_desktop_config.json

Mantieni il comando npx -y agencyhandy-mcp@1 e la chiave API come generati.

Riavviare e provare un prompt

Chiudi completamente e riapri Cursor o Claude Desktop. Poi chiedi qualcosa di semplice, ad esempio un briefing mattutino del workspace.

Se Claude o Cursor non trovano il server MCP, conferma che Node.js 20+ è installato e che hai riavviato l’app dopo aver salvato la config.

Collegare un agente cloud (server ospitato)

Se il tuo agente gira dove non puoi installare un pacchetto — Cloudflare Workers, funzioni Vercel, n8n, o un Claude o Cursor ospitato — puntalo al server MCP che ospitiamo per te:

https://mcp.agencyhandy.com/

Non c’è nulla da installare né alcun server da mantenere. Autentica ogni richiesta con la stessa chiave API dello spazio di lavoro come bearer token. Lo spazio di lavoro viene letto dalla chiave, quindi ogni utente si collega con la propria. Cursor, Claude Code e qualsiasi host che invia header personalizzati:

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

Claude Desktop non può inviare header personalizzati: fai da ponte con mcp-remote:

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

Claude Code da riga di comando:

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

L’indirizzo è la radice — https://mcp.agencyhandy.com/, non /mcp. Per verificare che il server risponda, apri https://mcp.agencyhandy.com/health.

Stai invece costruendo la tua integrazione sull’API HTTP? Invia un header User-Agent con le tue richieste. Alcuni runtime — incluso il fetch() di Cloudflare Workers — non ne inviano nessuno per impostazione predefinita, e le richieste senza header vengono rifiutate prima di raggiungere l’API.

Esempi di prompt

Usa il linguaggio naturale. Preferisci nome completo o email quando assegni lavoro, così viene scelta la persona giusta.

Obiettivo	Esempio di prompt
Briefing mattutino	“Dammi un briefing mattutino: ticket aperti, fatture non pagate e proposte in attesa dei clienti.”
Assegnare un ticket	“Assegna il ticket sul redesign della homepage Acme a Jordan Lee (jordan@agency.com).”
Inviare una fattura	“Invia la fattura INV-1042 al cliente via email.”
Creare un lead	“Crea un lead per Nora Patel di Bright Studio, email nora@brightstudio.com.”
Segnare una fattura come pagata	“Segna la fattura INV-1042 come paid.”

Quando due persone hanno lo stesso nome

Se due colleghe si chiamano entrambe Sara, Claude chiede a quale ti riferisci. Non inventa ID e non indovina in silenzio. Includi sempre un nome completo o un’email nel prompt quando i nomi possono entrare in conflitto.

Cosa funziona ora vs non ancora

Funziona ora	Non ancora disponibile da MCP
Briefing e ricerche su proposte, progetti, ticket e fatture	Rispondere nella client chat da MCP
Assegnare ticket e altro lavoro di team	—
Creare lead	—
Inviare fatture e segnarle come pagate	—

MCP consente di leggere il workspace e compiere azioni (creare, assegnare, inviare, aggiornare) con la chiave API. Le risposte della chat cliente non sono ancora esposte via MCP — usa AgencyHandy per quelle conversazioni.

Correlati

Genera le chiavi e copia la config nell’app in Workspace Config → API Key

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.

Server ospitato per agenti cloud: https://mcp.agencyhandy.com/ (verifica su /health)
Pacchetto: agencyhandy-mcp su npm (npx -y agencyhandy-mcp@1)

Inizia

Configurazione Workspace

CRM

Servizi e Ordini

Proposte e Fatture

Team e Attività

Moduli e File

Account e Fatturazione

Pagamenti

Integrazioni

Collega Claude e Cursor per gestire AgencyHandy con MCP

Due modi per collegarsi

Requisiti

Configurare Claude o Cursor MCP

Collegare un agente cloud (server ospitato)

Esempi di prompt

Quando due persone hanno lo stesso nome

Cosa funziona ora vs non ancora

Correlati

​Due modi per collegarsi

​Requisiti

​Configurare Claude o Cursor MCP

​Collegare un agente cloud (server ospitato)

​Esempi di prompt

​Quando due persone hanno lo stesso nome

​Cosa funziona ora vs non ancora

​Correlati

Due modi per collegarsi

Requisiti

Configurare Claude o Cursor MCP

Collegare un agente cloud (server ospitato)

Esempi di prompt

Quando due persone hanno lo stesso nome

Cosa funziona ora vs non ancora

Correlati