Skip to main content

Google Cloud Run MCP Server

Create a powerful Model Context Protocol (MCP) server for Google Cloud Run in minutes with our AI Gateway. This guide walks you through setting up seamless serverless container deployment with automatic scaling and instant API authentication.

About Google Cloud Run API​

Google Cloud Run is a fully managed serverless platform that automatically scales stateless containers. The API enables comprehensive management of services, revisions, routes, and configurations, providing a complete serverless container solution.

Key Capabilities​

  • Serverless Containers: Deploy any containerized app
  • Automatic Scaling: Scale to zero, scale to thousands
  • Traffic Management: Blue/green, canary deployments
  • Custom Domains: HTTPS with managed certificates
  • Event-driven: Respond to HTTP, Pub/Sub, Eventarc
  • Regional: Multi-region deployment options
  • Concurrency: Control request handling
  • Security: IAM, Binary Authorization, VPC

API Features​

  • RESTful API: Standard Google Cloud API
  • gRPC Support: High-performance option
  • OAuth 2.0: Secure authentication
  • Service Management: Full lifecycle control
  • Revision Control: Immutable deployments
  • Traffic Splitting: Gradual rollouts
  • Monitoring: Integrated with Cloud Monitoring
  • Async Operations: Long-running tasks

What You Can Do with Cloud Run MCP Server​

The MCP server transforms Cloud Run API into a natural language interface, enabling AI agents to:

Service Deployment​

  • Deploy Services

    • "Deploy container image to Cloud Run"
    • "Create service from source code"
    • "Update service configuration"
    • "Deploy from Artifact Registry"

  • Service Management

    • "List all services"
    • "Get service details"
    • "Delete unused service"
    • "Update service metadata"

  • Multi-Region Deploy

    • "Deploy to multiple regions"
    • "Configure regional settings"
    • "Set up global load balancing"
    • "Manage regional traffic"

Revision Management​

  • Deploy Revisions

    • "Create new revision"
    • "Update container image"
    • "Change environment variables"
    • "Modify resource limits"

  • Revision Control

    • "List service revisions"
    • "Tag revision as stable"
    • "Delete old revisions"
    • "Compare revisions"

  • Rollback

    • "Rollback to previous revision"
    • "Quick rollback on errors"
    • "Restore configuration"
    • "Emergency revert"

Traffic Management​

  • Traffic Splitting

    • "Split traffic 50/50"
    • "Canary deployment 10%"
    • "Blue-green deployment"
    • "Gradual rollout"

  • Custom Domains

    • "Map custom domain"
    • "Configure SSL certificate"
    • "Set up domain mapping"
    • "Manage certificates"

  • Load Balancing

    • "Configure load balancer"
    • "Set up health checks"
    • "Regional failover"
    • "Traffic policies"

Configuration​

  • Container Settings

    • "Set memory limits"
    • "Configure CPU allocation"
    • "Set concurrency limits"
    • "Configure timeout"

  • Environment Variables

    • "Add environment variable"
    • "Update configuration"
    • "Use Secret Manager"
    • "Set runtime variables"

  • Scaling Configuration

    • "Set min/max instances"
    • "Configure autoscaling"
    • "Set scale-to-zero delay"
    • "Adjust scaling metrics"

Security & Access​

  • IAM Management

    • "Grant public access"
    • "Require authentication"
    • "Set service account"
    • "Configure permissions"

  • Network Security

    • "Enable VPC connector"
    • "Configure egress"
    • "Set ingress rules"
    • "Private endpoints"

  • Binary Authorization

    • "Enable image verification"
    • "Set attestation requirements"
    • "Configure policies"
    • "Vulnerability scanning"

Monitoring & Logging​

  • Service Metrics

    • "Show request count"
    • "Check latency metrics"
    • "Monitor error rates"
    • "View container metrics"

  • Logging

    • "View service logs"
    • "Search error logs"
    • "Export logs"
    • "Set log retention"

  • Alerts

    • "Create uptime alert"
    • "Set latency threshold"
    • "Configure error alerts"
    • "Budget alerts"

Integration​

  • Event Triggers

    • "Connect Pub/Sub trigger"
    • "Set up Eventarc"
    • "Configure Cloud Tasks"
    • "Schedule with Cloud Scheduler"

  • CI/CD Integration

    • "Deploy from Cloud Build"
    • "GitHub integration"
    • "GitLab CI/CD"
    • "Artifact Registry"

  • Service Mesh

    • "Connect to Anthos"
    • "Configure Istio"
    • "Service discovery"
    • "Traffic management"

