Aloja servidores de MCP en Cloud Run

En esta guía, se muestra cómo alojar un servidor del protocolo de contexto del modelo (MCP) con transporte HTTP transmisible en Cloud Run y se proporciona orientación para autenticar clientes de MCP. Si es la primera vez que utilizas MCP, consulta la Guía de introducción para obtener más información.

El MCP es un protocolo abierto que estandariza la forma en que los agentes de IA interactúan con su entorno. El agente de IA aloja un cliente de MCP, y las herramientas y los recursos con los que interactúa son servidores de MCP. El cliente de MCP puede comunicarse con el servidor de MCP a través de dos tipos de transporte distintos:

Puedes alojar clientes y servidores de MCP en la misma máquina local, alojar un cliente de MCP de forma local y hacer que se comunique con servidores de MCP remotos alojados en una plataforma de nube como Cloud Run, o bien alojar el cliente y el servidor de MCP en una plataforma de nube.

Cloud Run admite el alojamiento de servidores de MCP con transporte HTTP transmitible, pero no servidores de MCP con transporte stdio.

La guía de esta página se aplica si desarrollas tu propio servidor de MCP o si usas uno existente.

Antes de comenzar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Configura tu entorno de desarrollo de Cloud Run en tu Google Cloud proyecto.
  7. Asegúrate de tener los permisos adecuados para implementar servicios y los roles de administrador de Cloud Run (roles/run.admin) y usuario de cuenta de servicio (roles/iam.serviceAccountUser) otorgados a tu cuenta.

    8. Obtén más información para otorgar los roles

    Console

    1. En la consola de Google Cloud , ve a la página IAM.

      Ir a IAM
    2. Selecciona el proyecto.
    3. Haz clic en Grant access.

    4. En el campo Principales nuevas, ingresa tu identificador de usuario. Por lo general, esta es la dirección de correo electrónico de la Cuenta de Google que se usa para implementar el servicio de Cloud Run.

    5. En la lista Seleccionar un rol, elige un rol.
    6. Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega cada rol adicional.
    7. Haz clic en Guardar.

    gcloud

    Para otorgar los roles de IAM necesarios a tu cuenta en tu proyecto, sigue estos pasos:

       gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL \
       --role=ROLE

    Reemplaza lo siguiente:

    • PROJECT_NUMBER por el número de tu proyecto Google Cloud .
    • PROJECT_ID por el ID de tu proyecto Google Cloud .
    • PRINCIPAL por la cuenta a la que agregarás la vinculación. Por lo general, esta es la dirección de correo electrónico de la Cuenta de Google que se usa para implementar el servicio de Cloud Run.
    • ROLE con el rol que agregarás a la cuenta del implementador.

    Aloja servidores de MCP remotos de SSE o HTTP aptos para transmisión

    Los servidores de MCP que usan eventos enviados por el servidor (SSE) o transporte HTTP transmitible se pueden alojar de forma remota desde sus clientes de MCP.

    Para implementar este tipo de servidor de MCP en Cloud Run, puedes implementarlo como una imagen de contenedor o como código fuente (comúnmente Node.js o Python), según cómo se empaquete el servidor de MCP.

    Imágenes de contenedor

    Los servidores de MCP remotos distribuidos como imágenes de contenedor son servidores web que escuchan solicitudes HTTP en un puerto específico, lo que significa que cumplen con el contrato de tiempo de ejecución del contenedor de Cloud Run y se pueden implementar en un servicio de Cloud Run.

    Para implementar un servidor de MCP empaquetado como una imagen de contenedor, debes tener la URL de la imagen de contenedor y el puerto en el que espera recibir solicitudes. Se pueden implementar con el siguiente comando de gcloud CLI:

    gcloud run deploy --image IMAGE_URL --port PORT

    Reemplaza lo siguiente:

    • IMAGE_URL por la URL de la imagen de contenedor, por ejemplo, us-docker.pkg.dev/cloudrun/container/mcp.
    • PORT con el puerto en el que escucha, por ejemplo, 3000.

    Fuentes

    Los servidores de MCP remotos que no se proporcionan como imágenes de contenedor se pueden implementar en Cloud Run desde sus fuentes, en particular si están escritos en Node.js o Python.

    1. Clona el repositorio de Git del servidor de MCP: 

      git clone https://github.com/ORGANIZATION/REPOSITORY.git

    2. Navega a la raíz del servidor de MCP: 

      cd REPOSITORY

    3. Realiza la implementación en Cloud Run con el siguiente comando de gcloud CLI: 

      gcloud run deploy --source .

    Después de implementar tu servidor de MCP HTTP en Cloud Run, el servidor de MCP obtiene una URL de HTTPS y la comunicación puede usar la compatibilidad integrada de Cloud Run para la transmisión de respuestas HTTP.

    Autentica clientes de MCP

    Según dónde alojaste el cliente de MCP, consulta la sección que te corresponda:

    Autentica clientes de MCP locales

    Si el agente de IA que aloja el cliente de MCP se ejecuta en una máquina local, usa uno de los siguientes métodos para autenticar el cliente de MCP:

    Para obtener más información, consulta la especificación de MCP sobre la autenticación.

    Permiso de IAM del invocador

    De forma predeterminada, la URL de los servicios de Cloud Run requiere que todas las solicitudes se autoricen con el rol de IAM de Invocador de Cloud Run (roles/run.invoker). Esta vinculación de política de IAM garantiza que se use un mecanismo de seguridad sólido para autenticar tu cliente de MCP local.

    Después de implementar tu servidor de MCP en un servicio de Cloud Run en una región, ejecuta el proxy de Cloud Run en tu máquina local para exponer de forma segura el servidor de MCP remoto a tu cliente con tus propias credenciales:

    gcloud run services proxy MCP_SERVER_NAME --region REGION --port=3000

    Reemplaza lo siguiente:

    • MCP_SERVER_NAME por el nombre del servicio de Cloud Run.
    • REGION por la Google Cloud región en la que implementaste el servicio Por ejemplo, europe-west1

    El comando proxy de Cloud Run crea un proxy local en el puerto 3000 que reenvía las solicitudes al servidor MCP remoto y, además, inyecta tu identidad.

    Actualiza el archivo de configuración del cliente de MCP con lo siguiente:

    {
  "mcpServers": {
    "cloud-run": {
      "url": "http://localhost:3000/sse"
    }
  }
}

    Si tu cliente de MCP no admite el atributo url, usa el paquete mcp-remote de npm:

    {
  "mcpServers": {
    "cloud-run": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/sse"
      ]
    }
  }
}

    Token de ID de OIDC

    Según si el cliente de MCP expone encabezados o usa una forma de proporcionar un transporte autenticado personalizado, puedes considerar autenticar el cliente de MCP con un token de ID de OIDC.

    Puedes usar varias bibliotecas de autenticación de Google para obtener un token de ID del entorno de ejecución, por ejemplo, la biblioteca de autenticación de Google para Python. Este token debe tener la reclamación de público correcta que coincida con la URL de *.run.app del servicio receptor, a menos que uses públicos personalizados. También debes incluir el token de ID en las solicitudes del cliente, como Authorization: Bearer <token value>.

    Si el cliente de MCP no expone encabezados ni transporte, usa otro método de autenticación.

    Autentica clientes de MCP que se ejecutan en Cloud Run

    Si el agente de IA que aloja el cliente de MCP se ejecuta en Cloud Run, usa uno de los siguientes métodos para autenticar el cliente de MCP:

    Implementa el servidor de MCP como un archivo adicional

    El servidor de MCP se puede implementar como un sidecar donde se ejecuta el cliente de MCP.

    No se requiere ninguna autenticación específica para este caso de uso, ya que el cliente y el servidor de MCP se encuentran en la misma instancia. El cliente puede conectarse al servidor de MCP a través de un puerto en http://localhost:PORT. Reemplaza PORT por un puerto diferente del que se usa para enviar solicitudes al servicio de Cloud Run.

    Autentica servicio a servicio

    Si el servidor y el cliente de MCP se ejecutan como servicios de Cloud Run distintos, consulta Autenticación de servicio a servicio.

    Usa Cloud Service Mesh

    Un agente que aloja un cliente de MCP puede conectarse a un servidor de MCP remoto con Cloud Service Mesh.

    Puedes configurar el servicio del servidor de MCP para que tenga un nombre corto en la malla, y el cliente de MCP puede comunicarse con el servidor de MCP usando el nombre corto http://mcp-server. La malla administra la autenticación.

    ¿Qué sigue?