Usar a API Cloud Healthcare com o MCP e outros agentes

Este guia mostra como usar a MCP Toolbox for Databases para conectar a API Cloud Healthcare a vários ambientes de desenvolvimento integrado (IDEs) e ferramentas de desenvolvedor. Ele usa o Protocolo de Contexto de Modelo (MCP), um protocolo aberto para conectar modelos de linguagem grandes (LLMs) a fontes de dados, como conjuntos de dados de saúde, permitindo pesquisar e interagir com dados de saúde diretamente nas ferramentas atuais.

Este guia demonstra o processo de conexão para os seguintes IDEs:

  • Cursor
  • Windsurf (antigo Codeium)
  • Visual Studio Code (Copilot)
  • Cline (extensão do VS Code)
  • Claude desktop
  • Claude code

Antes de começar

  1. No Google Cloud console do, na página do seletor de projetos, selecione ou crie um Google Cloud projeto do.

  2. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  3. Ative a API Cloud Healthcare no Google Cloud projeto.

  4. Configure os papéis e permissões necessários para concluir essa tarefa. Você vai precisar do papel de leitor de recursos FHIR do Healthcare (roles/healthcare.fhirResourceReader) e do papel de leitor de DICOM do Healthcare (roles/healthcare.dicomViewer) ou permissões equivalentes do IAM para se conectar ao projeto.

  5. Configure o Application Default Credentials (ADC) para seu ambiente.

Instalar a caixa de ferramentas MCP

A caixa de ferramentas funciona como um servidor de Protocolo de Contexto de Modelo (MCP) de código aberto que fica entre o IDE e a API Cloud Healthcare, fornecendo um plano de controle seguro e eficiente para suas ferramentas de IA.

  1. Faça o download da versão mais recente da caixa de ferramentas MCP como um binário. Selecione o binário correspondente ao seu sistema operacional (SO) e à arquitetura de CPU. É necessário usar a versão v0.19.1 ou mais recente da caixa de ferramentas MCP:

    linux/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/linux/amd64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas MCP, por exemplo, v0.19.1.

    macOS darwin/arm64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/arm64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas MCP, por exemplo, v0.19.1.

    macOS darwin/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/darwin/amd64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas MCP, por exemplo, v0.19.1.

    windows/amd64

    curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/VERSION/windows/amd64/toolbox

    Substitua VERSION pela versão da caixa de ferramentas MCP, por exemplo, v0.19.1.

  2. Torne o binário executável:

    chmod +x toolbox

  3. Verifique a instalação:

    ./toolbox --version

Configurar clientes e conexões

Esta seção explica como conectar a API Cloud Healthcare às suas ferramentas.

Claude code

  1. Instale o Claude Code.
  2. Crie um arquivo .mcp.json na raiz do projeto, se ele não existir.
  3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e salve: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Reinicie o Claude Code para carregar as novas configurações. Quando ele for reaberto, a ferramenta vai indicar que o servidor MCP configurado foi detectado.

Claude desktop

  1. Abra o Claude Desktop e acesse Configurações.
  2. Na guia Desenvolvedor, clique em Editar configuração para abrir o arquivo de configuração.
  3. Adicione a configuração, substitua as variáveis de ambiente pelos seus valores e salve: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Reinicie o Claude Desktop.
  5. A nova tela de chat mostra um ícone de martelo (MCP) com o novo servidor MCP.

Cline

  1. Abra a extensão Cline no VS Code e toque no ícone Servidores MCP.
  2. Toque em Configurar servidores MCP para abrir o arquivo de configuração.
  3. Adicione a configuração a seguir, substitua as variáveis de ambiente com seus valores e salve: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }

Um status ativo verde aparece depois que o servidor se conecta.

Cursor

  1. Crie o diretório .cursor na raiz do projeto, se ele não existir.
  2. Crie o arquivo .cursor/mcp.json, se ele não existir, e abra-o.
  3. Adicione a configuração a seguir, substitua as variáveis de ambiente com seus valores e salve: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Abra o Cursor e acesse Configurações > Configurações do cursor > MCP. Um status ativo verde aparece quando o servidor se conecta.

Visual Studio Code (Copilot)

  1. Abra o VS Code e crie um diretório .vscode na raiz do projeto, se ele não existir.
  2. Crie o arquivo .vscode/mcp.json, se ele não existir, e abra-o.
  3. Adicione a configuração a seguir, substitua as variáveis de ambiente com seus valores e salve: 
            {
          "servers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }
          }
        }
  4. Atualize a janela do VS Code. A extensão compatível com MCP detecta automaticamente a configuração e inicia o servidor.

Windsurf

  1. Abra o Windsurf e acesse o assistente do Cascade.
  2. Clique no ícone MCP e em Configurar para abrir o arquivo de configuração.
  3. Adicione a configuração a seguir, substitua as variáveis de ambiente com seus valores e salve: 
            {
          "mcpServers": {
            "healthcare": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","cloud-healthcare","--stdio"],
              "env": {
                "HEALTHCARE_PROJECT": "PROJECT_ID",
                "HEALTHCARE_REGION": "REGION",
                "HEALTHCARE_DATASET": "DATASET_ID"
              }
            }

          }
        }

Observação:a variável de ambiente HEALTHCARE_PROJECT especifica o ID do projeto default Google Cloud para a caixa de ferramentas MCP usar. Todas as operações, como pesquisar pacientes ou procurar instâncias DICOM, são executadas nesse projeto.

Usar as ferramentas

Sua ferramenta de IA agora está conectada à API Cloud Healthcare usando o MCP. Peça ao assistente de IA para pesquisar pacientes FHIR, recuperar registros de um determinado paciente, procurar um estudo DICOM ou listar os armazenamentos DICOM no conjunto de dados.

As seguintes ferramentas estão disponíveis para o LLM:

  • get_dataset: recupera os detalhes de um conjunto de dados.
  • list_datasets: lista conjuntos de dados de saúde em um projeto.
  • list_fhir_stores: lista os armazenamentos FHIR no conjunto de dados fornecido.
  • list_dicom_stores: lista os armazenamentos DICOM no conjunto de dados fornecido.
  • get_fhir_store: recebe a configuração do repositório FHIR especificado.
  • get_fhir_store_metrics: recebe métricas associadas ao repositório FHIR.
  • get_fhir_resource: recebe o conteúdo de um recurso FHIR.
  • get_fhir_resource_version: recebe o conteúdo de uma versão (atual ou histórica) de um recurso FHIR.
  • fhir_patient_everything: recupera um recurso de paciente FHIR e recursos relacionados a esse paciente.
  • fhir_patient_search: pesquisa recursos de pacientes FHIR no repositório FHIR de acordo com os critérios especificados.
  • get_dicom_store: recebe a configuração do repositório DICOM especificado.
  • get_dicom_store_metrics: recebe métricas associadas ao repositório DICOM.
  • search_dicom_studies: retorna uma lista de estudos DICOM correspondentes.
  • search_dicom_series: retorna uma lista de séries DICOM correspondentes.
  • search_dicom_instances: retorna uma lista de instâncias DICOM correspondentes.
  • retrieve_dicom_instance_rendered: retorna uma codificação em base64 de uma imagem renderizada no formato JPEG para uma instância DICOM associada ao estudo, série e UID da instância SOP fornecidos.