Google Cloud Activation Guide

This guide explains how to prepare Google Cloud so the in-app environment wizard (Configuration → Credentials → Validation → Review & create) can create infrastructure successfully.

Core idea: prepare GCP first (usually with the gcloud CLI), then copy the project ID, region, and service account key into the product. Validation checks credential and project access, then provisioning verifies Cloud Run access and prepares Artifact Registry.

Quick path

1. Sign in with your Google account and select the correct project (§ Sign in and select the project).
2. Enable the required APIs: Cloud Run, Artifact Registry, Cloud Resource Manager (§ Enable APIs).
3. Create or reuse a service account and grant it the right roles (§ Service account).
4. Create a JSON key for the service account and save the file (§ Service account key).
5. Verify the key works against your project (§ Verify the service account).
6. Open the wizard: Configuration → Credentials → run Validation → Review & create (§ Complete the wizard).
7. If something fails, use § Common issues.

Prerequisites

• Access to the target Google Cloud project.
• Permission to grant IAM roles (for example Owner or IAM Admin) when binding roles to the service account.
• Billing enabled on the project (Cloud Run and Artifact Registry require it, even at $0 usage).
• gcloud CLI installed locally, or Cloud Shell from the GCP console.

The CLI is recommended because console labels and layout change more often than command-line flows.

Field reference

The wizard matches GCP outputs like this:

Project ID vs project number vs project name: the wizard wants the Project ID (e.g. my-mcp-project-481923), which is a lowercase string with optional digits/dashes — not the numeric project number and not the human-readable display name.

Region: use a valid Cloud Run region identifier (lowercase with hyphens). List supported regions:

gcloud run regions list

Service Account Key (JSON): paste the entire contents of the downloaded JSON file, including the { ... } braces. The wizard validates that it has type: "service_account", a PEM-formatted private_key, and a client_email ending in .iam.gserviceaccount.com. Google recommends avoiding user-managed service account keys when a safer alternative is available; use this key flow only when the deployment wizard requires a JSON key.

Prepare GCP with the CLI

Run the steps below as your GCP user/admin unless noted. Replace placeholders such as <PROJECT_ID> and <SA_NAME> with your values.

Sign in and select the project

gcloud auth login
gcloud projects list
gcloud config set project <PROJECT_ID>
gcloud config get-value project

Record the value of gcloud config get-value project — this becomes the wizard's Project ID.

Enable required APIs

These APIs are required for the MCP deployment path described here:

• run.googleapis.com — Cloud Run (runtime)
• artifactregistry.googleapis.com — Artifact Registry (private image storage)
• cloudresourcemanager.googleapis.com — Resource Manager (used by validation to fetch project metadata)

gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudresourcemanager.googleapis.com \
  --project <PROJECT_ID>

Verify (each should appear in the list):

gcloud services list --enabled --project <PROJECT_ID> \
  --filter="config.name:(run.googleapis.com OR artifactregistry.googleapis.com OR cloudresourcemanager.googleapis.com)" \
  --format="value(config.name)"

API enablement can take a minute or two to propagate. If validation fails immediately after enabling, wait and retry.

Create or reuse a service account

Reuse an existing service account if you already have one with the right roles.

Option A — new service account (quick setup):

gcloud iam service-accounts create <SA_NAME> \
  --display-name "MCP Deployment Service Account" \
  --project <PROJECT_ID>

The full email becomes <SA_NAME>@<PROJECT_ID>.iam.gserviceaccount.com.

Option B — console: IAM & Admin → Service Accounts → Create service account.

Grant IAM roles

Validation needs the service account to read project metadata; provisioning needs permission to manage Cloud Run services and Artifact Registry repositories. Grant these roles at project scope:

SA_EMAIL=<SA_NAME>@<PROJECT_ID>.iam.gserviceaccount.com