Prerequisites​

  • Access to Cequence AI Gateway
  • Google Cloud Project
  • Cloud Run API enabled
  • Service account with permissions

Step 1: Configure Cloud Run API Access​

1.1 Enable Cloud Run API​

  1. Go to Google Cloud Console
  2. Navigate to APIs & Services Library
  3. Search for "Cloud Run API"
  4. Click Enable

1.2 Create Service Account​

  1. Go to IAM & Admin Service Accounts
  2. Click Create Service Account
  3. Configure:
    • Name: "AI Gateway Cloud Run"
    • Role: Cloud Run Admin
  4. Create and download JSON key

1.3 Set Project Configuration​

Note:

  • Project ID
  • Default region (e.g., us-central1)
  • Artifact Registry location

1.4 Configure Permissions​

Required roles:

  • run.admin - Full Cloud Run access
  • iam.serviceAccountUser - Use service accounts
  • storage.objectViewer - Access container images

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find Cloud Run API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL: https://run.googleapis.com/v2
  2. Project ID: Your GCP project
  3. Region: Default deployment region
  4. Click Next

Step 6: MCP Server Configuration​

  1. Name: "Cloud Run Serverless"
  2. Description: "Serverless container platform"
  3. Timeout: 120 seconds
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: Service Account
  2. Upload service account JSON key
  3. Or configure OAuth 2.0:
    • Client ID and Secret
    • Required scopes
  4. Test connection

Available Cloud Run API Operations​

Service APIs​

  • Service Management

    • Create service
    • Get service
    • Update service
    • Delete service
    • List services

  • Service Configuration

    • Update config
    • Set annotations
    • Manage labels

Revision APIs​

  • Revision Management
    • List revisions
    • Get revision
    • Delete revision
    • Tag revision

Route APIs​

  • Traffic Management
    • Get routes
    • Update traffic
    • Set percentages

Domain Mapping APIs​

  • Custom Domains
    • Create mapping
    • List mappings
    • Delete mapping
    • Verify domain

Job APIs (Cloud Run Jobs)​

  • Job Management
    • Create job
    • Run job
    • List executions
    • Delete job

Step 8-10: Complete Setup​

Configure security settings, choose deployment options, and deploy your server.

Using Your Cloud Run MCP Server​

With Claude Desktop​

{
  "servers": {
    "cloud-run": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "service-account",
        "credentials": "base64-encoded-service-account-key"
      },
      "config": {
        "project_id": "your-project-id",
        "region": "us-central1"
      }
    }
  }
}

Natural Language Commands​

  • "Deploy my Node.js app from gcr.io/myproject/app:latest"
  • "Split traffic 80/20 between stable and canary"
  • "Scale service to handle 1000 concurrent requests"
  • "Show me error logs from the last hour"
  • "Create scheduled job to run every midnight"

API Integration Example​

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'service-account',
    credentials: serviceAccountKey
  }
});

// Deploy a new service
const service = await mcpClient.cloudRun.createService({
  name: 'hello-world-api',
  location: 'us-central1',
  template: {
    metadata: {
      annotations: {
        'run.googleapis.com/execution-environment': 'gen2',
        'run.googleapis.com/startup-cpu-boost': 'true'
      }
    },
    spec: {
      containerConcurrency: 100,
      timeoutSeconds: 300,
      serviceAccountName: 'api-service@project.iam.gserviceaccount.com',
      containers: [{
        image: 'gcr.io/myproject/hello-api:v1.0.0',
        ports: [{
          name: 'http1',
          containerPort: 8080
        }],
        env: [
          {
            name: 'NODE_ENV',
            value: 'production'
          },
          {
            name: 'DATABASE_URL',
            valueFrom: {
              secretKeyRef: {
                name: 'database-url',
                key: 'latest'
              }
            }
          }
        ],
        resources: {
          limits: {
            cpu: '2',
            memory: '2Gi'
          }
        },
        startupProbe: {
          httpGet: {
            path: '/health',
            port: 8080
          },
          initialDelaySeconds: 0,
          periodSeconds: 10,
          timeoutSeconds: 1,
          failureThreshold: 3
        },
        livenessProbe: {
          httpGet: {
            path: '/health',
            port: 8080
          },
          periodSeconds: 10,
          timeoutSeconds: 1,
          failureThreshold: 3
        }
      }]
    }
  },
  traffic: [{
    percent: 100,
    latestRevision: true
  }]
});

console.log(`Service deployed: ${service.status.url}`);

