Building Production-Ready, Secure AI Backends with WebMCP and Google Cloud Run

Mukhtar Salim — Thu, 10 Sep 2026 06:17:47 +0000

The shift toward autonomous AI agents has exposed a critical gap in modern web infrastructure: the interface gap. For years, browser-based AI agents have had to navigate web pages the way humans do...parsing visual layouts, guessing CSS selectors, and attempting to mimic clicks.

Connecting in-browser agent tools directly to modern cloud backends requires an architectural shift. By combining WebMCP on the frontend with Google Cloud Run on the backend, engineers can build a deterministic, resilient, and enterprise-grade AI foundation.

What is WebMCP?

WebMCP (Web Model Context Protocol) is an emerging browser-level standard that allows live web pages to expose structured, machine-readable tools directly to client-side AI agents.

While Anthropic’s open-source MCP focuses on server-to-server and local-system connections (connecting LLMs to local databases, file systems, and internal enterprise services), WebMCP brings that same tooling contract into the browser DOM.

Through imperative JavaScript APIs (or declarative HTML annotations), a web application can register explicit capabilities...defining function names, JSON input schemas, and expected returns. When an AI agent visits the page, it does not need to guess what a button does; it inspects the page's registered WebMCP tools and calls them natively.

Why Does It Matter?

Traditional web agents rely on heuristic scraping, computer vision screenshot analysis, and DOM parsing. This approach introduces major engineering bottlenecks:

- Fragility: A slight redesign, a changed CSS class name, or an A/B test often breaks the agent's workflow entirely.

- Token Inefficiency: Feeding raw HTML or multi-resolution screenshots into LLM context windows consumes thousands of tokens per step, escalating cost and latency.

- Non-Determinism: Vision-driven clicking frequently misfires on interactive widgets, dynamic modals, or custom calendar pickers.

WebMCP establishes an explicit contract between websites and AI. Instead of asking an LLM to find an <input name="search"> tag and trigger a mouse event, the page declares a search_flights tool with typed arguments. The agent interacts with the website via a reliable, typed contract, making browser automation resilient and predictable.

Why Use WebMCP Instead of a Normal API?

WebMCP is an in-context orchestration layer for browser-agent interaction rather than a replacement for standard REST or GraphQL APIs. Unlike headless, server-to-server APIs that operate blindly and require manual state assembly and separate authentication flows, WebMCP executes inside the user's active browser session.

This setup enables tools to inherit live DOM state, reuse existing login sessions, and register dynamically based on application context. Most importantly, it keeps humans in the loop by updating the UI in real time, allowing users to visibly monitor, confirm, or abort agent actions as they happen.

What is Google Cloud Run?

Google Cloud Run is a fully managed, serverless compute platform that enables you to deploy and run containerized applications directly on top of Google’s scalable infrastructure.

Cloud Run eliminates container orchestration complexity. You package your application logic...whether written in Python, Go, Node.js, or Rust...into an OCI-compliant container image, and Cloud Run provisions, executes, and scales it automatically in response to incoming HTTPS requests or asynchronous events.

Core Features of Google Cloud Run

- True Serverless Scaling (Scale-to-Zero): Cloud Run instances scale dynamically from zero to thousands based on incoming traffic, meaning you only pay for compute resources while requests are actively processing.

- Concurrency per Instance: Unlike traditional Function-as-a-Service (FaaS) platforms where one instance handles one request at a time, Cloud Run allows a single container instance to process dozens of concurrent requests, optimizing memory and reducing costs.

- Native Secret Management: Deep integration with Google Cloud Secret Manager allows API keys (such as GEMINI_API_KEY) to be injected directly as environment variables or mounted files without hardcoding credentials in container builds.

- Built-in Identity & Access Management (IAM): Native support for Google Cloud IAM enables granular access policies, ensuring that only authenticated users or approved API Gateways can invoke endpoints.

