Cloud Run MCP Server for Windsurf: Setup & Config

What you can do with Cloud Run in Windsurf

Deploy from an agent and investigate the resulting Cloud Run service without changing integrations.

• Inspect service configuration and error evidence after deployment.
• Discover or create Google Cloud projects when operating the server locally.

Before you start: Cloud Run in Windsurf

• Node.js, preferably an LTS release
• Installed Google Cloud SDK
• Google account authentication and application-default credentials
• MCP client configured to start the local package

The command matches the README's recommended local Node configuration, not the bare script from config_hint. Prepare credentials with gcloud auth login followed by gcloud auth application-default login. All three environment entries are optional defaults. A remotely hosted server follows a different authenticated setup and does not expose the local-only tools.

Cloud Run Windsurf configuration

1. Choose Windsurf configuration scope

   For Cloud Run MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Cloud Run MCP Server to Windsurf

   Use the cloud-run-mcp entry below in mcpServers. Keep Cloud Run MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Cloud Run MCP Server in Windsurf

   Cloud Run MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "cloud-run-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@google-cloud/cloud-run-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "<optional project ID used when a request omits it>",
        "GOOGLE_CLOUD_REGION": "<optional deployment region used by default>",
        "DEFAULT_SERVICE_NAME": "<optional fallback name for the Cloud Run service>"
      }
    }
  }
}

Cloud Run tools available to Windsurf

Cloud Run's stored tool list documents 7 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

get-service-log

After refreshing Cloud Run in Windsurf settings, check Cascade's tool list for get-service-log.

Read a selected service's logs, including error messages.

get-service

After refreshing Cloud Run in Windsurf settings, check Cascade's tool list for get-service.

Inspect details about one deployed Cloud Run service.

list-services

After refreshing Cloud Run in Windsurf settings, check Cascade's tool list for list-services.

deploy-file-contents

After refreshing Cloud Run in Windsurf settings, check Cascade's tool list for deploy-file-contents.

Publish an application by supplying its files' contents directly.

deploy-local-folder

After refreshing Cloud Run in Windsurf settings, check Cascade's tool list for deploy-local-folder.

list-projects

After refreshing Cloud Run in Windsurf settings, check Cascade's tool list for list-projects.

create-project

After refreshing Cloud Run in Windsurf settings, check Cascade's tool list for create-project.

In local mode, create a project linked to the first available billing account, optionally choosing its ID.

Cloud Run: full stored tool descriptions

Troubleshooting Cloud Run in Windsurf

• Check npx @google-cloud/cloud-run-mcp (Node.js/npm) on the machine running Windsurf's MCP integration for Cloud Run MCP Server; refresh MCP and inspect Cascade's tools.
• Check DEFAULT_SERVICE_NAME, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_REGION for Cloud Run MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Cloud Run MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Remote instances cannot deploy outside their own hosting project.
• Known limitation: Folder deployment and project discovery or creation are unavailable in remote mode.
• Known limitation: Remote access needs authentication; host validation is not enabled by default.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions