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

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

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.

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:

  1. 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.
  2. 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
  1. Install dependencies
pip install -r requirements.txt
  1. 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.

  1. 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.

  1. 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:

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

For Chrome:

  1. Open chrome://flags/#enable-webmcp-testing.
  2. Set WebMCP for testing to Enabled.
  3. Restart Chrome.
  4. Open http://localhost:5500.
  5. 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:

  1. Build and deploy the backend container to Cloud Run.
  2. Configure GEMINI_API_KEY as a Cloud Run secret or environment variable.
  3. Restrict unauthenticated access where appropriate.
  4. Configure CORS to allow only the deployed frontend origin.
  5. Replace the local backend URL in index.html with the deployed HTTPS /analyze URL.
  6. 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. Thi

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.