- Traffic Splitting & Canary Deployments: Cloud Run allows zero-downtime rollouts and traffic splitting across multiple container revisions (e.g., routing 10% of agent traffic to a new LLM model prompt for evaluation).

- VPC Integration: Containers can securely communicate with internal databases (like Cloud SQL or Memorystore) and private VPC networks without exposing resources to the public internet.

Pros of Using Google Cloud Run for AI Backends

- Reduced Operational Overhead: No virtual machines to patch, no Kubernetes clusters to configure, and no manual node autoscaling policies to maintain.

- Cost Predictability: For AI workloads with unpredictable spikes or long periods of developer inactivity, scaling to zero prevents idle server bills.

- Portability: Because Cloud Run is standard container-based (Docker/Podman), you avoid vendor lock-in. The same container running on Cloud Run can run locally via Docker Compose or on an on-premises cluster.

- Long Request Timeouts: AI workloads....especially long-form analysis, retrieval-augmented generation (RAG), and agentic reasoning loops....require longer runtimes. Cloud Run supports request timeouts up to 60 minutes, accommodating long-running generative processes without dropped connections.

- Hardware Acceleration (GPU Support): Cloud Run supports attached GPUs (such as NVIDIA L4s), allowing you to run self-hosted inference or embedding models serverlessly alongside lightweight orchestration APIs.7.

Why Build a Production-Ready, Secure AI Backend with WebMCP and Google Cloud Run?

While running WebMCP with a local server (localhost:8080) is ideal for developer experimentation, a production deployment presents serious enterprise requirements: session isolation, API key protection, denial-of-service resilience, and strict compliance.

Pairing WebMCP and Google Cloud Run creates an optimal AI architecture for several reasons:

A. Zero Secret Exposure on the Client

WebMCP runs on the user's browser, meaning client-side code is entirely public. If a browser tool attempts to call models like Google Gemini directly from JavaScript, the API key must live in the browser, exposing it to exfiltration.

By having the WebMCP tool forward requests to a FastAPI container on Cloud Run, Cloud Run acts as a secure boundary. The Gemini API key remains isolated inside Google Secret Manager, never visible to the browser or network inspector.

B. Defending Against Resource Exhaustion & Model Quota Draining

Because WebMCP allows autonomous or semi-autonomous tools to trigger operations, unchecked clients could inadvertently loop and consume your LLM token quotas.

Placing Cloud Run behind an API Gateway or Cloud Armor allows you to implement:

Granular IP and token-bucket rate limiting.
Input size and schema validation (using Pydantic/FastAPI) before calling upstream models.
Token budgets and payload sanitization to mitigate prompt injection.

C. Enterprise-Grade Session Security

WebMCP leverages the user’s active web session for frontend context, while Cloud Run allows you to enforce strict CORS policies and JWT/OAuth authentication. The backend verifies that the incoming request originates from your authorized frontend domain and corresponds to a validated, logged-in enterprise user before executing backend agent tools.

D. Architectural Symmetry

This architecture creates a clean separation of concerns:

- The Client (WebMCP): Governs user experience, contextual state, DOM-aware interactions, and transparent human-in-the-loop controls.

- The Cloud (Cloud Run): Governs compute, security boundaries, model orchestration, cost controls, and audit logging.

By adopting this pattern, teams can deploy AI agents that operate reliably inside the browser without compromising enterprise security or server stability.

Hands-On: Building the WebMCP Gemini Data Analyzer

This practical proof-of-concept shows how an in-browser WebMCP tool registers an analytical capability, accepts parameters from an agent, and delegates execution to a containerized FastAPI service on Cloud Run.

Architecture Flow

index.html serves as the frontend and registers the analyze_data_with_cloud_run tool via WebMCP.
The browser agent inspects the page, discovers the tool, and passes an analytical prompt with structured JSON.
The WebMCP handler sends a POST request to FastAPI's /analyze endpoint.
FastAPI validates the payload, queries Gemini via the official SDK, and returns the response.
The frontend displays the analysis live in the DOM for the user.

