Deploying MCP Servers
on Google Cloud Run

One-time setup

Google Cloud setup, four steps

Skip ahead if a project with billing already exists.

Deploy

From source to a live URL

All commands run in Cloud Shell — the >_ icon, top right of the console. Nothing to install locally: gcloud, git, and docker are preloaded and already signed in as you.

# Confirm the right project — Cloud Shell usually auto-selects it; check the session banner first
gcloud config set project YOUR_PROJECT_ID

# One-time per project
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

# Get the server source
git clone <repo-url>
cd <repo-directory>

Before deploying, check the Dockerfile for BuildKit-only syntax — the single most common first-attempt failure:

grep -n "mount=type=cache" Dockerfile

If that finds anything, Cloud Build's default builder will fail on it (the --mount option requires BuildKit). Strip it — it only affects build-cache speed, not runtime behaviour:

sed -i 's/--mount=type=cache,target=[^ ]* //' Dockerfile
grep -n "mount=type=cache" Dockerfile   # should now print nothing

Deploy from source — Cloud Run builds the image for you, no local Docker build required:

gcloud run deploy SERVICE_NAME \
  --source . \
  --region europe-west2 \
  --allow-unauthenticated \
  --concurrency=1 \
  --set-env-vars UPSTREAM_API_KEY=your_value,BIND_ADDRESS=0.0.0.0

Notes on the flags:

• --allow-unauthenticated is required, not optional, for a claude.ai custom connector. Cloud Run's alternative is Google-signed IAM identity tokens, and claude.ai has no way to present those.
• --concurrency=1 — see the Troubleshoot tab for why this matters more than it looks like it should. Worth setting from the first deploy.
• BIND_ADDRESS=0.0.0.0 — many MCP HTTP servers default to loopback-only, which never receives Cloud Run's proxied traffic. Check the specific server's README for the exact variable name.
• The first deploy will offer to enable Artifact Registry — accept, that's where the built image is stored.

A successful deploy prints a Service URL, e.g. https://SERVICE_NAME-XXXXXXXXX.europe-west2.run.app. That hostname is stable across future redeploys.

If the build fails

Get the actual error rather than guessing:

gcloud builds log BUILD_ID --region=europe-west2

BUILD_ID prints in the failed deploy's own output, or list recent ones: gcloud builds list --region=europe-west2 --limit=5.

If the server checks the incoming Host header

A common security practice — check the server's logs or README for something like ALLOWED_HOSTS. Redeploy once more now that the real hostname is known:

gcloud run services update SERVICE_NAME \
  --region europe-west2 \
  --update-env-vars ALLOWED_HOSTS=SERVICE_NAME-XXXXXXXXX.europe-west2.run.app

Secure it

Gate inbound access before you rely on this

An upstream API key the server holds only authenticates its own outbound calls. It does not stop anyone who finds the Cloud Run URL from calling the server itself and running up usage against that key. Assume the URL eventually leaks somewhere — a log, a screenshot, a shared chat — and gate inbound access explicitly.

Generate a token

openssl rand -hex 32

Save the output somewhere retrievable — one unbroken 64-character string, no label or prefix attached.

What the patch needs to do

Regardless of the server's language, add a check at the earliest point in the request-handling chain — before any MCP protocol logic runs:

Worked examples, side by side

const authToken = process.env.MCP_AUTH_TOKEN;
if (authToken) {
  app.use((req, res, next) => {
    const header = req.headers.authorization;
    const queryToken = req.query.token;
    const headerOk = header === `Bearer ${authToken}`;
    const queryOk = typeof queryToken === "string" && queryToken === authToken;
    if (!headerOk && !queryOk) {
      res.status(401).json({
        jsonrpc: "2.0",
        error: { code: -32000, message: "Unauthorized" },
        id: null,
      });
      return;
    }
    next();
  });
}

import os
from fastapi import Request
from fastapi.responses import JSONResponse

AUTH_TOKEN = os.environ.get("MCP_AUTH_TOKEN")

@app.middleware("http")
async def auth_gate(request: Request, call_next):
    if AUTH_TOKEN:
        header = request.headers.get("authorization")
        query_token = request.query_params.get("token")
        header_ok = header == f"Bearer {AUTH_TOKEN}"
        query_ok = query_token == AUTH_TOKEN
        if not header_ok and not query_ok:
            return JSONResponse(
                status_code=401,
                content={"jsonrpc": "2.0", "error": {"code": -32000, "message": "Unauthorized"}, "id": None},
            )
    return await call_next(request)

