Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configura il server MCP dell'API People

L'API People offre un server Model Context Protocol (MCP) remoto che consente agli agenti AI di interagire in modo sicuro con i dati di profilo e di contatto di Google Workspace. Configurando il server MCP dell'API People, puoi consentire alle applicazioni AI come Gemini CLI, Claude o IDE di eseguire azioni utilizzando l'API People.

Il server MCP dell'API People fornisce un modo standardizzato per gli agenti AI di:

Leggere i dati: recuperare i profili utente e cercare contatti o persone nella directory
Rispettare la sicurezza: ereditare le stesse autorizzazioni e gli stessi controlli di governance dei dati dell'utente.

Prerequisiti

Un progetto Google Cloud. Per creare un progetto, vedi Creare un progetto.
Un client MCP, come Gemini CLI.
Per eseguire i comandi in questa pagina, configura gcloud CLI in un ambiente di sviluppo locale seguendo questi passaggi:
1. Installa Google Cloud CLI. Se hai già installato gcloud CLI, assicurati di avere la versione più recente eseguendo gcloud components update.
2. Se utilizzi un provider di identità (IdP) esterno, accedi a gcloud CLI con la tua identità federata. Per ulteriori informazioni, vedi Accedi a gcloud CLI con la tua identità federata.
3. Inizializza gcloud CLI.

Configurare il server MCP dell'API People

Per utilizzare il server MCP dell'API People, devi abilitarlo nel tuo progetto Google Cloud e poi configurare il client MCP per connetterti.

Abilitare l'API e il servizio MCP

Per utilizzare il server MCP dell'API People, devi abilitare il seguente servizio nel tuo progetto Google Cloud:

API People

CLI

gcloud services enable people.googleapis.com --project=PROJECT_ID

Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud.

Console

Abilita le API nella console Google Cloud:

Abilita le API

Il server MCP dell'API People 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.

Vai a Branding
Se hai già configurato il Google Auth Platform, puoi configurare le seguenti impostazioni della schermata per il consenso OAuth in Branding, Pubblico, e Accesso ai dati. Se visualizzi il messaggio Google Auth Platform non ancora configurata, fai clic su Inizia:
1. In Informazioni sull'app, in Nome app, digita People API MCP Server.
2. In Email di assistenza utente, seleziona il tuo indirizzo email o un gruppo Google appropriato.
3. Fai clic su Avanti.
4. In Pubblico, seleziona Interno. Se non riesci a selezionare Interno, seleziona Esterno.
5. Fai clic su Avanti.
6. In Dati di contatto, inserisci un indirizzo email su cui ricevere notifiche in merito a eventuali modifiche al progetto.
7. Fai clic su Avanti.
8. In Fine , esamina le Norme relative ai dati utente dei servizi API di Google e, se le accetti, seleziona Accetto le Norme relative ai dati utente: servizi API di Google.
9. Fai clic su Continua.
10. Fai clic su Crea.
11. Se hai selezionato Esterno come tipo di utente, aggiungi utenti di test:
  1. Fai clic su Pubblico.
  2. In Utenti di test, fai clic su Aggiungi utenti.
  3. Inserisci il tuo indirizzo email e gli altri utenti di test autorizzati, poi fai clic su Salva.
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.
1. In Aggiungi ambiti manualmente, incolla gli ambiti per il server MCP dell'API People:
  - https://www.googleapis.com/auth/directory.readonly
  - https://www.googleapis.com/auth/userinfo.profile
  - https://www.googleapis.com/auth/contacts.readonly
2. Fai clic su Aggiungi alla tabella.
3. Fai clic su Aggiorna.
4. Dopo aver selezionato gli ambiti richiesti dalla tua app, fai clic su Salva nella pagina Accesso ai dati.

Configurare il client MCP

Per aggiungere il server MCP remoto dell'API People al client MCP, segui le istruzioni per il tuo client.

Gemini CLI

Per aggiungere il server MCP remoto dell'API People a Gemini CLI, aggiungi la configurazione del server al file settings.json.

Crea un ID client e un client secret OAuth 2.0:
1. Nella console Google Cloud, vai a Google Auth Platform > Client > Crea client.
  
  Vai a Crea client
2. Seleziona App desktop come tipo di applicazione.
3. Inserisci un Nome.
4. Fai clic su Crea e copia l'ID client e il client secret.
Apri o crea il file di configurazione ~/.gemini/settings.json.

Aggiungi la configurazione mcpServers a settings.json:

{
  "mcpServers": {
    "people": {
      "httpUrl": "https://people.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET",
        "scopes": [
          "https://www.googleapis.com/auth/directory.readonly",
          "https://www.googleapis.com/auth/userinfo.profile",
          "https://www.googleapis.com/auth/contacts.readonly"
        ]
      }
    }
  }
}

Sostituisci quanto segue:

