Collega un agente IA a FireCMS Cloud (server MCP)

FireCMS Cloud mette a disposizione un server MCP, così assistenti IA come Claude, Claude Code o Cursor possono lavorare direttamente sul tuo progetto: esplorare e modificare i dati, creare e cambiare collezioni, inferire schemi dai documenti già presenti nel tuo Firestore e gestire gli utenti.

C’è un unico indirizzo, uguale per tutti:

https://api.firecms.co/mcp

Aggiungilo al tuo client e accedi a FireCMS Cloud dal browser. Non c’è nulla da installare. L’agente agisce con il tuo account, quindi non può mai fare nulla che tu stesso non potresti fare in FireCMS Cloud.

Prima di iniziare

• Un client compatibile con MCP: Claude (claude.ai o Claude Desktop), Claude Code, Cursor o qualsiasi altro client che parli il Model Context Protocol.
• Un account FireCMS Cloud. La lettura è disponibile a qualsiasi membro del progetto; creare o modificare collezioni, dati e utenti richiede il ruolo admin sul progetto.

Aggiungi il server MCP di FireCMS

In Claude (claude.ai o Claude Desktop), apri Settings → Connectors, scegli Add custom connector, chiamalo FireCMS e incolla:

https://api.firecms.co/mcp

In Claude Code, esegui questo comando nel terminale, poi esegui /mcp dentro Claude Code e scegli Authenticate:

claude mcp add --transport http firecms https://api.firecms.co/mcp

In Cursor, o in qualsiasi altro client che accetti server remoti tramite URL, aggiungi questo alla sua configurazione MCP (.cursor/mcp.json nel tuo progetto, oppure ~/.cursor/mcp.json per tutti i progetti):

{
  "mcpServers": {
    "firecms": {
      "url": "https://api.firecms.co/mcp"
    }
  }
}

Accedi

La prima volta che il client si collega, apre FireCMS Cloud nel tuo browser. Accedi se non l’hai già fatto, controlla quale app sta chiedendo l’accesso e dove ti rimanderà, poi approva. Da quel momento il client resta connesso.

Per scollegarlo, rimuovi il connettore dal tuo client.

Provalo

Chiedi all’agente qualcosa come:

List my FireCMS projects

List the collections in my FireCMS project <il-tuo-project-id>

Add a "featured" boolean property to the products collection, shown after the title

Portare in FireCMS un progetto Firebase esistente

Collegare un progetto crea un account di servizio nel tuo progetto Google Cloud, e per farlo servono i tuoi permessi Google Cloud. Il server ospitato non li possiede mai, quindi questo singolo passaggio avviene in FireCMS Cloud:

1. Chiedi all’agente di collegare il tuo progetto. connect_project_to_firecms risponde con un link a app.firecms.co/new.
2. Scegli lì il progetto e segui i passaggi. Ci vuole circa un minuto.
3. Tornato nel tuo client, setup_all_collections inferisce ogni collezione radice dai dati già presenti.

Attenzione

Firebase Authentication deve essere attivo sul progetto prima di collegarlo. È l’unico prerequisito senza un’API dedicata, quindi attivalo prima dalla console Firebase.

Il passo 3 è quello in cui un progetto esistente diventa un CMS funzionante: FireCMS campiona i documenti di ogni collezione radice, inferisce i tipi delle proprietà e sceglie i nomi da mostrare, un nome al singolare, un’icona e un gruppo di navigazione.

Se preferisci che sia l’agente a occuparsi dell’intero collegamento, compresa l’abilitazione delle API e la creazione del database Firestore, esegui il server in locale: accede con il tuo account Google, quindi può farlo.

Costruire collezioni dai dati esistenti

Strumento	Descrizione
get_root_collections	Elenca le collezioni radice di Firestore di un progetto (lettura in tempo reale)
list_subcollections	Elenca le sottocollezioni di un documento, per esplorare dati annidati
list_databases	Elenca i database Firestore (serve solo oltre (default))
preview_inferred_schema	Inferisce uno schema da un campione di documenti senza salvarlo
infer_collections_from_data 🔒	Inferisce e salva le collezioni per i percorsi scelti
setup_all_collections 🔒	Inferisce e salva ogni collezione radice non ancora mappata