For any other language, the shape is the same: intercept before routing, check both locations, short-circuit with 401 on failure.

Finding the insertion point

grep -n "app\.\(use\|post\|all\)" <main-server-file>   # Express-style
# or the equivalent route-registration search for the framework in use

Read enough surrounding context to find a safe spot — ideally right after any existing Host-header check, before CORS or JSON parsing. Prefer a scripted patch over manual editing:

cat > /tmp/patch_auth.py << 'PYEOF'
path = "<main-server-file>"
with open(path) as f:
    content = f.read()

anchor = """<exact text immediately before your insertion point>"""
insert = """<anchor text> + <your new middleware>"""

count = content.count(anchor)
if count != 1:
    raise SystemExit(f"Expected exactly 1 match, found {count} — aborting.")

with open(path, "w") as f:
    f.write(content.replace(anchor, insert))
print("Patched successfully.")
PYEOF
python3 /tmp/patch_auth.py

Redeploy and verify both directions

gcloud run deploy SERVICE_NAME \
  --source . --region europe-west2 --allow-unauthenticated --concurrency=1 \
  --set-env-vars UPSTREAM_API_KEY=your_value,BIND_ADDRESS=0.0.0.0,ALLOWED_HOSTS=<hostname>,MCP_AUTH_TOKEN=<token>

# Expect 401 — no token supplied
curl -i -X POST https://<hostname>/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Expect 200 — correct token via query string
curl -i -X POST "https://<hostname>/mcp?token=<token>" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

A 200 on the second call, with a JSON body naming the server and its tools, confirms the deployment is genuinely working end to end.

Connect to claude.ai

Add the connector, three fields

Why there's no header field

As of this writing, claude.ai's Add Custom Connector dialog exposes exactly three inputs: Name, URL, and an OAuth Client ID/Secret pair for connectors that use full OAuth. There is currently no field for arbitrary custom headers, unlike Claude Code and Claude Desktop's config-file-based setup, which do support them. A genuine current gap in the web UI, not a missing setting to hunt for.

The workaround: query-string token

Because the patch above already checks the query string as well as the header, the token can simply be embedded directly in the connector's URL field, and no header configuration is needed at all.

Troubleshooting reference

Every error hit, and what it actually means

Tailing logs live

gcloud beta run services logs tail SERVICE_NAME --region <region>

First run in a fresh Cloud Shell session may prompt to install a component:

sudo apt-get install google-cloud-cli-log-streaming

This self-install prompt fails inside Cloud Shell specifically, since component management is disabled there — normal, not an error. Cloud Shell is ephemeral, so this reinstalls every fresh session.

Maintenance

Rotating secrets and checking what's actually live

Design notes

Judgment calls worth knowing if you extend this

• A single clean curl test doesn't prove a server survives real usage. Load-test with several calls close together before calling any deployment done.
• Chat-side error summaries paraphrase, not quote. Go to the actual Cloud Run log for anything beyond a first-pass symptom.
• Official reference MCP servers aren't necessarily built for concurrent HTTP use. Many are written and tested primarily for local, single-client, stdio use.
• claude.ai's connector auth story is currently OAuth-first, even for connectors that don't use OAuth at all.
• Delete-and-recreate is the correct fix for a stuck custom connector, not a fallback. There's no edit path today.

Appendix A

Perplexity MCP — the deployment this guide came from

The concrete build every general-purpose step in this guide traces back to.

Deployment Record
File: 20260711-perplexityMcpDeployment-v1.0

Server: perplexityai/modelcontextprotocol (official), HTTP mode via included Dockerfile
Region: europe-west2 (London)
Env vars: PERPLEXITY_API_KEY, BIND_ADDRESS=0.0.0.0, ALLOWED_HOSTS, MCP_AUTH_TOKEN
Dockerfile fix: Yes — one --mount=type=cache instance on the npm install line, stripped
Concurrency bug: Yes — "Already connected to a transport", resolved with --concurrency=1
Root cause: Single shared Server instance in src/http.ts, reused across requests
Auth patch: Node/Express, inserted between Host-header check and CORS configuration
Validated with: 30+ real tool calls across three chat sessions spanning several hours,
  multiple Cloud Run instances spinning up and down correctly under concurrency=1,
  zero recurrence of the transport error after the fix

One data point, not a guarantee every server behaves identically — but every general-purpose step in the Deploy and Secure & Connect tabs traces back to something encountered building this one.