// Update service with new image
const updatedService = await mcpClient.cloudRun.updateService({
  name: `projects/${projectId}/locations/us-central1/services/hello-world-api`,
  updateMask: 'spec.template.spec.containers',
  service: {
    spec: {
      template: {
        spec: {
          containers: [{
            image: 'gcr.io/myproject/hello-api:v1.1.0',
            // Inherit other settings
          }]
        }
      }
    }
  }
});

// Implement canary deployment
const canaryDeployment = await mcpClient.cloudRun.updateServiceTraffic({
  name: service.name,
  traffic: [
    {
      revisionName: 'hello-world-api-00001-abc', // Current stable
      percent: 90,
      tag: 'stable'
    },
    {
      revisionName: 'hello-world-api-00002-def', // New canary
      percent: 10,
      tag: 'canary'
    }
  ]
});

// Create a Cloud Run Job
const job = await mcpClient.cloudRun.createJob({
  name: 'data-processing-job',
  location: 'us-central1',
  template: {
    metadata: {
      annotations: {
        'run.googleapis.com/launch-stage': 'GA'
      }
    },
    spec: {
      parallelism: 10,
      taskCount: 100,
      template: {
        spec: {
          maxRetries: 3,
          timeoutSeconds: 3600,
          serviceAccountName: 'job-runner@project.iam.gserviceaccount.com',
          containers: [{
            image: 'gcr.io/myproject/batch-processor:latest',
            env: [
              {
                name: 'BATCH_SIZE',
                value: '1000'
              },
              {
                name: 'GCS_BUCKET',
                value: 'gs://myproject-data'
              }
            ],
            resources: {
              limits: {
                cpu: '4',
                memory: '8Gi'
              }
            }
          }],
          volumes: [{
            name: 'cloudsql',
            cloudSqlInstance: {
              instances: ['myproject:us-central1:myinstance']
            }
          }],
          vpcAccess: {
            connector: 'projects/myproject/locations/us-central1/connectors/my-vpc',
            egress: 'PRIVATE_RANGES_ONLY'
          }
        }
      }
    }
  }
});

// Execute the job
const execution = await mcpClient.cloudRun.runJob({
  name: job.name,
  overrides: {
    containerOverrides: [{
      env: [{
        name: 'EXECUTION_ID',
        value: `exec-${Date.now()}`
      }]
    }]
  }
});

console.log(`Job execution started: ${execution.name}`);

// Configure custom domain
const domainMapping = await mcpClient.cloudRun.createDomainMapping({
  parent: `projects/${projectId}/locations/us-central1`,
  domainMappingId: 'api.example.com',
  domainMapping: {
    spec: {
      routeName: service.name,
      certificateMode: 'AUTOMATIC',
      forceOverride: false
    },
    metadata: {
      name: 'api.example.com',
      namespace: projectId,
      annotations: {
        'run.googleapis.com/launch-stage': 'GA'
      }
    }
  }
});

// Set up VPC connector for private access
const vpcService = await mcpClient.cloudRun.updateService({
  name: service.name,
  updateMask: 'spec.template.spec.vpcAccess',
  service: {
    spec: {
      template: {
        spec: {
          vpcAccess: {
            connector: 'projects/myproject/locations/us-central1/connectors/my-vpc',
            egress: 'ALL_TRAFFIC'
          }
        }
      }
    }
  }
});

// Configure autoscaling
const autoscaledService = await mcpClient.cloudRun.updateService({
  name: service.name,
  updateMask: 'spec.template.metadata.annotations',
  service: {
    spec: {
      template: {
        metadata: {
          annotations: {
            'autoscaling.knative.dev/minScale': '1',
            'autoscaling.knative.dev/maxScale': '100',
            'autoscaling.knative.dev/target': '80',
            'autoscaling.knative.dev/metric': 'concurrency'
          }
        }
      }
    }
  }
});

// Enable Binary Authorization
const secureService = await mcpClient.cloudRun.updateService({
  name: service.name,
  updateMask: 'metadata.annotations',
  service: {
    metadata: {
      annotations: {
        'binaryauthorization.grafeas.io/break-glass': 'false',
        'run.googleapis.com/binary-authorization': 'default'
      }
    }
  }
});

// Monitor service metrics
const metrics = await mcpClient.cloudRun.getServiceMetrics({
  name: service.name,
  metrics: ['request_count', 'request_latencies', 'container_cpu_utilization'],
  interval: {
    startTime: new Date(Date.now() - 3600000), // Last hour
    endTime: new Date()
  }
});

console.log('\nService Metrics:');
console.log(`Requests: ${metrics.requestCount.total}`);
console.log(`Average Latency: ${metrics.requestLatencies.mean}ms`);
console.log(`CPU Usage: ${metrics.cpuUtilization.mean * 100}%`);