How it works

The application has two independent parts:

index.html registers a WebMCP tool named analyze_data_with_cloud_run.
A browser agent discovers and invokes that tool with a prompt and JSON data.
The tool sends a POST request to the FastAPI /analyze endpoint.
FastAPI sends the prompt and data to the Gemini API.
Gemini's response is returned to the browser agent as JSON.

Browser agent
    |
    | WebMCP tool invocation
    v
index.html (localhost:5500)
    |
    | POST /analyze
    v
FastAPI (localhost:8080)
    |
    | Gemini generate_content
    v
Google Gemini API

Project structure

.
├── Dockerfile
├── README.md
├── index.html
├── main.py
└── requirements.txt

index.html contains the user interface and WebMCP tool registration.
main.py contains the FastAPI application and Gemini integration.
requirements.txt lists the Python dependencies.
Dockerfile packages the backend for container-based deployment.

Requirements

Python 3.11 or newer
A Google Gemini API key
Brave or Chrome with experimental WebMCP support
Docker, optionally, for running the backend in a container

Local setup

1. Create a virtual environment

Open a terminal in the project directory:

cd /Users/mukhtarsalim/Desktop/webmcp-demo
python3 -m venv .venv
source .venv/bin/activate

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install dependencies

pip install -r requirements.txt

3. Configure the Gemini API key

Create or rotate an API key in Google AI Studio. Export it only in the backend terminal:

export GEMINI_API_KEY='your-new-gemini-api-key'

On Windows PowerShell:

$env:GEMINI_API_KEY='your-new-gemini-api-key'

Do not add API keys to index.html, source control, screenshots, documentation, or shell scripts.

4. Start the backend

uvicorn main:app --host 0.0.0.0 --port 8080 --reload

The API should be available at:

Health endpoint: http://localhost:8080/
Analysis endpoint: http://localhost:8080/analyze
Swagger UI: http://localhost:8080/docs

Keep this terminal running.

5. Start the frontend

Open a second terminal in the project directory:

python3 -m http.server 5500

Open http://localhost:5500 in the WebMCP-enabled browser.

Do not open index.html directly with a file:// URL. WebMCP requires a secure context such as HTTPS or localhost.

Enable WebMCP

WebMCP is currently an experimental browser feature.

For Brave:

Open brave://flags/#enable-webmcp-testing.
Set WebMCP for testing to Enabled.
Restart Brave.
Open http://localhost:5500.
Open the WebMCP Tools inspector on the application tab.

For Chrome:

Open chrome://flags/#enable-webmcp-testing.
Set WebMCP for testing to Enabled.
Restart Chrome.
Open http://localhost:5500.
Use the Model Context Tool Inspector to view and invoke the registered tool.

The tool is registered by the application page, not globally. The inspector will not find the tool while the active page is brave://flags, chrome://flags, or another website.

WebMCP tool

The frontend registers this tool:

analyze_data_with_cloud_run

It accepts:

prompt: the question or analysis instruction for Gemini.
data: a JSON object containing the structured information to analyze.

Example arguments:

{
  "prompt": "Summarize the data and identify unusual values.",
  "data": {
    "sales": [120, 135, 128, 410],
    "currency": "USD"
  }
}

The tool forwards the arguments to:

POST http://localhost:8080/analyze

API usage

Health check

curl http://localhost:8080/

Example response:

{
  "status": "online",
  "message": "WebMCP Cloud Run Backend is running",
  "api_key_configured": true
}

Analyze data

curl --request POST http://localhost:8080/analyze \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "Summarize this dataset.",
    "data": {
      "value": 42,
      "category": "example"
    }
  }'

Example successful response:

{
  "status": "success",
  "result": "Gemini-generated analysis"
}