OAUTH_CLIENT_ID: l'ID client che hai creato.
OAUTH_CLIENT_SECRET: il client secret che hai creato.

Salva settings.json.
Avvia Gemini CLI:
```
gemini
```
In Gemini CLI, esegui l'autenticazione con il server MCP eseguendo il comando seguente:
```
/mcp auth people
```
1. Quando ti viene richiesto, premi 1 per aprire una pagina di autenticazione nel tuo browser. Se stai lavorando tramite SSH, segui le istruzioni in nell'interfaccia a riga di comando.
2. Accedi al tuo Account Google.
3. Esamina gli ambiti OAuth richiesti e fai clic su Consenti.
4. Viene visualizzato un messaggio che conferma che l'autenticazione è andata a buon fine.
In Gemini CLI, esegui /mcp list per visualizzare i server MCP configurati e i relativi strumenti.

La risposta è simile alla seguente:
```
🟢 people - Ready (3 tools)
  Tools:
  - get_user_profile
  - search_contacts
  - search_directory_people
```

Il server MCP remoto è pronto per essere utilizzato in Gemini CLI.

Claude

Per utilizzare il server MCP remoto dell'API People con Claude.ai o Claude Desktop, devi avere il piano Claude Enterprise, Pro, Max o Team.

Per aggiungere il server MCP remoto dell'API People a Claude, configura un connettore personalizzato con un ID client e un client secret OAuth.

Crea un ID client e un client secret OAuth 2.0:
1. Nella console Google Cloud, vai a Google Auth Platform > Client > Crea client.
  
  Vai a Crea client
2. Seleziona Applicazione web come tipo di applicazione.
3. Inserisci un Nome.
4. Nella sezione URI di reindirizzamento autorizzati, fai clic su + Aggiungi URI, poi aggiungi https://claude.ai/api/mcp/auth_callback nel campo URI.
5. Fai clic su Crea e copia l'ID client e il client secret.
Configura il server MCP in Claude:
1. In Claude.ai o Claude Desktop, vai a Impostazioni (o Impostazioni di amministrazione) > Connettori.
2. Fai clic su Aggiungi connettore personalizzato.
3. Inserisci i dettagli della connessione per il prodotto API People:
  - Nome server: people.
  - URL del server MCP remoto: https://people.googleapis.com/mcp/v1
4. In Impostazioni avanzate, inserisci l'ID client OAuth e il client secret OAuth.
5. Fai clic su Aggiungi.

Altro

Molte applicazioni 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 dell'API People, inserisci quanto segue:

Nome server: people
URL del server: https://people.googleapis.com/mcp/v1
Trasporto: HTTP
Autenticazione: il server MCP remoto dell'API People utilizza OAuth 2.0. Per maggiori dettagli, vedi Scopri di più sull'autenticazione e l'autorizzazione.

Per maggiori dettagli sulla connessione di diversi tipi di client, vedi Configurare MCP in un'applicazione AI.

Testare il server MCP dell'API People

Dopo aver configurato il client MCP, puoi verificare la connessione eseguendo alcuni prompt di test.

Prova a porre le seguenti domande al client MCP:

"Secondo il mio profilo Google, qual è il mio nome?"

Il client utilizza people.get_user_profile per recuperare le informazioni del tuo Profilo Workspace Google.

Se gli strumenti vengono eseguiti correttamente e ricevi risposte pertinenti, il server MCP dell'API People è configurato correttamente.

Risoluzione dei problemi

Se riscontri problemi di connessione al server MCP, puoi verificare la presenza di errori nei log OAuth. Chiedi all'amministratore di controllare gli eventi del log OAuth in lo strumento di indagine sulla sicurezza.

Riferimento agli strumenti

I seguenti strumenti sono disponibili per il server MCP dell'API People:

get_user_profile
search_contacts
search_directory_people

Considerazione importante per la sicurezza: prompt injection indiretto

Quando esponi un modello linguistico a dati non attendibili, esiste il rischio di un attacco di prompt injection indiretto. Poiché i client MCP come Gemini CLI hanno accesso a strumenti e API potenti tramite il server MCP dell'API People, possono leggere i dati nel tuo Account Google.

Per mitigare questi rischi, segui queste best practice:

Utilizza solo strumenti attendibili. Non connettere mai il server MCP dell'API People ad applicazioni non attendibili o non verificate.
Fai attenzione agli input non attendibili. Evita di chiedere al client MCP di elaborare risorse provenienti da fonti non verificate. Questi input potrebbero contenere istruzioni nascoste che possono compromettere la tua sessione, consentendo a un utente malintenzionato di modificare, rubare o eliminare i tuoi dati.
Esamina tutte le azioni. Esamina sempre attentamente le azioni intraprese dal client AI per tuo conto per assicurarti che siano corrette e in linea con le tue intenzioni.