preview_inferred_schema è l’opzione non distruttiva: campiona fino a 200 documenti, inferisce tipi, enumerazioni e validazioni, e restituisce una bozza che puoi modificare e poi salvare con save_collection_schema. Funziona anche per le sottocollezioni e per qualsiasi percorso che gli strumenti massivi saltano.

infer_collections_from_data e setup_all_collections scrivono il risultato direttamente nel progetto. Entrambi saltano i percorsi già associati a una collezione, quindi puoi rieseguirli man mano che il database cresce. Rifiutano anche i percorsi senza documenti: senza nulla da campionare, un modello inventerebbe uno schema partendo dal solo nome del percorso.

Strumenti disponibili

Gli strumenti contrassegnati con 🔒 richiedono il ruolo admin sul progetto. Quelli contrassegnati con 💻 sono offerti solo dal server locale.

Ogni strumento dice al tuo client se si limita a leggere o se modifica qualcosa, e se una modifica può sovrascrivere o eliminare dati, così i client che chiedono conferma prima di scrivere sanno quando chiederla.

Account

Strumento	Descrizione
firecms_get_current_user	Mostra l’utente corrente
firecms_login 💻	Accedi dal browser (Google OAuth)
firecms_logout 💻	Esci

Onboarding

Strumento	Descrizione
connect_project_to_firecms	Collega un progetto Firebase esistente. Ospitato: restituisce il link per farlo in FireCMS Cloud. Locale: lo collega e applica le regole di sicurezza necessarie
list_firebase_projects 💻	Progetti Google Cloud a cui hai accesso, con lo stato di preparazione per FireCMS
get_project_setup_status 💻	Stato di preparazione dettagliato di un progetto
list_firestore_locations 💻	Località disponibili per un nuovo database Firestore
enable_project_apis 💻	Abilita le API di Google Cloud richieste da FireCMS
enable_firestore 💻	Crea il database Firestore predefinito (la località è permanente)
apply_firestore_security_rules 🔒	Aggiunge la regola di accesso di FireCMS a Firestore e Storage (idempotente)
create_firecms_webapp 🔒	Riprova la creazione della web app se è fallita durante il collegamento

Progetti e configurazione

Strumento	Descrizione
list_projects	Elenca i tuoi progetti FireCMS Cloud
get_project_config 🔒	Legge la configurazione completa del progetto (nome, colori, piano, funzionalità)
update_project_name 🔒	Rinomina un progetto
update_project_colors 🔒	Aggiorna i colori primario e secondario del brand
update_default_locale 🔒	Cambia la lingua predefinita
toggle_text_search 🔒	Attiva o disattiva la ricerca testuale locale
toggle_entity_history 🔒	Attiva o disattiva la cronologia delle entità

Utenti

Strumento	Descrizione
list_users 🔒	Elenca gli utenti del progetto e i loro ruoli
add_user 🔒	Invita un utente
update_user_roles 🔒	Modifica i ruoli di un utente
remove_user 🔒	Rimuove un utente

Schemi delle collezioni

Strumento	Descrizione
list_collection_schemas 🔒	Elenca tutti gli schemi di collezione salvati
get_collection_schema 🔒	Legge lo schema completo di una collezione
save_collection_schema 🔒	Crea o sostituisce lo schema di una collezione
update_collection_schema 🔒	Aggiorna parzialmente lo schema di una collezione
delete_collection_schema 🔒	Elimina lo schema di una collezione (i dati restano intatti)
save_property 🔒	Aggiunge o aggiorna una singola proprietà di una collezione
delete_property 🔒	Rimuove una proprietà dallo schema di una collezione
generate_collection	Genera con l’IA lo schema di una collezione a partire da un prompt
modify_collection	Modifica con l’IA uno schema esistente a partire da un prompt

Documenti

Strumento	Descrizione
list_documents	Interroga i documenti (filtri, ordinamento, paginazione)
get_document	Legge un documento dal suo percorso
create_document	Crea un nuovo documento
update_document	Aggiorna parzialmente un documento
delete_document	Elimina un documento
count_documents	Conta i documenti di una collezione
export_collection	Esporta i dati di una collezione in JSON
import_documents 🔒	Importa documenti in blocco (max 500 per chiamata)

