# googlecloudplatform/cloud-run-mcp architecture

> Architecture diagram of the GitHub repository googlecloudplatform/cloud-run-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/cloud-run-mcp
- Repository: https://github.com/googlecloudplatform/cloud-run-mcp

## Overview

Cloud Run MCP exposes project and service-management tools plus deployment and log prompts to AI clients. The principal workflow is an agent tool call through MCP registration into deployment orchestration, which prepares source or an image and deploys a Cloud Run service; separate tools list projects and inspect services/logs. The README documents local-folder, file-content, and image deployment, and local project creation. The sampled sources establish several orchestration calls, but not every internal deployment step, so uncertain wiring is omitted.

Main entry points: [`lib/deployment/deployer.js`](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/deployer.js) (Deployment orchestration), [`tools/register-tools.js`](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/tools/register-tools.js) (Tool registration), [`lib/cloud-api/run.js`](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/run.js) (Service operations), [`mcp-server.js`](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/mcp-server.js) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_mcp["MCP server<br/>[mcp-server.js]"]
  node_toolreg["Tool registration<br/>[register-tools.js]"]
  node_toolimpl["Tool handlers<br/>[tools.js]"]
  node_prompts["Prompt templates<br/>[prompts.js]"]
end

subgraph group_deploy["Deployment"]
  node_deployer["Deployment orchestration<br/>[deployer.js]"]
  node_source["Source preparation"]
  node_maker["Universal Maker<br/>[universal-maker.js]"]
  node_deployhelpers["Deployment helpers<br/>[helpers.js]"]
end

subgraph group_cloud["Cloud API"]
  node_projects["Project operations<br/>[projects.js]"]
  node_runapi["Service operations<br/>[run.js]"]
  node_build["Cloud Build<br/>[build.js]"]
  node_registry["Artifact Registry<br/>[registry.js]"]
  node_storage["Storage operations<br/>[storage.js]"]
end

subgraph group_identity["Authentication"]
  node_clients["GCP client cache<br/>[clients.js]"]
  node_gcpauth["ADC check<br/>[auth.js]"]
  node_oauth["OAuth middleware<br/>[oauth.js]"]
end

node_agent(("AI agent"))
node_gcp{{"Google Cloud"}}
node_cloudrun{{"Cloud Run"}}
node_cloudbuild{{"Cloud Build service"}}
node_artifactregistry{{"Artifact Registry service"}}
node_gcs[("Cloud Storage")]
node_logging{{"Cloud Logging"}}

node_agent -->|"sends MCP requests"| node_mcp
node_mcp -->|"registers tools"| node_toolreg
node_mcp -->|"provides prompts"| node_prompts
node_toolreg -->|"lists or creates projects"| node_projects
node_toolreg -->|"lists and inspects services"| node_runapi
node_toolreg -->|"requests deployment"| node_deployer
node_deployer -->|"checks services"| node_runapi
node_deployer -->|"ensures repository"| node_registry
node_deployer -->|"triggers build"| node_build
node_deployer -->|"analyzes source"| node_maker
node_deployer -->|"cleans temporary files"| node_source
node_deployer -->|"checks build mode"| node_deployhelpers
node_deployer -->|"creates or updates service"| node_cloudrun
node_build -->|"starts build"| node_cloudbuild
node_registry -->|"manages repository"| node_artifactregistry
node_storage -->|"creates buckets and uploads"| node_gcs
node_projects -->|"manages projects"| node_gcp
node_runapi -->|"reads services and logs"| node_cloudrun
node_runapi -->|"reads logs"| node_logging
node_clients -->|"creates authenticated clients"| node_gcp
node_gcpauth -->|"checks credentials"| node_gcp
node_oauth -->|"gets OAuth client"| node_clients
node_oauth -.->|"rejects unauthenticated calls"| node_agent

