βοΈ Deploying MCP Gateway on Google Cloud Run¶
MCP Gateway can be deployed to Google Cloud Run, a fully managed, autoscaling platform for containerized applications. This guide provides step-by-step instructions to provision PostgreSQL and Redis backends, deploy the container, configure environment variables, authenticate using JWT, and monitor logs-all optimized for cost-efficiency.
β Overview¶
Google Cloud Run is an ideal platform for MCP Gateway due to its:
- Serverless and cost-efficient model with scale-to-zero capability.
- Public HTTPS endpoints with automatic TLS configuration.
- Seamless integration with Cloud SQL (PostgreSQL) and Memorystore (Redis).
- Compatibility with public container registries like GitHub's
ghcr.io
.
You can deploy the public image directly:
π Prerequisites¶
1. Install and Initialize Google Cloud CLI (gcloud
)¶
Install the Google Cloud SDK:
- macOS (Homebrew):
- Debian/Ubuntu:
These steps also apply to WSL2 running Ubuntu.
# Update package lists and install necessary utilities
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates gnupg curl
# Import the Google Cloud public key securely
# This is for newer distributions (Debian 9+ or Ubuntu 18.04+).
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
# Add the Google Cloud SDK distribution URI as a package source
# This is for newer distributions, ensuring packages are signed by the key we just added.
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
# Update your package lists again to recognize the new repository
sudo apt-get update
# Install the Google Cloud CLI
sudo apt-get install -y google-cloud-cli
- Windows (PowerShell):
After installation, initialize the CLI:
Authenticate with your Google Cloud account:
Set a project ID:
2. Enable Required APIs¶
Enable the necessary Google Cloud APIs:
# This might take a minute..
gcloud services enable \
run.googleapis.com \
sqladmin.googleapis.com \
redis.googleapis.com
3. Install Docker¶
Ensure Docker is installed for local testing and JWT token generation. Visit Docker's official website for installation instructions.
4. Set Environment Variables¶
Prepare the following environment variables:
Variable | Description |
---|---|
JWT_SECRET_KEY | Secret key for signing JWT tokens |
BASIC_AUTH_USER | Username for HTTP Basic Authentication |
BASIC_AUTH_PASSWORD | Password for HTTP Basic Authentication |
AUTH_REQUIRED | Set to true to enforce authentication |
DATABASE_URL | PostgreSQL connection string |
REDIS_URL | Redis connection string |
CACHE_TYPE | Set to redis for production environments |
PORT | Port number the application listens on (e.g., 4444 ) |
Consider creating a .env.gcr
file where you will record the various settings used during deployment.
# βββ Google Cloud project βββββββββββββββββββββββββββββββββββ
PROJECT_ID=
REGION=us-central1
SERVICE_NAME=mcpgateway
# βββ Authentication βββββββββββββββββββββββββββββββββββββββββ
JWT_SECRET_KEY=
BASIC_AUTH_USER=
BASIC_AUTH_PASSWORD=
AUTH_REQUIRED=true
# βββ Cloud SQL (PostgreSQL) βββββββββββββββββββββββββββββββββ
SQL_INSTANCE=mcpgw-db
SQL_REGION=us-central1
DATABASE_URL=postgresql://postgres:<PASSWORD>@<SQL_IP>:5432/mcpgw
# βββ Memorystore (Redis) ββββββββββββββββββββββββββββββββββββ
REDIS_INSTANCE=mcpgw-redis
REDIS_REGION=us-central1
REDIS_URL=redis://<REDIS_IP>:6379/0
CACHE_TYPE=redis
# βββ Application ββββββββββββββββββββββββββββββββββββββββββββ
PORT=4444
βοΈ Setup Steps¶
1. Provision Cloud SQL (PostgreSQL)¶
Create a PostgreSQL instance using the db-f1-micro
tier for cost efficiency:
# POSTGRES_16 and POSTGRES_17 default to Enterprise Plus; adding --edition=ENTERPRISE lets you pick db-f1-micro
gcloud sql instances create mcpgw-db \
--database-version=POSTGRES_17 \
--edition=ENTERPRISE \
--tier=db-f1-micro \
--region=us-central1
Set the password for the postgres
user:
Create the mcpgw
database:
Retrieve the IP address of the instance:
Note: The
db-f1-micro
tier is a shared-core instance designed for low-cost development and testing environments. It is not covered by the Cloud SQL SLA.
2. Provision Memorystore (Redis)¶
Create a Redis instance using the Basic Tier with 1 GiB capacity:
Retrieve the host IP address:
Note: The Basic Tier provides a standalone Redis instance suitable for applications that can tolerate potential data loss during failures.
3. Deploy to Google Cloud Run¶
Cloud Run only accepts container images that live in Artifact Registry or the older Container Registry endpoints; anything pulled from the public internet (for example ghcr.io) must first be proxied or copied into Artifact Registry.
Set Your Project ID¶
Begin by setting your Google Cloud project ID as an environment variable:
Replace "your-project-id"
with your actual Google Cloud project ID.
Enable Required APIs¶
Ensure that the necessary Google Cloud APIs are enabled:
Create a Remote Repository¶
Set up a remote repository in Artifact Registry that proxies GitHub Container Registry (GHCR):
gcloud artifacts repositories create ghcr-remote \
--project=$PROJECT_ID \
--repository-format=docker \
--location=us-central1 \
--description="Proxy for GitHub Container Registry" \
--mode=remote-repository \
--remote-docker-repo=https://ghcr.io
Retrieve Cloud SQL Instance Connection Name¶
It will output something like this:
Allow ingress to your database.¶
Consider only allowing the Cloud Run IP range.
Deploy the MCP Gateway container with minimal resource allocation:¶
gcloud run deploy mcpgateway \
--image=us-central1-docker.pkg.dev/$PROJECT_ID/ghcr-remote/ibm/mcp-context-forge:latest
--region=us-central1 \
--platform=managed \
--allow-unauthenticated \
--port=4444 \
--cpu=1 \
--memory=512i \
--max-instances=1 \
--set-env-vars=\
JWT_SECRET_KEY=jwt-secret-key,\
BASIC_AUTH_USER=admin,\
BASIC_AUTH_PASSWORD=changeme,\
AUTH_REQUIRED=true,\
DATABASE_URL=postgresql://postgres:mysecretpassword@<SQL_IP>:5432/mcpgw,\
REDIS_URL=redis://<REDIS_IP>:6379/0,\
CACHE_TYPE=redis,\
HOST=0.0.0.0,\
GUNICORN_WORKERS=1
Replace
<SQL_IP>
and<REDIS_IP>
with the actual IP addresses obtained from the previous steps. Do not leave out the HOST=0.0.0.0 to ensure the container listens on all ports, or the container engine won't be able to reach the container. Setting the number of GUNICORN_WORKERS lets you control how much memory the service consumes.
Check the logs¶
¶
Check that the database is created:¶
You can use any PostgreSQL client, such as psql
. You should see the list of tables when using dt;
psql postgresql://postgres:mysecretpassword@<SQL_IP>:5432/mcpgw
mcpgw=> \dt;
List of relations
Schema | Name | Type | Owner
--------+------------------------------+-------+----------
public | gateways | table | postgres
public | mcp_messages | table | postgres
public | mcp_sessions | table | postgres
public | prompt_gateway_association | table | postgres
public | prompt_metrics | table | postgres
public | prompts | table | postgres
public | resource_gateway_association | table | postgres
public | resource_metrics | table | postgres
public | resource_subscriptions | table | postgres
public | resources | table | postgres
public | server_metrics | table | postgres
public | server_prompt_association | table | postgres
public | server_resource_association | table | postgres
public | server_tool_association | table | postgres
public | servers | table | postgres
public | tool_gateway_association | table | postgres
public | tool_metrics | table | postgres
public | tools | table | postgres
(18 rows)
π Authentication and Access¶
Generate a JWT Bearer Token¶
Use the MCP Gateway container to generate a JWT token:
docker run -it --rm ghcr.io/ibm/mcp-context-forge:0.6.0 \
python3 -m mcpgateway.utils.create_jwt_token -u admin --secret jwt-secret-key
Export the token as an environment variable:
Perform Smoke Tests¶
Test the /health
, /version
, and /tools
endpoints:
# Check that the service is healthy
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
https://<your-cloud-run-url>/health
# Check that version reports the version and show Postgres/Redis as connected
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
https://<your-cloud-run-url>/health
# Check that tools return an empty list []
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
https://<your-cloud-run-url>/tools
Replace
<your-cloud-run-url>
with the URL provided after deploying the service.
π Logs and Monitoring¶
View Logs via CLI¶
Tailing real-time logs requires google-cloud-cli-log-streaming
. Ex: sudo apt-get install google-cloud-cli-log-streaming
:
Access Logs via Console¶
Navigate to the Cloud Run Console and select your service to view logs and metrics.
π¦ GitHub Actions Deployment (Optional)¶
Automate builds and deployments using GitHub Actions. Refer to the workflow file:
This workflow:
- Restores and updates a local BuildKit layer cache.
- Builds the Docker image from
Containerfile.lite
. - Pushes the image to Google Artifact Registry.
- Deploys to Google Cloud Run with
--max-instances=1
.
Setting up permissions for Google Cloud Run deployment¶
Instead of project-wide permissions, grant permissions on specific resources:
# Create service account
gcloud iam service-accounts create github-mcpgateway \
--display-name="GitHub MCP Gateway Deploy"
# Grant permission ONLY on the specific Cloud Run service
gcloud run services add-iam-policy-binding mcpgateway \
--region=us-central1 \
--member="serviceAccount:github-mcpgateway@YOUR-PROJECT-ID.iam.gserviceaccount.com" \
--role="roles/run.developer"
# Grant permission ONLY on the specific Artifact Registry repository
gcloud artifacts repositories add-iam-policy-binding mcpgateway \
--location=us-central1 \
--member="serviceAccount:github-mcpgateway@YOUR-PROJECT-ID.iam.gserviceaccount.com" \
--role="roles/artifactregistry.writer"
# Create the key
gcloud iam service-accounts keys create restricted-key.json \
--iam-account=github-mcpgateway@YOUR-PROJECT-ID.iam.gserviceaccount.com
π Notes and Tips¶
-
HTTPS by Default: Cloud Run services are accessible over HTTPS without additional configuration.
-
Custom Domains: You can map custom domains via the Cloud Run settings.
-
Secret Management: Consider using Secret Manager for managing sensitive environment variables.
-
Cold Starts: To reduce cold start latency, set a minimum number of instances:
- Monitoring: Utilize Cloud Monitoring for detailed metrics and alerts.
π§© Feature Summary¶
Feature | Supported |
---|---|
HTTPS (built-in) | β |
Custom domains | β |
PostgreSQL (Cloud SQL) | β |
Redis (Memorystore) | β |
Auto-scaling | β |
Scale-to-zero | β |
Max instance limit | β |
π§ Additional Resources¶
- Cloud Run Documentation
- Cloud SQL for PostgreSQL Documentation
- Memorystore for Redis Documentation
- Google Cloud SDK Installation Guide
- Cloud Run Pricing
- Cloud SQL Pricing
- Memorystore Pricing
By following this guide, you can deploy MCP Gateway on Google Cloud Run using the most cost-effective configurations, ensuring efficient resource utilization and seamless scalability.