Documentazione

Agenti AI (MCP)

Collega il server MCP

Collega Claude, Claude Code, ChatGPT, Cursor, VS Code o Codex al tuo workspace AmICited tramite MCP. Un solo URL, accesso OAuth e una chiave API come alternativa.

AmICited gestisce un server MCP (Model Context Protocol) sempre attivo. Una volta collegato il tuo client AI, può leggere i tuoi dati di visibilità, eseguire report e, con accesso in scrittura, aggiungere prompt, generare articoli o registrare annotazioni, tutto da una normale conversazione. Ogni funzione della dashboard è disponibile anche come strumento MCP, quindi non c’è nulla che tu possa fare nell’app che un agente non possa fare.

Prima di iniziare#

  • Un piano che include MCP. MCP è disponibile nella prova di 7 giorni e sui piani Pro, Premium ed Enterprise. I workspace Starter possono vedere l’URL del server, ma le connessioni vengono rifiutate finché non passi a un piano superiore. Vedi piani e limiti.
  • Permessi di Editor o superiori nel workspace. La pagina MCP invita i membri che non li hanno a rivolgersi a un owner o admin del workspace.
  • Un saldo di crediti positivo. Le letture tramite MCP sono gratuite, ma l’endpoint verifica che il workspace abbia crediti prima di rispondere. Vedi crediti.

L’URL del server#

C’è un solo URL per tutti:

text
https://api.flowhunt.io/mcp/amicited

Il workspace non è nell’URL. Deriva dalla tua credenziale: con OAuth scegli il workspace nella schermata di consenso, e una chiave API appartiene già a un solo workspace. Puoi anche copiare l’URL dalla pagina MCP nell’app, che lo mostra con un pulsante Copy URL e le stesse istruzioni per client riportate qui sotto. Il trasporto è streamable HTTP.

Collega il tuo client#

Scegli il tuo client. Ogni scheda inizia con l’accesso OAuth consigliato e termina con l’alternativa della chiave API.

Claude (web e Desktop)

I connettori che aggiungi su claude.ai sono disponibili anche nell’app Claude Desktop.

  1. Apri le impostazioni dei connettori di Claude.
  2. Fai clic su +, poi su Add custom connector.
  3. Incolla https://api.flowhunt.io/mcp/amicited e fai clic su Add.
  4. Fai clic su Connect sul nuovo connettore e approva l’accesso nella finestra del browser che si apre. Scegli il tuo workspace nella schermata di consenso.

In una chat, apri il menu degli strumenti e assicurati che il connettore AmICited sia abilitato.

Alternativa con chiave API (file di configurazione di Claude Desktop). Aggiungi questo sotto mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json su macOS, poi riavvia Claude Desktop:

claude_desktop_config.json
{
  "mcpServers": {
    "amicited": {
      "type": "http",
      "url": "https://api.flowhunt.io/mcp/amicited",
      "headers": {
        "Authorization": "Bearer <your-workspace-api-key>"
      }
    }
  }
}

Claude Code

Registra il server una volta dal terminale:

bash
claude mcp add --transport http amicited https://api.flowhunt.io/mcp/amicited

Poi esegui /mcp dentro Claude Code, scegli Authenticate e approva l’accesso nella finestra del browser che si apre.

Alternativa con chiave API. Aggiungi il server sotto la chiave di primo livello mcpServers in ~/.claude.json e riavvia Claude Code:

~/.claude.json
{
  "mcpServers": {
    "amicited": {
      "type": "http",
      "url": "https://api.flowhunt.io/mcp/amicited",
      "headers": {
        "Authorization": "Bearer <your-workspace-api-key>"
      }
    }
  }
}

ChatGPT

I connettori MCP personalizzati richiedono la Developer mode, disponibile sui piani ChatGPT a pagamento (Plus, Pro, Team, Enterprise). Nei workspace Business, Enterprise ed Edu può essere necessario che un admin la abiliti per te.

  1. Attiva la Developer mode come descritto nella documentazione dei connettori di OpenAI.
  2. In ChatGPT, apri Settings, poi Apps & Connectors.
  3. Aggiungi un connettore personalizzato e incolla https://api.flowhunt.io/mcp/amicited.
  4. Approva l’accesso nella finestra del browser che si apre.

Alternativa con chiave API. Al passaggio 4, scegli invece l’autenticazione con chiave API e incolla la chiave API del tuo workspace. Salva il connettore, poi abilitalo in una nuova chat.

Cursor

Nella pagina MCP dell’app, seleziona Cursor e fai clic su Add to Cursor. Cursor installa il server ed esegue l’accesso al posto tuo.