click node_mcp "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/mcp-server.js"
click node_toolreg "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/tools/register-tools.js"
click node_toolimpl "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/tools/tools.js"
click node_prompts "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/prompts.js"
click node_deployer "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/deployer.js"
click node_source "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/source-processor.js"
click node_maker "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/universal-maker.js"
click node_deployhelpers "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/helpers.js"
click node_projects "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/projects.js"
click node_runapi "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/run.js"
click node_build "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/build.js"
click node_registry "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/registry.js"
click node_storage "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/storage.js"
click node_clients "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/clients.js"
click node_gcpauth "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/auth.js"
click node_oauth "https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/middleware/oauth.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_toolreg,node_toolimpl,node_prompts toneBlue
class node_deployer,node_source,node_maker,node_deployhelpers,node_gcs toneAmber
class node_projects,node_runapi,node_build,node_registry,node_storage toneMint
class node_clients,node_gcpauth,node_oauth toneRose
class node_agent,node_gcp,node_cloudrun,node_cloudbuild,node_artifactregistry,node_logging toneIndigo
```

## Components

### MCP interface

- [MCP server](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/mcp-server.js): `mcp-server.js`
- [Tool registration](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/tools/register-tools.js): `tools/register-tools.js`
- [Tool handlers](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/tools/tools.js): `tools/tools.js`
- [Prompt templates](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/prompts.js): `prompts.js`

### Deployment

- [Deployment orchestration](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/deployer.js): `lib/deployment/deployer.js`
- [Source preparation](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/source-processor.js): `lib/deployment/source-processor.js`
- [Universal Maker](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/universal-maker.js): `lib/deployment/universal-maker.js`
- [Deployment helpers](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/deployment/helpers.js): `lib/deployment/helpers.js`

### Cloud API

- [Project operations](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/projects.js): `lib/cloud-api/projects.js`
- [Service operations](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/run.js): `lib/cloud-api/run.js`
- [Cloud Build](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/build.js): `lib/cloud-api/build.js`
- [Artifact Registry](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/registry.js): `lib/cloud-api/registry.js`
- [Storage operations](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/storage.js): `lib/cloud-api/storage.js`

### Authentication

- [GCP client cache](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/clients.js): `lib/clients.js`
- [ADC check](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/cloud-api/auth.js): `lib/cloud-api/auth.js`
- [OAuth middleware](https://github.com/googlecloudplatform/cloud-run-mcp/blob/main/lib/middleware/oauth.js): `lib/middleware/oauth.js`

### Other components

- **AI agent**
- **Google Cloud**
- **Cloud Run**
- **Cloud Build service**
- **Artifact Registry service**
- **Cloud Storage**
- **Cloud Logging**

## Connections

- AI agent → MCP server: sends MCP requests
- MCP server → Tool registration: registers tools
- MCP server → Prompt templates: provides prompts
- Tool registration → Project operations: lists or creates projects
- Tool registration → Service operations: lists and inspects services
- Tool registration → Deployment orchestration: requests deployment
- Deployment orchestration → Service operations: checks services
- Deployment orchestration → Artifact Registry: ensures repository
- Deployment orchestration → Cloud Build: triggers build
- Deployment orchestration → Universal Maker: analyzes source
- Deployment orchestration → Source preparation: cleans temporary files
- Deployment orchestration → Deployment helpers: checks build mode
- Deployment orchestration → Cloud Run: creates or updates service
- Cloud Build → Cloud Build service: starts build
- Artifact Registry → Artifact Registry service: manages repository
- Storage operations → Cloud Storage: creates buckets and uploads
- Project operations → Google Cloud: manages projects
- Service operations → Cloud Run: reads services and logs
- Service operations → Cloud Logging: reads logs
- GCP client cache → Google Cloud: creates authenticated clients
- ADC check → Google Cloud: checks credentials
- OAuth middleware → GCP client cache: gets OAuth client
- OAuth middleware → AI agent: rejects unauthenticated calls