Documenti offre un server Model Context Protocol (MCP) remoto che consente agli agenti AI di interagire in modo sicuro con i dati di Documenti. Configurando il server MCP di Documenti, consenti alle applicazioni di AI come Google Antigravity e Claude di eseguire azioni in Documenti.
Il server MCP di Documenti fornisce un modo standardizzato per gli agenti AI di:
- Lettura dei dati: leggi le informazioni strutturali e i contenuti di testo del documento.
- Passa all'azione: aggiorna lo stile e la struttura del documento utilizzando gli aggiornamenti batch.
- Rispetta la sicurezza: eredita le stesse autorizzazioni e gli stessi controlli di governance dei dati dell'utente.
Prerequisiti
Iscrizione al programma Anteprima per gli sviluppatori di Google Workspace.
Un progetto Google Cloud. Per creare un progetto, consulta Crea un progetto.
Un host MCP, ovvero un'applicazione AI come Google Antigravity o Claude. L'applicazione AI crea una connessione client MCP per ogni server MCP.
Per eseguire i comandi in questa pagina, configura gcloud CLI in uno dei seguenti ambienti di sviluppo:
Cloud Shell
Per utilizzare un terminale online con gcloud CLI già configurata, attiva Cloud Shell:
Shell locale
Per utilizzare un ambiente di sviluppo locale, segui questi passaggi:
- Installa Google Cloud CLI.
Se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo
gcloud components update. - Se utilizzi un provider di identità (IdP) esterno, accedi a gcloud CLI con la tua identità federata. Per saperne di più, consulta Accedi a gcloud CLI con la tua identità federata.
- Inizializza la gcloud CLI.
- Installa Google Cloud CLI.
Se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo
Configura il server MCP di Documenti
Per utilizzare il server MCP di Documenti, abilitalo nel tuo progetto Google Cloud e configura la tua applicazione AI per connetterti.
Abilita le API
Per utilizzare il server MCP di Documenti, abilita la seguente API nel tuo progetto Google Cloud:
API Documenti Google
Interfaccia a riga di comando
gcloud services enable docs.googleapis.com --project=PROJECT_ID
Sostituisci PROJECT_ID con l'ID progetto Google Cloud.
Console
Abilita le API nella console Google Cloud:
Abilita i servizi MCP
Per abilitare i componenti MCP per Documenti, abilita il seguente servizio nel tuo progetto Google Cloud:
API Docs MCP
Interfaccia a riga di comando
gcloud services enable docsmcp.googleapis.com --project=PROJECT_ID
Sostituisci PROJECT_ID con l'ID progetto Google Cloud.
Console
Abilita i servizi MCP nella console Google Cloud:
Configura la schermata per il consenso OAuth
Il server MCP di Documenti utilizza OAuth 2.0 per l'autenticazione e l'autorizzazione. Devi configurare la schermata per il consenso OAuth prima di poter creare un ID client OAuth.
Nella console Google Cloud, vai a Google Auth Platform > Branding.
Se hai già configurato la piattaforma di autenticazione di Google, puoi configurare le seguenti impostazioni della schermata per il consenso OAuth in Branding, Pubblico e Accesso ai dati. Se viene visualizzato il messaggio Google Auth Platform non ancora configurata, fai clic su Inizia:
- In Informazioni sull'app, digita
Docs MCP Serverin Nome app. - In Email assistenza utenti, seleziona il tuo indirizzo email o un gruppo Google appropriato.
- Fai clic su Avanti.
- In Pubblico, seleziona Interno. Se non riesci a selezionare Interno, seleziona Esterno.
- Fai clic su Avanti.
- In Dati di contatto, inserisci un indirizzo email a cui puoi ricevere notifiche su eventuali modifiche al progetto.
- Fai clic su Avanti.
- In Fine, esamina le Norme relative ai dati utente dei Google API Services e, se accetti, seleziona Accetto le Norme relative ai dati utente: Google API Services.
- Fai clic su Continua.
- Fai clic su Crea.
- Se hai selezionato Esterno come tipo di utente, aggiungi gli utenti di test:
- Fai clic su Pubblico.
- Nella sezione Utenti di test, fai clic su Aggiungi utenti.
- Inserisci il tuo indirizzo email e gli eventuali altri utenti di test autorizzati, quindi fai clic su Salva.
- In Informazioni sull'app, digita
Fai clic su Accesso ai dati > Aggiungi o rimuovi ambiti. Viene visualizzato un riquadro con un elenco di ambiti per ogni API che hai abilitato nel tuo progetto Google Cloud.
In Aggiungi ambiti manualmente, incolla gli ambiti per il server MCP di Documenti:
https://www.googleapis.com/auth/drive.readonlyhttps://www.googleapis.com/auth/drive.filehttps://www.googleapis.com/auth/documents.readonlyhttps://www.googleapis.com/auth/documents
Fai clic su Aggiungi alla tabella.
Fai clic su Aggiorna.
Dopo aver selezionato gli ambiti richiesti dalla tua app, nella pagina Accesso ai dati, fai clic su Salva.
Configura la tua applicazione di AI
Per aggiungere il server MCP remoto di Documenti alla tua applicazione di AI, segui le istruzioni per la tua applicazione.
Gli ID client OAuth 2.0 delegati dall'utente che chiamano il server MCP di Documenti devono avere l'opzione Utilizza questo client per un agente basato sull'AI selezionata in Google Auth Platform > Client. Per aggiornare un ID client OAuth 2.0 esistente, seleziona questa impostazione in Google Auth Platform > Client, come descritto in Gestisci i client OAuth. Se non riesci a modificare questa impostazione su un client esistente o se il client supporta anche funzionalità non relative agli agenti, crea un nuovo ID client OAuth 2.0 per l'agente AI. Per le richieste rifiutate, i service account con delega a livello di dominio o Google Apps Script, consulta la sezione Risoluzione dei problemi.
Antigravity
Per aggiungere il server MCP remoto di Documenti ad Antigravity, aggiungi la configurazione del server al file mcp_config.json. Queste istruzioni supportano Antigravity 2.0, Antigravity IDE e Antigravity CLI.
Crea un ID client e un secret OAuth 2.0:
Nella console Google Cloud, vai a Google Auth Platform > Client > Crea client.
Seleziona Applicazione web come tipo di applicazione.
Inserisci un Nome.
Nella sezione URI di reindirizzamento autorizzati, fai clic su + Aggiungi URI, quindi aggiungi
https://antigravity.google/oauth-callbacknel campo URI.Seleziona Utilizza questo client per un agente basato sull'AI.
Fai clic su Crea e copia l'ID client e il client secret.
Apri o crea il file di configurazione
~/.gemini/config/mcp_config.json.Aggiungi la configurazione
mcpServersamcp_config.json:{ "mcpServers": { "docs": { "serverUrl": "https://docsmcp.googleapis.com/mcp/v1", "oauth": { "clientId": "OAUTH_CLIENT_ID", "clientSecret": "OAUTH_CLIENT_SECRET" } } } }Sostituisci quanto segue:
OAUTH_CLIENT_ID: l'ID client che hai creato.OAUTH_CLIENT_SECRET: il client secret che hai creato.
Risparmia
mcp_config.json.Autentica il server MCP. Puoi eseguire l'autenticazione utilizzando le impostazioni della GUI o l'interfaccia a riga di comando:
Per Antigravity IDE o GUI (Antigravity 2.0):
- Apri la schermata delle impostazioni (ad esempio, fai clic su Impostazioni in basso a sinistra o apri Impostazioni utente Antigravity).
- Vai a Personalizzazioni.
- Nella sezione Server MCP installati, fai clic su Aggiorna.
- Trova
docsnell'elenco, fai clic su Autentica, accedi al tuo Account Google, copia il codice di autorizzazione, incollalo nella finestra di dialogo di input e fai clic su Invia.
Per Antigravity CLI:
Avvia Antigravity CLI:
agyApri il riquadro di gestione interattivo di MCP eseguendo:
/mcpUtilizza i tasti freccia per selezionare
docs, vai all'azione Autentica e premi Invio. Completa il flusso di accesso nel browser, copia il codice di autorizzazione, incollalo nel prompt del terminale e premi Invio.
Verifica che il server sia configurato correttamente e in esecuzione:
- Per Antigravity IDE o la GUI: viene visualizzato un pulsante Esci accanto al server in Personalizzazioni > Server MCP installati.
- Per Antigravity CLI: apri il riquadro
/mcpper visualizzare i server MCP configurati. I server verificati e autenticati mostrano Authed accanto ai loro nomi all'interno del pannello TUI interattivo. Puoi selezionare qualsiasi server nella visualizzazione della dashboard per controllarne lo stato ed elencare tutti gli strumenti disponibili.
Il server MCP remoto è pronto per l'uso in Antigravity.
Claude
Per utilizzare il server MCP remoto di Documenti con Claude.ai o Claude Desktop, devi disporre del piano Claude Enterprise, Pro, Max o Team.
Per aggiungere il server MCP remoto di Documenti a Claude, configura un connettore personalizzato con un ID client OAuth e un client secret.
Crea un ID client e un secret OAuth 2.0:
Nella console Google Cloud, vai a Google Auth Platform > Client > Crea client.
Seleziona Applicazione web come tipo di applicazione.
Inserisci un Nome.
Nella sezione URI di reindirizzamento autorizzati, fai clic su + Aggiungi URI, quindi aggiungi
https://claude.ai/api/mcp/auth_callbacknel campo URI.Seleziona Utilizza questo client per un agente basato sull'AI.
Fai clic su Crea e copia l'ID client e il client secret.
Configura il server MCP in Claude:
- In Claude.ai o Claude Desktop, vai a Impostazioni > Connettori o Impostazioni amministratore > Connettori.
- Fai clic su Aggiungi connettore personalizzato.
- Inserisci i dettagli della connessione per il prodotto Documenti:
- Nome server:
Docs. - URL del server MCP remoto:
https://docsmcp.googleapis.com/mcp/v1
- Nome server:
- In Impostazioni avanzate, inserisci l'ID client OAuth e il client secret OAuth.
- Fai clic su Aggiungi.
Altri
Molte applicazioni di AI hanno modi per connettersi a un server MCP remoto. In genere, devi inserire i dettagli del server, come nome, endpoint, protocollo di trasporto e metodo di autenticazione. Per il server MCP remoto di Documenti, inserisci quanto segue:
Nome server:
docsURL del server:
https://docsmcp.googleapis.com/mcp/v1Trasporto: HTTP trasmissibile in streaming
Autenticazione: il server MCP remoto di Documenti utilizza OAuth 2.0. Quando crei il client OAuth 2.0, seleziona Utilizza questo client per un agente basato sull'AI. Per maggiori dettagli, consulta Scopri di più su autenticazione e autorizzazione.
Per evitare richieste di accesso orarie con un client OAuth di un'applicazione web, configura il client MCP in modo che richieda l'accesso offline utilizzando
access_type=offlineo l'ambitooffline_access. Per maggiori dettagli, vedi Richieste di accesso ripetute ogni ora.
Per maggiori dettagli sulla connessione di diversi tipi di applicazioni di AI, consulta Configura MCP in un'applicazione di AI.
Testa il server MCP di Documenti
Dopo aver configurato l'applicazione AI, puoi verificare la connessione eseguendo alcuni prompt di test.
Prova a porre alla tua applicazione AI le seguenti domande:
"Mostrami i contenuti strutturali del documento Google
abcd123."Il client recupera la struttura e i contenuti del documento utilizzando
docs.read_doc."Inserisci il titolo 'Il mio piano di marketing' nel documento Google
abcd123."Il client esegue
docs.update_docper aggiornare gli elementi strutturali e inserire il testo.
Se gli strumenti vengono eseguiti correttamente e ricevi risposte pertinenti, il tuo server MCP di Documenti è configurato correttamente.
Risoluzione dei problemi
Utilizza le sezioni seguenti per risolvere i problemi comuni di autenticazione e connessione con il server MCP di Documenti.
Controlla gli eventi dei log OAuth
Se riscontri problemi di connessione al server MCP, controlla se sono presenti errori nei log OAuth. Chiedi all'amministratore di Google Workspace di esaminare gli eventi dei log OAuth nello strumento di indagine sulla sicurezza.
Richieste rifiutate dai client OAuth delegati dagli utenti
Se le tue richieste al server MCP vengono rifiutate, verifica che l'ID client OAuth 2.0 delegato dall'utente per il tuo flusso OAuth a tre vie abbia l'opzione Utilizza questo client per un agente basato sull'AI selezionata in Google Auth Platform > Client:
- Il client esistente supporta l'impostazione: seleziona Utilizza questo client per un agente basato sull'AI nel client OAuth esistente.
- Impossibile aggiornare il client esistente: crea un nuovo client OAuth con l'opzione Utilizza questo client per un agente basato sull'AI selezionata e aggiorna la tua app per utilizzarlo.
- Il client esistente supporta anche funzionalità non relative agli agenti: crea un client OAuth separato per l'agente AI e mantieni il client esistente per le funzionalità non relative agli agenti.
Per le istruzioni, consulta Configura l'applicazione AI e Gestisci i client OAuth.
Service account con delega a livello di dominio
Se la tua app utilizza un service account con delega a livello di dominio per OAuth a 2 vie, non puoi selezionare Utilizza questo client per un agente basato sull'AI perché i service account non sono gestiti in Google Auth Platform > Client:
- Controllo dell'accesso: le richieste al server MCP da questi service account non vengono rifiutate se manca l'impostazione dell'agente. L'accesso è invece regolato dalle impostazioni di delega a livello di dominio gestite dall'amministratore di Google Workspace. Per maggiori dettagli sulle impostazioni dell'amministratore, consulta Controlla l'accesso all'API con la delega a livello di dominio.
- Azioni sensibili: i server MCP di Google Workspace continuano a restituire prompt di richiesta di moduli per la conferma human-in-the-loop delle chiamate allo strumento sensibili effettuate tramite l'impersonificazione di un utente con delega a livello di dominio.
Richieste da Apps Script
Se chiami il server MCP da Apps Script, non puoi selezionare Utilizza questo client per un agente basato sull'AI sul client OAuth predefinito che Apps Script crea e gestisce per il tuo script. Questo vale anche se lo script utilizza un progetto Google Cloud standard.
Per chiamare il server MCP da Apps Script, segui questi passaggi:
- Nella console Google Cloud, vai a Google Auth Platform > Client, crea un client OAuth e seleziona Utilizza questo client per un agente basato sull'AI.
- Nello script, utilizza la libreria OAuth2 per Apps Script per autorizzare gli utenti con quel client OAuth.
- Quando chiami il server MCP, invia il token di accesso restituito dalla libreria anziché il token di
ScriptApp.getOAuthToken.
I progetti Apps Script che non chiamano i server MCP di Google Workspace non sono interessati.
Richieste di accesso ripetute ogni ora
Se ti viene chiesto di accedere di nuovo ogni ora circa, il tuo client MCP non riceve o non utilizza un token di aggiornamento. In genere, questo accade nelle seguenti situazioni:
- Accesso offline mancante su un client OAuth di un'applicazione web: a differenza dei client OAuth di app desktop, i client OAuth di applicazione web utilizzano per impostazione predefinita l'accesso online. Per richiedere un token di aggiornamento, includi
access_type=offlineo l'ambito OpenID Connect (OIDC)offline_accessinsieme ad almeno un ambito API e non impostareaccess_type=online. - Riautorizzazione di un'app già autorizzata: il server OAuth 2.0 di Google emette un token di aggiornamento la prima volta che un utente concede l'accesso offline. Se un utente ha già autorizzato il tuo client OAuth senza accesso offline o se il tuo client MCP ha perso il token di aggiornamento memorizzato, gli accessi successivi potrebbero non restituire un nuovo token di aggiornamento. Includi
prompt=consentnella richiesta di autorizzazione o rimuovi l'accesso dell'app in Collegamenti con l'Account Google e accedi di nuovo. - Token di connessione statico: se passi un token di accesso non elaborato in un'intestazione
Authorization, ad esempio l'output digcloud auth print-access-token, il token scade dopo un'ora, a meno che il client non lo aggiorni.
Per maggiori dettagli, consulta Aggiorna un token di accesso.
Riferimento dello strumento
Per il server MCP di Documenti sono disponibili i seguenti strumenti. Per gli schemi di input e output, consulta il riferimento MCP di Documenti:
Considerazione importante sulla sicurezza: prompt injection indiretto
Quando esponi un modello linguistico a dati non attendibili, esiste il rischio di un attacco di prompt injection indiretto. Poiché le applicazioni di AI come Google Antigravity hanno accesso a strumenti e API potenti tramite il server MCP di Documenti, possono leggere, modificare ed eliminare i dati nel tuo Account Google.
Per mitigare questi rischi, devi esaminare i prompt e le risposte per individuare contenuti dannosi o attacchi di prompt injection. Puoi utilizzare Model Armor fornito da Google o la tua soluzione, se la documenti in modo che gli utenti possano accettare il rischio. Per istruzioni, consulta Configura la sicurezza per i server MCP di Google Workspace.
Segui queste best practice:
- Utilizza solo strumenti affidabili. Non connettere mai il server MCP di Documenti ad applicazioni non attendibili o non verificate.
- Fai attenzione agli input non attendibili. Evita di chiedere alla tua applicazione AI di elaborare documenti o altre risorse provenienti da fonti non verificate. Questi input potrebbero contenere istruzioni nascoste che possono compromettere la tua sessione e consentire a un malintenzionato di modificare, rubare o eliminare i tuoi dati.
- Esamina tutte le azioni. Esamina sempre attentamente le azioni intraprese dalla tua applicazione AI per tuo conto per assicurarti che siano accurate e corrispondano alle tue intenzioni.