Risorse

I client che supportano le risorse MCP possono anche leggerle direttamente:

URI	Descrizione
firecms://projects/{id}/collections	Collezioni Firestore di primo livello
firecms://projects/{id}/users	Utenti del progetto e ruoli
firecms://projects/{id}/schemas	Tutti gli schemi di collezione (albero di configurazione completo)
firecms://projects/{id}/config	Istantanea della configurazione del progetto

Esegui il server in locale

Lo stesso server è pubblicato come @firecms/mcp-server e può girare sulla tua macchina tramite stdio. Richiede Node.js 18 o successivo. In locale accede con il tuo account Google invece che tramite FireCMS Cloud, ed è questo che gli permette anche di abilitare le API, creare database Firestore e collegare progetti dall’inizio alla fine.

In Claude Code:

claude mcp add firecms -- npx -y @firecms/mcp-server

Per Claude Desktop, Cursor o qualsiasi altro client MCP, aggiungi questo al file di configurazione MCP del client (claude_desktop_config.json per Claude Desktop):

{
  "mcpServers": {
    "firecms": {
      "command": "npx",
      "args": ["-y", "@firecms/mcp-server"]
    }
  }
}

Poi riavvia il client e chiedi all’agente di eseguire lo strumento firecms_login. Si apre un browser per l’accesso con Google e le credenziali vengono salvate in ~/.firecms/tokens.json, lo stesso file usato dalla CLI di FireCMS. Devi farlo una sola volta. Usa firecms_logout per uscire.

Con il server locale, il collegamento di un progetto si fa interamente dall’agente:

1. list_firebase_projects — mostra quali progetti puoi collegare e cosa manca ancora
2. get_project_setup_status — controlla un progetto nel dettaglio (facoltativo)
3. enable_project_apis — solo se apisEnabled è false
4. enable_firestore — solo se firestoreEnabled è false (la località è permanente)
5. connect_project_to_firecms — account di servizio, utente amministratore e regole di sicurezza
6. setup_all_collections — inferisce ogni collezione radice dai dati già presenti

Permessi e sicurezza

• Autenticazione: il server ospitato usa OAuth. Approvi ogni client in FireCMS Cloud, e il client riceve un token valido solo per il tuo account. Il server locale usa Google OAuth nel browser, lo stesso flusso di firecms login nella CLI.
• L’autorizzazione viene verificata per progetto: ogni scrittura richiede il ruolo admin.
• Il server ospitato non possiede credenziali Google Cloud. Può fare ciò che tu puoi fare in FireCMS Cloud, mai ciò che puoi fare su Google Cloud.
• Token: il server ospitato conserva i propri token solo come hash; i token di accesso durano un’ora e i token di aggiornamento vengono sostituiti a ogni utilizzo. Il server locale conserva i propri token in ~/.firecms/tokens.json, condiviso con la CLI.
• Le credenziali non raggiungono mai il modello: list_projects rimuove l’account di servizio di ogni progetto dal proprio output.

Risoluzione dei problemi

Il client non riesce a collegarsi, o continua a chiedere di accedere. Rimuovi il connettore e aggiungilo di nuovo con https://api.firecms.co/mcp, poi approva la richiesta nella finestra del browser che si apre.

Gli strumenti non compaiono dopo aver modificato un file di configurazione. I client MCP leggono la configurazione all’avvio: riavvia completamente il client.

Una scrittura fallisce con un errore di permessi. L’account con cui hai effettuato l’accesso richiede il ruolo admin su quel progetto. Verificalo nella sezione Utenti del progetto su FireCMS Cloud, oppure chiedi a un amministratore di assegnartelo.

Dopo aver collegato un progetto non compare nessuna collezione. Assicurati che Firebase Authentication sia attivo e che le regole di sicurezza siano state applicate (apply_firestore_security_rules), poi esegui setup_all_collections.

Il server locale dice che non hai effettuato l’accesso. Esegui lo strumento firecms_login. Se la finestra del browser non si apre, esegui npx @firecms/mcp-server --help in un terminale per verificare che il pacchetto si installi e si avvii.