Se il pulsante non apre Cursor, aggiungi il server a mano nelle impostazioni di Cursor sotto MCP, oppure modifica ~/.cursor/mcp.json (o un .cursor/mcp.json per singolo progetto):

~/.cursor/mcp.json
{
  "mcpServers": {
    "amicited": {
      "url": "https://api.flowhunt.io/mcp/amicited"
    }
  }
}

Cursor apre un browser per l’accesso la prima volta che si connette. Imposta la chat in modalità Agent per usare gli strumenti.

Alternativa con chiave API. Aggiungi un header alla stessa voce:

json
"headers": { "Authorization": "Bearer <your-workspace-api-key>" }

VS Code

VS Code usa il server tramite GitHub Copilot in modalità Agent, quindi Copilot deve essere abilitato.

Nella pagina MCP dell’app, seleziona VS Code e fai clic su Add to VS Code. VS Code installa il server ed esegue l’accesso al posto tuo.

Per aggiungerlo a mano, apri la Command Palette, esegui MCP: Open User Configuration e aggiungi il server sotto servers:

mcp.json
{
  "servers": {
    "amicited": {
      "type": "http",
      "url": "https://api.flowhunt.io/mcp/amicited"
    }
  }
}

Alternativa con chiave API. Aggiungi "headers": { "Authorization": "Bearer <your-workspace-api-key>" } alla voce. Puoi anche eseguire MCP: Add Server…, scegliere HTTP (HTTP or Server-Sent Events), incollare l’URL e aggiungere l’header Authorization quando richiesto.

Codex

Codex si collega come un normale client MCP remoto. Aggiungi il server, poi accedi:

bash
codex mcp add amicited --url https://api.flowhunt.io/mcp/amicited
codex mcp login amicited

Oppure modifica direttamente ~/.codex/config.toml:

~/.codex/config.toml
[mcp_servers.amicited]
url = "https://api.flowhunt.io/mcp/amicited"
oauth_resource = "https://api.flowhunt.io/mcp/amicited"

Alternativa con chiave API. Metti la chiave in una variabile d’ambiente e indica a Codex di usarla:

~/.codex/config.toml
[mcp_servers.amicited]
url = "https://api.flowhunt.io/mcp/amicited"
bearer_token_env_var = "AMICITED_API_KEY"

Codex eseguito con impostazioni di approvazione rigorose raggiunge comunque ogni strumento di sola lettura tramite read_tool. Vedi toolset e strumenti.

OAuth o chiave API#

OAuth 2.1 (consigliato)Chiave API del workspace (alternativa)
ConfigurazioneIncolla l’URL, approva nel browserIncolla l’URL più un header Authorization: Bearer
WorkspaceScelto nella schermata di consensoFissato dalla chiave
Permessiamicited:read per connettersi e leggere; per le scritture serve anche amicited:writeAccesso completo al workspace
RevocaConnected clients → Revoke nella pagina MCPElimina o fai scadere la chiave

OAuth è l’impostazione predefinita migliore: non c’è alcun segreto da incollare in un file di configurazione, ogni client compare per nome nella pagina MCP sotto Connected clients e puoi revocarne uno senza toccare gli altri. Un token OAuth di sola lettura può elencare e leggere tutto, ma qualsiasi strumento che crea, modifica o elimina rifiuterà con un messaggio che nomina lo scope amicited:write. Riprovare non serve; ricollegati con accesso in scrittura.

Tratta una chiave API come una password

Chiunque possieda una chiave API del workspace può eseguire ogni strumento del server sui dati del tuo workspace, comprese le scritture. Preferisci OAuth, tieni le chiavi fuori dai repository condivisi e usa una variabile d’ambiente dove il tuo client la supporta.

Verifica che funzioni#

Chiedi al tuo agente qualcosa di semplice: “List my AmICited domains.” Dovrebbe chiamare list_domains e restituire i tuoi domini per nome. Poi prova “Show my AI visibility for the last 30 days”, che usa prompt_analytics.

Se la connessione viene rifiutata, il messaggio di solito ne spiega il motivo:

  • Piano. “requires a Pro plan or above”: il piano dell’owner del workspace non include MCP.
  • Crediti. Il saldo del workspace è zero o negativo. Ricarica e riprova.
  • Limite di frequenza. Le chiamate agli strumenti hanno un tetto per workspace all’ora: 120 nella prova, 600 su Pro, 2,000 su Premium, illimitate su Enterprise. Il messaggio indica quando si azzera la finestra. L’elenco degli strumenti e la lettura delle skill non contano.

Correlati#