Run the backend with Docker

Build the image:

docker build -t webmcp-demo .

Run the container:

docker run --rm \
  --publish 8080:8080 \
  --env GEMINI_API_KEY='your-new-gemini-api-key' \
  webmcp-demo

The Docker container runs only the FastAPI backend. The frontend must still be served separately:

python3 -m http.server 5500

Optional Cloud Run deployment

Cloud Run is not required for local development. It is only needed when the backend must be publicly accessible.

For a hosted deployment:

Build and deploy the backend container to Cloud Run.
Configure GEMINI_API_KEY as a Cloud Run secret or environment variable.
Restrict unauthenticated access where appropriate.
Configure CORS to allow only the deployed frontend origin.
Replace the local backend URL in index.html with the deployed HTTPS /analyze URL.
Serve the frontend from an HTTPS host.

Do not deploy the current demo publicly without adding authentication, rate limiting, request-size limits, and restrictive CORS settings. Otherwise, third parties could consume the Gemini quota.

Changes made during local setup

The original frontend sent requests directly to a hardcoded Google Cloud Run endpoint:

https://webmcp-backend-103973904738.us-central1.run.app/analyze

It was changed to the local FastAPI endpoint:

http://localhost:8080/analyze

This change:

Removes the need to configure Cloud Run for local testing.
Connects the locally served frontend to the locally running backend.
Keeps Gemini API calls on the backend so the API key is not exposed to browser code.
Allows the complete WebMCP flow to run on localhost.

The application was then verified with:

The FastAPI health endpoint responding on port 8080.
The frontend serving successfully on port 5500.
WebMCP for testing enabled in Brave.
The tool inspector opened on the application page.

Troubleshooting

WebMCP API not found

Confirm the WebMCP testing flag is enabled.
Restart the browser after changing the flag.
Open the application through http://localhost:5500.
Test with the latest Google Chrome if Brave does not expose the API.

No tools registered

The inspector must be attached to the application tab. Navigate to http://localhost:5500 before opening or refreshing the inspector.

Receiving end does not exist

This usually means the inspector extension cannot communicate with the active page or its background process.

Restart the browser.
Reopen the application tab.
Disable and re-enable the inspector extension.
Test with current Google Chrome if the issue persists in Brave.

Backend is not reachable

Confirm the backend process is running:

curl http://localhost:8080/

Also confirm that index.html points to:

http://localhost:8080/analyze

Gemini API key is not configured

Export GEMINI_API_KEY in the same terminal before starting Uvicorn. Restart Uvicorn after changing it.

`python main.py` fails

The current main.py calls uvicorn.run(...) without importing uvicorn. Start the application with the supported command:

uvicorn main:app --host 0.0.0.0 --port 8080 --reload

Alternatively, add import uvicorn at the top of main.py before using python main.py.

CORS errors

Ensure the frontend uses http://localhost:5500 and the backend uses http://localhost:8080. For production, replace wildcard CORS configuration with the exact frontend origin.

Current limitations

This project is a proof of concept rather than a production-ready service:

The /analyze endpoint has no authentication.
CORS currently permits every origin.
There is no rate limiting or request-size limit.
Backend exception details may be returned to clients.
Dependencies are not version-pinned.
Automated tests and CI are not configured.
The WebMCP tool does not yet use an AbortSignal for cleanup.
The WebMCP tool does not yet declare security annotations.

Security notes

Rotate an API key immediately if it appears in terminal history, screenshots, chat, or source control.
Never put GEMINI_API_KEY in frontend JavaScript.
Use a secret manager for hosted deployments.
Add authentication and rate limiting before exposing /analyze publicly.
Restrict CORS to trusted frontend origins in production.
Avoid returning raw provider errors to clients.

Stopping the application

Press Ctrl+C in both terminals:

The terminal running Uvicorn.
The terminal running the Python HTTP server.

DEV Community: Mukhtar Salim