for ROLE in \
  roles/run.developer \
  roles/artifactregistry.admin \
  roles/iam.serviceAccountUser \
  roles/serviceusage.serviceUsageConsumer \
  roles/viewer
do
  gcloud projects add-iam-policy-binding <PROJECT_ID> \
    --member "serviceAccount:$SA_EMAIL" \
    --role "$ROLE"
done

Verify:

gcloud projects get-iam-policy <PROJECT_ID> \
  --flatten="bindings[].members" \
  --filter="bindings.members:$SA_EMAIL" \
  --format="value(bindings.role)"

You should see these roles listed for that service account.

Create a service account key

gcloud iam service-accounts keys create ./mcp-sa-key.json \
  --iam-account "$SA_EMAIL" \
  --project <PROJECT_ID>

This writes a JSON file. Open it and copy the entire contents when filling out the wizard. Treat this file as secret — anyone with it can act as the service account.

Verify the service account

This separates GCP misconfiguration from product issues. Activate the key and run a few read-only calls.

gcloud auth activate-service-account --key-file ./mcp-sa-key.json
gcloud config set project <PROJECT_ID>

# 1. Project is readable (matches the wizard's validation call)
gcloud projects describe <PROJECT_ID>

# 2. Cloud Run API is enabled and listable
gcloud run services list --region <REGION>

# 3. Artifact Registry is accessible
gcloud artifacts repositories list --location <REGION>

If all three calls succeed, authentication, project access, and the required APIs are working.

Switch back to your user account when done:

gcloud auth login
gcloud config set account <YOUR_EMAIL>

Complete the wizard in the app

Use the Field reference for definitions.

Configuration

• Environment Name — label in your app (for example gcp).
• Project ID — GCP project ID from § Sign in.
• Region — Cloud Run region, e.g. us-central1.

Credentials

• Service Account Key (JSON) — paste the full contents of the JSON file from § Service account key.

Validation

Run validation in the UI. It should succeed when the key parses cleanly and the service account can read the project via Resource Manager.

Cloud Run API access checks and Artifact Registry repository preparation happen during provisioning right after Review & create.

Review & create

After validation succeeds, finish creating the environment.

Common issues

Official references

• Cloud Run IAM roles
• Cloud Run regions
• Artifact Registry roles and permissions
• Best practices for managing service account keys
• Install the Google Cloud CLI

Appendix: Copy-paste activation script

The block below repeats Prepare GCP with the CLI in one place for convenience. Replace placeholders before running.

# --- As your GCP user ---

PROJECT_ID=<PROJECT_ID>
REGION=<REGION>           # e.g. us-central1
SA_NAME=<SA_NAME>         # e.g. mcp-deployer
SA_EMAIL="$SA_NAME@$PROJECT_ID.iam.gserviceaccount.com"

gcloud auth login
gcloud config set project "$PROJECT_ID"

# Enable APIs
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudresourcemanager.googleapis.com \
  --project "$PROJECT_ID"

# Create service account
gcloud iam service-accounts create "$SA_NAME" \
  --display-name "MCP Deployment Service Account" \
  --project "$PROJECT_ID"

# Grant roles
for ROLE in \
  roles/run.developer \
  roles/artifactregistry.admin \
  roles/iam.serviceAccountUser \
  roles/serviceusage.serviceUsageConsumer \
  roles/viewer
do
  gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member "serviceAccount:$SA_EMAIL" \
    --role "$ROLE"
done

# Create JSON key (treat as secret)
gcloud iam service-accounts keys create ./mcp-sa-key.json \
  --iam-account "$SA_EMAIL" \
  --project "$PROJECT_ID"

# --- Test as the service account ---

gcloud auth activate-service-account --key-file ./mcp-sa-key.json
gcloud config set project "$PROJECT_ID"

gcloud projects describe "$PROJECT_ID"
gcloud run services list --region "$REGION"
gcloud artifacts repositories list --location "$REGION"

After this succeeds, fill the wizard using the Field reference and complete § Complete the wizard.