Utilizzare l'API Cloud Healthcare con MCP e altri agenti

Questa guida mostra come utilizzare MCP Toolbox for Databases per connettere l'API Cloud Healthcare a una serie di ambienti di sviluppo integrati (IDE) e strumenti per sviluppatori. Utilizza il Model Context Protocol (MCP), un protocollo aperto per collegare modelli linguistici di grandi dimensioni (LLM) a origini dati come i set di dati sanitari, consentendoti di cercare e interagire con i dati sanitari direttamente dagli strumenti esistenti.

Questa guida mostra la procedura di connessione per i seguenti IDE:

  • Cursore
  • Windsurf (in precedenza Codeium)
  • Visual Studio Code (Copilot)
  • Cline (estensione VS Code)
  • Claude desktop
  • Codice Claude

Prima di iniziare

  1. Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

  2. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  3. Abilita l'API Cloud Healthcare nel Google Cloud progetto.

  4. Configura i ruoli e le autorizzazioni richiesti per completare questa attività. Per connetterti al progetto, devi disporre del ruolo Lettore risorse FHIR Healthcare (roles/healthcare.fhirResourceReader) e del ruolo Visualizzatore DICOM Healthcare (roles/healthcare.dicomViewer) o di autorizzazioni IAM equivalenti.

  5. Configura le credenziali predefinite dell'applicazione (ADC) per il tuo ambiente.

Installare la casella degli strumenti MCP

Il toolkit funge da server Model Context Protocol (MCP) open source che si trova tra l'IDE e l'API Cloud Healthcare, fornendo un control plane sicuro ed efficiente per i tuoi strumenti di AI.

  1. Scarica l'ultima versione di MCP Toolbox come file binario. Seleziona il file binario corrispondente al tuo sistema operativo e all'architettura della CPU. Devi utilizzare MCP Toolbox versione v0.19.1 o successive:

    linux/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.19.1.

    macOS darwin/arm64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.19.1.

    macOS darwin/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.19.1.

    windows/amd64

    curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox

    Sostituisci VERSION con la versione di MCP Toolbox, ad esempio v0.19.1.

  2. Rendi eseguibile il file binario:

    chmod +x toolbox

  3. Verifica l'installazione:

    ./toolbox --version

Configurare client e connessioni

Questa sezione spiega come connettere l'API Cloud Healthcare ai tuoi strumenti.

Codice Claude

  1. Installa Claude Code.
  2. Crea un file .mcp.json nella root del progetto, se non esiste.
  3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Riavvia Claude Code per caricare le nuove impostazioni. Quando si riapre, lo strumento indica che è stato rilevato il server MCP configurato.

Claude desktop

  1. Apri Claude Desktop e vai a Impostazioni.
  2. Nella scheda Sviluppatore, fai clic su Modifica configurazione per aprire il file di configurazione.
  3. Aggiungi la configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Riavvia Claude Desktop.
  5. Nella nuova schermata della chat viene visualizzata un'icona a forma di martello (MCP) con il nuovo server MCP.

Cline

  1. Apri l'estensione Cline in VS Code e tocca l'icona Server MCP.
  2. Tocca Configura server MCP per aprire il file di configurazione.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }

Dopo la connessione riuscita del server, viene visualizzato uno stato attivo verde.

Cursore

  1. Crea la directory .cursor nella root del progetto se non esiste.
  2. Crea il file .cursor/mcp.json se non esiste e aprilo.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Apri Cursore e vai a Impostazioni > Impostazioni cursore > MCP. Quando il server si connette, viene visualizzato uno stato attivo verde.

Visual Studio Code (Copilot)

  1. Apri VS Code e crea una directory .vscode nella radice del progetto se non esiste.
  2. Crea il file .vscode/mcp.json se non esiste, e aprilo.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
            {
          "servers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Ricarica la finestra di VS Code. L'estensione compatibile con MCP rileva automaticamente la configurazione e avvia il server.

Windsurf

  1. Apri Windsurf e vai all'assistente Cascade.
  2. Fai clic sull'icona di MCP, quindi su Configura per aprire il file di configurazione.
  3. Aggiungi la seguente configurazione, sostituisci le variabili di ambiente con i tuoi valori e salva: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }

          }
        }

Nota:la variabile di ambiente HEALTHCARE_PROJECT specifica l'ID progetto Google Cloud predefinito da utilizzare per MCP Toolbox. Tutte le operazioni, come la ricerca di pazienti o la ricerca di istanze DICOM, vengono eseguite all'interno di questo progetto.

Utilizzare gli strumenti

Il tuo strumento di AI è ora connesso all'API Cloud Healthcare tramite MCP. Prova a chiedere all'assistente AI di cercare pazienti FHIR, recuperare le cartelle di un determinato paziente, cercare uno studio DICOM o elencare gli archivi DICOM nel set di dati.

Sono disponibili i seguenti strumenti per il LLM:

  • get_dataset: recupera i dettagli di un set di dati.
  • list_datasets: elenca i set di dati sanitari in un progetto.
  • list_fhir_stores: elenca gli archivi FHIR nel set di dati specificato.
  • list_dicom_stores: elenca gli archivi DICOM nel set di dati specificato.
  • get_fhir_store: recupera la configurazione del datastore FHIR specificato.
  • get_fhir_store_metrics: recupera le metriche associate all'archivio FHIR.
  • get_fhir_resource: recupera i contenuti di una risorsa FHIR.
  • get_fhir_resource_version: recupera i contenuti di una versione (attuale o cronologica) di una risorsa FHIR.
  • fhir_patient_everything: recupera una risorsa FHIR Patient e le risorse correlate a quel paziente.
  • fhir_patient_search: cerca le risorse FHIR Patient nell'archivio FHIR in base ai criteri specificati.
  • get_dicom_store: recupera la configurazione dell'archivio DICOM specificato.
  • get_dicom_store_metrics: recupera le metriche associate all'archivio DICOM.
  • search_dicom_studies: restituisce un elenco di studi DICOM corrispondenti.
  • search_dicom_series: restituisce un elenco di serie DICOM corrispondenti.
  • search_dicom_instances: restituisce un elenco di istanze DICOM corrispondenti.
  • retrieve_dicom_instance_rendered: restituisce una codifica Base64 di un'immagine sottoposta a rendering in formato JPEG per un'istanza DICOM associata all'UID di studio, serie e istanza SOP specificato.