// Create uptime check
const uptimeCheck = await mcpClient.cloudRun.createUptimeCheck({
  displayName: 'Hello API Health Check',
  monitoredResource: {
    type: 'cloud_run_revision',
    labels: {
      service_name: 'hello-world-api',
      location: 'us-central1',
      project_id: projectId
    }
  },
  httpCheck: {
    path: '/health',
    port: 443,
    requestMethod: 'GET',
    useSsl: true,
    validateSsl: true
  },
  period: '60s',
  timeout: '10s'
});

// Set up Eventarc trigger
const trigger = await mcpClient.cloudRun.createEventarcTrigger({
  name: 'pubsub-trigger',
  location: 'us-central1',
  eventFilters: [{
    attribute: 'type',
    value: 'google.cloud.pubsub.topic.v1.messagePublished'
  }],
  destination: {
    cloudRun: {
      service: service.name,
      path: '/webhook',
      region: 'us-central1'
    }
  },
  transport: {
    pubsub: {
      topic: 'projects/myproject/topics/events'
    }
  },
  serviceAccount: 'eventarc-trigger@project.iam.gserviceaccount.com'
});

// Blue-green deployment
const blueGreenDeploy = async (newImage) => {
  // Deploy new revision (green)
  const greenRevision = await mcpClient.cloudRun.updateService({
    name: service.name,
    service: {
      spec: {
        template: {
          metadata: {
            name: `${service.metadata.name}-green`
          },
          spec: {
            containers: [{
              image: newImage
            }]
          }
        }
      },
      traffic: [
        {
          revisionName: service.status.latestReadyRevisionName,
          percent: 100,
          tag: 'blue'
        },
        {
          latestRevision: true,
          percent: 0,
          tag: 'green'
        }
      ]
    }
  });
  
  // Test green deployment
  const testResult = await testDeployment(greenRevision.status.url + '-green');
  
  if (testResult.success) {
    // Switch traffic to green
    await mcpClient.cloudRun.updateServiceTraffic({
      name: service.name,
      traffic: [{
        latestRevision: true,
        percent: 100
      }]
    });
  }
};

// Create scheduled job
const scheduledJob = await mcpClient.cloudRun.createCloudSchedulerJob({
  name: 'nightly-cleanup',
  schedule: '0 2 * * *', // 2 AM daily
  timeZone: 'America/New_York',
  httpTarget: {
    uri: `${service.status.url}/cleanup`,
    httpMethod: 'POST',
    headers: {
      'Authorization': `Bearer ${await getIdToken()}`
    },
    body: JSON.stringify({
      daysToKeep: 30
    })
  },
  retryConfig: {
    retryCount: 3,
    minBackoffDuration: '5s',
    maxBackoffDuration: '60s'
  }
});

// Export service configuration
const exportedConfig = await mcpClient.cloudRun.exportService({
  name: service.name,
  format: 'YAML'
});

console.log('Exported service config:', exportedConfig);

// List all services with filtering
const services = await mcpClient.cloudRun.listServices({
  parent: `projects/${projectId}/locations/-`,
  filter: 'metadata.labels.environment=production',
  pageSize: 100
});

console.log(`Found ${services.services.length} production services`);

Common Use Cases​

Web Applications​

  • API backends
  • Web frontends
  • Microservices
  • GraphQL servers

Data Processing​

  • Batch jobs
  • ETL pipelines
  • Image processing
  • Report generation

Event-driven​

  • Webhook handlers
  • Pub/Sub processors
  • Event streaming
  • Async workflows

Scheduled Tasks​

  • Cron jobs
  • Maintenance tasks
  • Data synchronization
  • Cleanup operations

Best Practices​

  1. Container Design:

    • Keep images small
    • Use multi-stage builds
    • Handle signals properly
    • Log to stdout/stderr

  2. Configuration:

    • Use environment variables
    • Store secrets in Secret Manager
    • Set appropriate resources
    • Configure health checks

  3. Deployment:

    • Use CI/CD pipelines
    • Implement gradual rollouts
    • Tag stable revisions
    • Monitor deployments

Troubleshooting​

Common Issues​

  1. Deployment Errors

    • Check container image
    • Verify permissions
    • Review resource limits
    • Check region availability

  2. Performance Issues

    • Analyze cold starts
    • Optimize container size
    • Configure concurrency
    • Review scaling settings

  3. Networking

    • Check VPC configuration
    • Verify ingress settings
    • Review firewall rules
    • Test connectivity

Getting Help​