YouTube MCP Server
ctgunn/youtube-mcp-server
Servidor MCP para integrar busca e recuperação de dados do YouTube em agentes
Ver no GitHubServidor MCP que encapsula a API do YouTube e expõe ferramentas de busca para uso em workflows de agentes. Implementa um contrato MCP padronizado e pode ser deployado em Google Cloud Run, oferecendo gerenciamento de sessão, health checks e observabilidade.
Instalação
npx convez-ai ctgunn/youtube-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar busca no YouTube em workflows de agentes OpenAI
- Expor APIs do YouTube via protocolo MCP em aplicações cloud-native
- Construir pipelines de recuperação de conteúdo de vídeo em automações
Veredito

Solução técnica bem estruturada para integração YouTube em arquiteturas MCP. Adequada para quem precisa expor dados do YouTube via protocolo padrão em deployments cloud, mas requer familiaridade com MCP e infraestrutura serverless.
README
A tradução para o português deste README ainda está na fila.
youtube-mcp-server
An MCP-compliant server that wraps the YouTube Data API and exposes searchable tools for use in OpenAI Agent Builder workflows. The current primary hosted provider adapter targets Google Cloud Run, while the shared platform contract keeps the hosted deployment model portable across providers.
What this is
At a high level, this repository contains a remote MCP server. Other
applications do not import this code directly. Instead, they connect to the
hosted HTTP endpoint, send MCP messages to /mcp, discover the available
tools, and call those tools over the network.
Today the server includes:
- baseline server tools such as
server_ping,server_info, andserver_list_tools - foundational retrieval tools such as
searchandfetch - hosted session management for streamable MCP over HTTP
- health, readiness, security, and observability behavior for Cloud Run-style hosting
If you are new to the repository, the sections below explain the server in the same layered way a human would usually learn it: from very high level down to the request-by-request details.
How to read this README
This README is intentionally layered.
If you are trying to get the server running for the first time, start with the setup sections immediately below:
Setup from scratch: localgets the server running on your machine as fast as possible.Setup from scratch: hosted on GCPwalks through the first full hosted deployment path end to end.
After that, come back to the architecture sections when you want to understand how the server actually works.
You can think about the architecture at five levels:
- 100 ft: what the server is for
- 30 ft: how another application uses it
- 10 ft: which modules are responsible for which jobs
- ground level: what happens during a real request
- underground: where sessions, streams, validation, and tool execution actually live
The rest of this README keeps the detailed deployment and verification material that already existed, but this section is intended to make the big picture much easier to follow first.
Setup From Scratch: Local
Use this path when you want to run the MCP server on your own machine for development or manual testing before pushing code.
What you need
python33.11 or newerpipmake- one supported compose command if you want the hosted-like Redis-backed path:
docker compose,docker-compose,podman compose, orpodman-compose
These tools must already be installed on your machine before you start.
Recommended install paths:
python3: use your platform package manager or the official Python installer. On macOS with Homebrew:brew install python@3.11pip: usually included with Python 3. If not, install Python again using the official installer or your package manager.make: usually preinstalled on macOS. If not, install the Xcode Command Line Tools withxcode-select --installdocker compose: easiest path for most users is Docker Desktop, which includes bothdockeranddocker composepodman compose: use Podman if you prefer it over Docker; install it from your platform package manager or the official installer
1. Open the repository
cd ~/Projects/youtube-mcp-server
2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
3. Install the project
python3 -m pip install --upgrade pip
python3 -m pip install -e .
4. Review the local environment file
The local runtime path reads defaults from .env.local.
For the first run, the important ideas are:
- local development uses
MCP_ENVIRONMENT=dev - the default local path uses
MCP_SESSION_BACKEND=memory - the default local path does not require hosted cloud infrastructure
5. Start the server locally
The simplest local startup command is:
make dev
That command uses scripts/dev_local.sh, loads .env.local, and starts the
ASGI app locally.
6. Verify that the local server is healthy
In a second terminal:
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/ready
You want both endpoints to return 200.
7. Verify the MCP handshake locally
Initialize:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":"req-init","method":"initialize","params":{"clientInfo":{"name":"local-test","version":"1.0.0"}}}' \
http://127.0.0.1:8080/mcp
Copy the returned MCP-Session-Id header, then use it to list tools:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Session-Id: YOUR_SESSION_ID' \
-d '{"jsonrpc":"2.0","id":"req-list","method":"tools/list","params":{}}' \
http://127.0.0.1:8080/mcp
Then call a baseline tool:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Session-Id: YOUR_SESSION_ID' \
-d '{"jsonrpc":"2.0","id":"req-call","method":"tools/call","params":{"name":"server_ping","arguments":{}}}' \
http://127.0.0.1:8080/mcp
8. Run the hosted-like local path when you need Redis-backed sessions
This path is useful when you want local behavior that is closer to hosted session durability.
If make dev is still running, stop that in-memory local server first with
Ctrl+C before switching modes. make dev-down only stops the Redis
containers used by the hosted-like path; it does not stop the server process
started by make dev.
Start the local Redis dependency:
docker compose -f infrastructure/local/compose.yaml up -d
./scripts/local_compose.sh up -d
Start the app in hosted-like mode:
make dev-hosted
When you are done:
make dev-down
This hosted-like local path keeps the same app entrypoint while switching the session backend to Redis-backed settings under local control.
Setup From Scratch: Hosted On GCP
Use this path when you want a real hosted MCP endpoint that other applications can reach over the network.
What you need
gcloudterraformdockerpython3- a Google Cloud account with billing enabled
- a GCP project you can administer, or permission to create one
These tools must already be installed on your machine before you start.
Recommended install paths:
gcloud: install the Google Cloud CLI. On macOS with Homebrew:brew install --cask google-cloud-sdkterraform: install the HashiCorp Terraform CLI. On macOS with Homebrew:brew tap hashicorp/tap && brew install hashicorp/tap/terraformdocker: easiest path for most users is Docker Desktop, which also includesdocker composepython3: use your platform package manager or the official Python installer. On macOS with Homebrew:brew install python@3.11
After installing them, verify they are on your PATH:
gcloud version
terraform version
docker --version
python3 --version
Before you start the hosted path, make sure you have already done the Google Cloud account-level setup outside this repository:
- create or sign in to your Google Cloud account
- enable billing for that account
- create a GCP project you want to use for this deployment
0. Create or choose the GCP project
If you already have a project, note its project ID and continue to the next step.
If you still need to create one, you can do that in the Google Cloud Console
or with gcloud:
gcloud projects create YOUR_PROJECT_ID --name="youtube-mcp-server"
gcloud config set project YOUR_PROJECT_ID
If Google Cloud prompts you to attach a billing account, complete that in the console before continuing.
1. Authenticate to Google Cloud
gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
2. Enable the required Google Cloud APIs
gcloud services enable \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
secretmanager.googleapis.com \
redis.googleapis.com \
vpcaccess.googleapis.com \
compute.googleapis.com \
iam.googleapis.com
3. Create the Artifact Registry repository if you do not already have one
gcloud artifacts repositories create apps \
--repository-format=docker \
--location=us-central1
4. Create the runtime secrets in Secret Manager
The hosted runtime expects operator-managed secret values for:
YOUTUBE_API_KEYMCP_AUTH_TOKEN
Use the following guidance for those values:
YOUTUBE_API_KEYshould be your real YouTube Data API key from Google Cloud. Create it in the Google Cloud Console under APIs & Services > Credentials after enabling the YouTube Data API for your project.MCP_AUTH_TOKENis not issued by Google Cloud and is not generated by this repository. It is a shared bearer secret that you choose and manage.- Hosted callers must send that exact
MCP_AUTH_TOKENvalue inAuthorization: Bearer ...when calling the protected/mcpendpoint. MCP_AUTH_TOKENshould be a long, random, high-entropy string. Do not use memorable phrases, repository values, or credentials reused from other systems.
One simple way to generate MCP_AUTH_TOKEN locally is:
openssl rand -base64 32
If openssl is not convenient in your environment, this Python alternative is
equivalent:
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
Create them if this is your first setup:
printf 'YOUR_REAL_YOUTUBE_API_KEY' | gcloud secrets create YOUTUBE_API_KEY --data-file=-
printf 'YOUR_REAL_MCP_AUTH_TOKEN' | gcloud secrets create MCP_AUTH_TOKEN --data-file=-
If they already exist, add new versions instead:
printf 'YOUR_REAL_YOUTUBE_API_KEY' | gcloud secrets versions add YOUTUBE_API_KEY --data-file=-
printf 'YOUR_REAL_MCP_AUTH_TOKEN' | gcloud secrets versions add MCP_AUTH_TOKEN --data-file=-
5. Review the deployment operator inputs
The repository root .env is the operator-oriented deployment input file for
the supported Cloud Run path. Review and set the values you actually intend to
deploy, especially:
PROJECT_ID: the GCP project ID that owns the Cloud Run service, secrets, and other hosted resources.REGION: the GCP region for the hosted deployment, such asus-central1.SERVICE_NAME: the Cloud Run service name to deploy.SERVICE_ACCOUNT_EMAIL: the runtime service account email used by Cloud Run. In this repository, Terraform creates that service account fromservice_account_nameininfrastructure/gcp/*.tfvars, and you can read the resulting email withterraform -chdir=infrastructure/gcp output service_account_emailafter apply. Before Terraform runs, you can usually predict the value asSERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com. For example, ifservice_account_name="youtube-mcp-server"andPROJECT_ID="my-gcp-project", the runtime email will usually beyoutube-mcp-server@my-gcp-project.iam.gserviceaccount.com.IMAGE_REFERENCE: the container image to deploy, for exampleus-central1-docker.pkg.dev/YOUR_PROJECT_ID/apps/youtube-mcp-server:TAG.MCP_ENVIRONMENT: runtime profile for the deployed service. Allowed values:dev,staging,prod.dev: local or low-friction validation profile; auth may be relaxed unless explicitly configured.staging: pre-production hosted profile; requiresYOUTUBE_API_KEYandMCP_AUTH_TOKEN.prod: production hosted profile; same required secrets asstaging.PUBLIC_INVOCATION_INTENT: whether the Cloud Run service is intentionally reachable by trusted remote MCP clients. Allowed values:public_remote_mcp,private_only.public_remote_mcp: intended for reachable remote MCP access.private_only: do not treat the service as part of the public remote MCP path.MCP_ALLOWED_ORIGINS: comma-separated browser origin allowlist for protected/mcprequests, for examplehttps://chat.openai.com. This matters for browser-based callers that send anOriginheader.SECRET_REFERENCES: comma-separated Secret Manager secret names injected into the runtime. Forstagingandprod, include bothYOUTUBE_API_KEYandMCP_AUTH_TOKEN.
Other operator inputs in .env are usually fine to keep at the example
defaults unless you need to tune behavior:
MIN_INSTANCES,MAX_INSTANCES,CONCURRENCY,TIMEOUT_SECONDS: Cloud Run scaling and request handling settings.MCP_AUTH_REQUIRED: optional boolean override for bearer-token enforcement. Leave blank to use profile defaults. Accepted true-like values are1,true,yes,on; anything else is treated as false.MCP_ALLOW_ORIGINLESS_CLIENTS: boolean control for non-browser clients that do not sendOrigin. Accepted true-like values are1,true,yes,on.MCP_SECRET_ACCESS_MODE: how the runtime receives secret-backed config. In the hosted GCP path this is typicallysecret_manager_env.MCP_SECRET_REFERENCE_NAMES: comma-separated secret names mirrored into the runtime configuration. This should matchSECRET_REFERENCESfor hosted deploys.MCP_SESSION_BACKEND: hosted session backend. Common values:memoryfor local-only or single-process validation,redisfor durable hosted sessions across instances.MCP_SESSION_STORE_URL: required whenMCP_SESSION_BACKEND=redis; points to the shared session store. For the Terraform-managed GCP path, it is normal for this to be blank in.envbefore infrastructure exists. Terraform creates the Redis instance and exportsmcp_session_store_url, which this repository can consume later throughINFRA_OUTPUTS_FILE=artifacts/gcp-foundation-outputs.jsonafter runningterraform -chdir=infrastructure/gcp output -json > artifacts/gcp-foundation-outputs.json. The generated value follows the patternredis://REDIS_HOST:6379/0.MCP_SESSION_CONNECTIVITY_MODEL: provider-specific connectivity path to the session backend. Common values:local_processfor local-only execution,serverless_vpc_connectorfor the hosted GCP durable-session path.MCP_SESSION_DURABILITY_REQUIRED: boolean flag indicating whether hosted deployment should require durable sessions.MCP_SESSION_TTL_SECONDS: hosted session lifetime in seconds.MCP_SESSION_REPLAY_TTL_SECONDS: replay event retention window in seconds for reconnect flows.INFRA_OUTPUTS_FILE: optional Terraformoutput -jsonhandoff file. When set, the deploy workflow merges values such asSERVICE_ACCOUNT_EMAIL,MCP_SESSION_STORE_URL, and the session network references from Terraform outputs, so you do not need to copy them into.envby hand.
For a real remote MCP deployment, MCP_ENVIRONMENT=staging and
PUBLIC_INVOCATION_INTENT=public_remote_mcp are the usual starting point.
6. Create the Terraform variable file for your environment
cp infrastructure/gcp/terraform.tfvars.example infrastructure/gcp/staging.tfvars
Then edit infrastructure/gcp/staging.tfvars with the real values for your
environment, including:
- project and region
- service name and environment
- public invocation intent
- allowed origins
- managed VPC, subnet, and VPC connector names/CIDRs for durable sessions
7. Provision the hosted infrastructure
Initialize Terraform:
terraform -chdir=infrastructure/gcp init
Review the plan:
terraform -chdir=infrastructure/gcp plan -var-file=staging.tfvars
Apply the infrastructure:
terraform -chdir=infrastructure/gcp apply -var-file=staging.tfvars
This hosted infrastructure step is what creates and wires the platform around the app, including the Cloud Run foundation, durable-session Redis path, and the managed network resources needed for the supported GCP session-connectivity model.
8. Export the Terraform outputs for the deploy handoff
mkdir -p artifacts
terraform -chdir=infrastructure/gcp output -json > artifacts/gcp-foundation-outputs.json
9. Build and push the container image
Authenticate Docker to Artifact Registry:
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
Build the image:
docker build -t us-central1-docker.pkg.dev/YOUR_PROJECT_ID/apps/youtube-mcp-server:manual-001 .
Push it:
docker push us-central1-docker.pkg.dev/YOUR_PROJECT_ID/apps/youtube-mcp-server:manual-001
10. Deploy the application through the repository deploy script
set -a
source .env
set +a
INFRA_OUTPUTS_FILE=artifacts/gcp-foundation-outputs.json \
IMAGE_REFERENCE=us-central1-docker.pkg.dev/YOUR_PROJECT_ID/apps/youtube-mcp-server:manual-001 \
DEPLOYMENT_RECORD_FILE=artifacts/cloud-run-deployment.json \
bash scripts/deploy_cloud_run.sh
This is the supported application rollout path. It uses the Terraform outputs
as the handoff from infrastructure reconciliation into Cloud Run deployment.
The deploy script does not load .env on its own, so source it first if you
want the operator-managed deployment inputs from step 5 to participate in the
deploy command.
11. Verify the hosted deployment
PYTHONPATH=src python3 scripts/verify_cloud_run_foundation.py \
--deployment-record artifacts/cloud-run-deployment.json \
--auth-token "YOUR_REAL_MCP_AUTH_TOKEN" \
--evidence-file artifacts/cloud-run-verification.txt \
--summary-file artifacts/cloud-run-verification.json
Do not treat the deployment as complete until hosted verification passes.
12. Enable push-triggered deployment after the manual path works once
The repository now defines the primary automated rollout in cloudbuild.yaml.
Once the manual path above works:
- create or update your Cloud Build trigger for
main - point it at
cloudbuild.yaml - set the required substitutions for project, region, service name, Artifact Registry repository, Terraform var file, and service account
- ensure the Cloud Build service account can manage the infrastructure and read the required secret references
After that, a push to main should run:
- tests and lint
- image build and publish
- Terraform apply
- deploy through
scripts/deploy_cloud_run.sh - hosted verification through
scripts/verify_cloud_run_foundation.py
100 Ft View
This server is a network-accessible toolbox.
An MCP-capable client such as OpenAI or another remote MCP consumer talks to your server over HTTP. The client asks:
- who are you?
- what tools do you have?
- please run this tool for me
Your server answers those questions using the MCP protocol.
In practical terms, the server has four main responsibilities:
- Start with the correct runtime configuration.
- Accept HTTP requests on
/health,/ready, and/mcp. - Maintain MCP session state so a client can continue talking to the same logical session.
- Route tool requests to Python handlers and return MCP-shaped results.
30 Ft View
Another application uses this server through a hosted MCP flow:
- The client sends
initializetoPOST /mcp. - If the request is allowed and valid, the server returns MCP capabilities and
an
MCP-Session-Idheader. - The client reuses that session ID on later requests such as
tools/listandtools/call. - The server validates the request, finds the correct tool, runs it, and returns a result in MCP format.
- If the client needs replay or stream continuation, it can reconnect with the
same session using
GET /mcpandLast-Event-ID.
The most important thing to remember is that clients interact with this server through HTTP plus JSON-RPC/MCP messages. They are not calling Python functions directly.
10 Ft View
These modules are the main moving parts:
- src/mcp_server/cloud_run_entrypoint.py This is the hosted front door. It receives raw HTTP requests and turns them into hosted MCP behavior.
- src/mcp_server/app.py This creates the transport object and loads runtime configuration.
- src/mcp_server/config.py This reads environment variables and defines runtime settings such as auth, session backend, TTLs, and readiness expectations.
- src/mcp_server/transport/http.py
This classifies requests, owns hosted route behavior, and routes
/mcppayloads into the MCP protocol layer. - src/mcp_server/security.py This decides whether a request is allowed based on bearer auth, origin handling, and browser preflight rules.
- src/mcp_server/transport/streaming.py This manages sessions, streams, replay windows, and SSE payload encoding.
- src/mcp_server/protocol/methods.py
This implements the MCP methods supported by the server, such as
initialize,tools/list, andtools/call. - src/mcp_server/tools/dispatcher.py This is the registry and dispatcher for tools.
- src/mcp_server/tools/retrieval.py
This is one current tool module that implements
searchandfetch. - src/mcp_server/transport/session_store.py This defines where hosted session state is stored: in memory or in Redis.
Ground Level: One Request Lifecycle
Here is the normal happy-path lifecycle for a hosted client:
- Cloud Run receives an HTTPS request.
- The ASGI entrypoint in
cloud_run_entrypoint.pypasses the request toexecute_hosted_request(...). - The request is classified by path, method, content type, and body shape.
/healthand/readyare answered directly by the hosted transport./mcprequests go through security checks first.- If the MCP method is
initialize, the protocol layer validates it and the server creates a new session only if initialize succeeds. - The server returns an
MCP-Session-Id, which the client must reuse on later requests. - Follow-up
tools/listandtools/callrequests are routed through the dispatcher. - The dispatcher validates tool arguments against the published schema and calls the correct Python handler.
- The result is wrapped into an MCP response and returned as JSON or streamable HTTP/SSE depending on the flow.
Underground: What lives under the surface
The server has a few pieces of hidden plumbing that matter a lot:
Sessions
- A successful
initializecreates a hosted MCP session. - The session ID is returned in the
MCP-Session-Idresponse header. - Follow-up requests must include that header.
- If a session is missing or expired, the request fails and the client is expected to initialize again.
Session storage
Session state can live in one of two places:
- memory: useful for local development and simple single-process workflows
- Redis: useful for durable/shared hosted session continuity
The session backend is selected by MCP_SESSION_BACKEND and
MCP_SESSION_STORE_URL.
Streaming and replay
This server supports streamable HTTP MCP behavior:
- a client can ask for
text/event-stream - the server can return SSE instead of a plain JSON body
- the client can reconnect with
Last-Event-ID - the server can replay missed events as long as they are still within the replay window
The replay window is controlled by MCP_SESSION_REPLAY_TTL_SECONDS.
Tool discovery and execution
Each tool has:
- a name
- a description
- an
inputSchema - a Python handler
That means a client can discover tools dynamically through tools/list, then
construct a valid tools/call request without knowing Python details.
Short Example
In plain language, a client does something like this:
- Send
initialize. - Receive capabilities and
MCP-Session-Id. - Send
tools/list. - Read the published tool schemas.
- Send
tools/callfor a tool such assearchorfetch. - Receive the tool result in MCP format.
That is the core of how this server works. The sections below cover the exact runtime configuration, deployment, verification, and hosted contract details.
Local dependency bootstrap
The setup sections above are the recommended first-time path. This section and the ones that follow are the deeper runtime and operator reference details.
Install the hosted runtime dependencies from the repository root:
python3 -m pip install -e .
Minimal local runtime path
Use the minimal local runtime path when you only need local development and do
not need Redis-backed session durability. bash scripts/dev_local.sh is the
canonical local startup entry point, and it loads the local runtime defaults
from .env.local automatically.
bash scripts/dev_local.sh
This path does not require cloud provisioning or local infrastructure under
infrastructure/, and it remains outside any provider adapter prerequisites in the shared platform contract.
Local runtime verification:
.env.localis the dedicated local runtime defaults file for this path.- The script fails immediately if
.env.localis missing and tells you to restore the local runtime defaults file. - Successful startup means the app is running with the baseline local profile and no hosted deployment-only inputs.
Hosted deployment-only inputs remain in hosted deployment documentation and .env.example; they are not required for the minimal local runtime path.
Hosted-like local verification path
Use the hosted-like local verification path when you need to exercise the same Redis-backed session settings used by the hosted deployment without provisioning cloud infrastructure first:
docker compose -f infrastructure/local/compose.yaml up -d
./scripts/local_compose.sh up -d
LOCAL_SESSION_MODE=hosted bash scripts/dev_local.sh
When finished:
./scripts/local_compose.sh down
These local and hosted-like local workflows are execution modes of the shared platform contract. They remain separate from the primary hosted provider adapter and any future provider adapter.
Hosted-like local verification keeps the same startup entry point but changes the local session profile:
- baseline local values still come from
.env.local - hosted-like local overrides are documented in
infrastructure/local/.env.example - the Redis bootstrap path must be running before
LOCAL_SESSION_MODE=hosted bash scripts/dev_local.sh - if the durable-session dependency is unavailable, start
docker compose -f infrastructure/local/compose.yaml up -dor./scripts/local_compose.sh up -dand retry
Engineering workflow
Feature specification, planning, and implementation in this repository follow a mandatory Red-Green-Refactor TDD workflow. Every feature plan and task list must include explicit failing-test, minimal-pass, and refactor phases. Work is not complete until the full repository test suite has been run after the final code changes and every test is passing. All new or modified Python functions must include reStructuredText docstrings before review and merge.
Runtime configuration profiles
MCP_ENVIRONMENTis required and must be one ofdev,staging, orprod.- Startup fails fast when required profile configuration is missing or invalid.
YOUTUBE_API_KEYis required forstagingandprod.MCP_AUTH_TOKENis required forstagingandprodhosted MCP access and acts as the shared bearer secret for protected/mcprequests.MCP_ALLOWED_ORIGINSdefines the browser origin allowlist for protected/mcprequests.MCP_ALLOW_ORIGINLESS_CLIENTScontrols whether non-browser callers withoutOrigincan proceed to authentication checks.MCP_SESSION_BACKENDselects the hosted session backend (memoryfor local-only or shared-memory tests,redisfor durable hosted deployments).MCP_SESSION_STORE_URLpoints at the shared durable session backend when hosted session durability is required.MCP_SECRET_ACCESS_MODEdocuments how the hosted runtime receives secret-backed configuration.MCP_SECRET_REFERENCE_NAMESrecords the secret references expected to be available to the hosted runtime.MCP_SESSION_CONNECTIVITY_MODELdocuments the provider-specific connectivity path used to reach the durable session backend.- The Terraform-managed hosted network layer now provisions the VPC network, subnet, and session connector reference used by the supported GCP durable-session path.
MCP_SESSION_DURABILITY_REQUIREDforces/readyto fail unless a healthy shared session backend is available.MCP_SESSION_TTL_SECONDScontrols how long an inactive hosted session remains reusable.MCP_SESSION_REPLAY_TTL_SECONDScontrols how long reconnect replay history is retained forLast-Event-IDresume flows.GET /healthreturns liveness ({"status":"ok"}).GET /readyreturns readiness based on startup config/secret validation.
Browser-originated hosted MCP access
- Browser-originated access is explicitly supported only for
/mcp. - Approved browser clients must pass preflight before sending authenticated hosted MCP requests.
- Successful browser preflight for
/mcpreturnsAccess-Control-Allow-Origin,Access-Control-Allow-Methods, andAccess-Control-Allow-Headers. - Successful approved-origin
/mcpresponses exposeMCP-Session-Id,MCP-Protocol-Version, andX-Stream-Idso browser clients can continue hosted MCP flows. - Denied origins and unsupported browser request patterns fail explicitly instead of relying on implicit browser blocking.
Representative browser preflight example:
curl -i -X OPTIONS \
-H 'Origin: http://localhost:3000' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: authorization, content-type' \
https://YOUR_SERVICE_URL/mcp
Cloud Run foundation deployment
If you are deploying for the first time, follow Setup From Scratch: Hosted On GCP earlier in this README first. This section is the lower-level hosted
deployment reference.
The hosted deployment steps below describe the current primary hosted provider adapter. FND-020 preserves these steps while separating them from the provider-neutral application deployment model.
Required deployment inputs:
PROJECT_IDREGIONSERVICE_NAMEIMAGE_REFERENCESERVICE_ACCOUNT_EMAILMCP_SERVER_IMPLEMENTATION(uvicorn)MCP_ASGI_APP(mcp_server.cloud_run_entrypoint:app)MCP_SECRET_ACCESS_MODE(secret_manager_envfor Cloud Run hosted secret injection)MCP_SECRET_REFERENCE_NAMES(comma-separated runtime secret references, normally matchingSECRET_REFERENCES)PUBLIC_INVOCATION_INTENT(public_remote_mcpfor trusted public remote MCP environments,private_onlyotherwise)MCP_ENVIRONMENTMCP_AUTH_REQUIREDMCP_ALLOWED_ORIGINSMCP_ALLOW_ORIGINLESS_CLIENTSMIN_INSTANCESMAX_INSTANCESCONCURRENCYTIMEOUT_SECONDSSECRET_REFERENCES(YOUTUBE_API_KEYandMCP_AUTH_TOKENare required forstagingandprod)INFRA_OUTPUTS_FILE(optional Terraformoutput -jsonhandoff file for pre-provisioned infrastructure)
When you use the supported GCP Terraform path, deployment evidence also carries the managed hosted-network references exported by infrastructure reconciliation. That includes the session connector reference and the managed network references needed for deployment review and hosted verification.
Execute the deployment workflow with explicit revision settings:
PROJECT_ID=example-project \
REGION=us-central1 \
SERVICE_NAME=youtube-mcp-server \
IMAGE_REFERENCE=us-central1-docker.pkg.dev/example-project/apps/youtube-mcp-server:sha \
SERVICE_ACCOUNT_EMAIL=youtube-mcp-server@example-project.iam.gserviceaccount.com \
MCP_SERVER_IMPLEMENTATION=uvicorn \
MCP_ASGI_APP=mcp_server.cloud_run_entrypoint:app \
MCP_SECRET_ACCESS_MODE=secret_manager_env \
MCP_SECRET_REFERENCE_NAMES=YOUTUBE_API_KEY,MCP_AUTH_TOKEN \
PUBLIC_INVOCATION_INTENT=public_remote_mcp \
MCP_ENVIRONMENT=staging \
MCP_AUTH_REQUIRED=true \
MCP_ALLOWED_ORIGINS=https://chat.openai.com \
MCP_ALLOW_ORIGINLESS_CLIENTS=true \
MCP_SESSION_BACKEND=redis \
MCP_SESSION_STORE_URL=redis://REDIS_HOST:6379/0 \
MCP_SESSION_CONNECTIVITY_MODEL=serverless_vpc_connector \
MCP_SESSION_DURABILITY_REQUIRED=true \
MIN_INSTANCES=0 \
MAX_INSTANCES=2 \
CONCURRENCY=20 \
TIMEOUT_SECONDS=180 \
SECRET_REFERENCES=YOUTUBE_API_KEY,MCP_AUTH_TOKEN \
bash scripts/deploy_cloud_run.sh
If you provisioned the hosted platform through the Terraform workflow in
infrastructure/gcp/, you can pass the exported outputs file directly into the
deployment workflow instead of retyping the provisioned values:
set -a
source .env
set +a
INFRA_OUTPUTS_FILE=artifacts/gcp-foundation-outputs.json \
IMAGE_REFERENCE=us-central1-docker.pkg.dev/example-project/apps/youtube-mcp-server:sha \
bash scripts/deploy_cloud_run.sh
The deployment workflow now returns a JSON deployment record containing the
deployment outcome, revision name, hosted service URL, public invocation
intent, published connection point, and runtime settings summary. Save that
record and use it as the handoff into hosted verification.
The runtime settings summary includes serverImplementation=uvicorn and
appModule=mcp_server.cloud_run_entrypoint:app.
Example:
PROJECT_ID=example-project \
REGION=us-central1 \
SERVICE_NAME=youtube-mcp-server \
IMAGE_REFERENCE=us-central1-docker.pkg.dev/example-project/apps/youtube-mcp-server:sha \
SERVICE_ACCOUNT_EMAIL=youtube-mcp-server@example-project.iam.gserviceaccount.com \
MCP_SERVER_IMPLEMENTATION=uvicorn \
MCP_ASGI_APP=mcp_server.cloud_run_entrypoint:app \
MCP_SECRET_ACCESS_MODE=secret_manager_env \
MCP_SECRET_REFERENCE_NAMES=YOUTUBE_API_KEY,MCP_AUTH_TOKEN \
PUBLIC_INVOCATION_INTENT=public_remote_mcp \
MCP_ENVIRONMENT=staging \
MCP_AUTH_REQUIRED=true \
MCP_ALLOWED_ORIGINS=https://chat.openai.com \
MCP_ALLOW_ORIGINLESS_CLIENTS=true \
MCP_SESSION_BACKEND=redis \
MCP_SESSION_STORE_URL=redis://REDIS_HOST:6379/0 \
MCP_SESSION_CONNECTIVITY_MODEL=serverless_vpc_connector \
MCP_SESSION_DURABILITY_REQUIRED=true \
MIN_INSTANCES=0 \
MAX_INSTANCES=2 \
CONCURRENCY=20 \
TIMEOUT_SECONDS=180 \
SECRET_REFERENCES=YOUTUBE_API_KEY,MCP_AUTH_TOKEN \
bash scripts/deploy_cloud_run.sh > artifacts/cloud-run-deployment.json
Verify the hosted foundation revision after deployment:
PYTHONPATH=src python3 scripts/verify_cloud_run_foundation.py \
--deployment-record artifacts/cloud-run-deployment.json \
--auth-token "$MCP_AUTH_TOKEN" \
--evidence-file artifacts/cloud-run-verification.txt
Set PUBLIC_INVOCATION_INTENT=public_remote_mcp only for environments that
should be intentionally reachable by trusted remote MCP consumers. Use
PUBLIC_INVOCATION_INTENT=private_only for environments that should remain
outside the public remote MCP workflow. Public invocation intent does not
replace Authorization: Bearer ...; it only determines whether the hosted
Cloud Run service is intentionally reachable.
Operator diagnosis now follows two layers:
cloud_platform: the publicreachabilityprobe failed before the request reached the hosted MCP application.mcp_application: the hosted service was reachable, but the protected/mcprequest failed due to bearer-token or browser-origin rules.
The hosted verifier now exercises the streamable MCP transport rather than the
older bare POST /mcp flow. It performs initialize, captures the returned
MCP-Session-Id, reuses that session for subsequent POST and GET MCP
requests, validates reconnect behavior with Last-Event-ID, and accepts both
application/json and text/event-stream responses as required by the hosted
transport contract. Covered hosted MCP failures now use numeric error.code
values and stable error.data.category details rather than legacy string-style
top-level error codes. It now records a public reachability check before
liveness, readiness, and authenticated /mcp verification so operators can
separate Cloud Run public access from MCP-layer authentication.
It also records deployment-evidence, secret-access, and
session-connectivity checks so operators can distinguish missing runtime
secret access from missing durable session connectivity before session
continuation is attempted.
When hosted verification reports SECRET_ACCESS_UNAVAILABLE or
SECRET_REFERENCE_MISSING, inspect the Cloud Run runtime service account,
MCP_SECRET_ACCESS_MODE, and MCP_SECRET_REFERENCE_NAMES first. When hosted
verification reports a session-connectivity failure, inspect
MCP_SESSION_CONNECTIVITY_MODEL, the exported session connector reference, the
managed session network reference, and the Redis backend reference first.
Automated hosted deployment
Push-triggered hosted deployment is primarily defined in cloudbuild.yaml.
Cloud Build is the primary auto-deploy path for pushes to main when your GCP
trigger is configured to use that file.
The GitHub Actions workflow at .github/workflows/hosted-deploy.yml is a
manual fallback for operators and open source users who prefer GitHub-hosted
automation. The GitHub Actions workflow is a manual fallback, and it is
intentionally workflow_dispatch only so it does not race with the Cloud Build
trigger on main.
Both automation paths keep the same repository-managed rollout path intact:
- validate bootstrap prerequisites
- run
pytestandruff check . - build and publish the current image
- run
terraform -chdir=infrastructure/gcp apply - export Terraform outputs to
artifacts/gcp-foundation-outputs.json - deploy through
scripts/deploy_cloud_run.sh - verify through
scripts/verify_cloud_run_foundation.py - upload the deployment and verification artifacts
For environments that require durable hosted session connectivity, managed network bootstrap is part of step 4. In other words, network reconciliation happens before deploy and remains inside the same reviewed automation path. Stated directly: network reconciliation happens before deploy for the supported hosted path.
The workflow does not replace the repository deployment logic with a direct image-only Cloud Run update. Terraform outputs remain the handoff between infrastructure reconciliation and application rollout.
Push-triggered deployment bootstrap prerequisites
Before trusting a push to main as a hosted deployment trigger, confirm these
one-time bootstrap prerequisites:
These one-time bootstrap inputs remain outside the recurring automated deployment run.
- repository automation can authenticate to GCP through
GCP_WORKLOAD_IDENTITY_PROVIDERandGCP_SERVICE_ACCOUNT - repository variables provide
GCP_PROJECT_ID,GCP_REGION,GCP_SERVICE_NAME,GCP_ARTIFACT_REGISTRY_REPOSITORY, andGCP_TERRAFORM_VAR_FILE - the target environment already contains operator-managed secret values for
YOUTUBE_API_KEYandMCP_AUTH_TOKEN - the Artifact Registry repository and Terraform variable file already exist for the target environment
If any bootstrap prerequisite is missing, the workflow fails before it reports a hosted deployment result.
The failure boundary is intentional and should remain operator-visible:
bootstrap_input_failuremeans one-time bootstrap inputs were missing before hosted reconciliation could start.network_reconcile_failuremeans managed network bootstrap failed during infrastructure reconciliation.- later deploy or hosted verification failures happen only after those earlier gates succeed.
For the primary path, configure your existing Cloud Build trigger for main to
read cloudbuild.yaml. Use the GitHub Actions workflow only when you want a
manual fallback run or a community-managed alternative outside your primary GCP
trigger.
Secret boundary for automated deployment
Repository automation is allowed to wire secret references, authenticate to the cloud environment, export infrastructure outputs, deploy the hosted revision, and run hosted verification.
Repository automation is not allowed to create, print, rotate, or commit secret
values. YOUTUBE_API_KEY and MCP_AUTH_TOKEN remain operator-managed secret
values even when the workflow is fully automated.
Hosted deployment artifacts
The workflow publishes these artifacts for each push-driven hosted rollout:
artifacts/image-reference.txtartifacts/gcp-foundation-outputs.jsonartifacts/cloud-run-deployment.jsonartifacts/cloud-run-verification.jsonartifacts/cloud-run-verification.txt
Treat artifacts/cloud-run-deployment.json as the handoff from deploy to
verification and artifacts/cloud-run-verification.json as the final release
gate summary.
Manual streamable MCP verification examples:
Rejected initialize requests must not return MCP-Session-Id and must not create
usable hosted continuation state:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-d '{"jsonrpc":"2.0","id":"req-init-invalid","method":"initialize","params":{}}' \
https://YOUR_SERVICE_URL/mcp
Expected result: invalid initialize error with no MCP-Session-Id header.
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-d '{"jsonrpc":"2.0","id":"req-init","method":"initialize","params":{"clientInfo":{"name":"manual","version":"1.0.0"}}}' \
https://YOUR_SERVICE_URL/mcp
Use the returned MCP-Session-Id for subsequent requests:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-H 'MCP-Session-Id: SESSION_ID' \
-d '{"jsonrpc":"2.0","id":"req-call","method":"tools/call","params":{"name":"server_ping","arguments":{}}}' \
https://YOUR_SERVICE_URL/mcp
Successful hosted JSON responses now use protocol-native MCP bodies:
{
"jsonrpc": "2.0",
"id": "req-call",
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"ok\",\"timestamp\":\"...\"}",
"structuredContent": {
"status": "ok",
"timestamp": "..."
}
}
],
"isError": false
}
}
Representative hosted failure responses now use numeric MCP error codes:
{
"jsonrpc": "2.0",
"id": "req-invalid",
"error": {
"code": -32602,
"message": "arguments must be an object",
"data": {
"category": "invalid_argument"
}
}
}
Representative hosted resource-missing failures use the shared numeric mapping:
{
"jsonrpc": "2.0",
"id": "req-missing-tool",
"error": {
"code": -32001,
"message": "Tool not found.",
"data": {
"category": "unknown_tool",
"toolName": "missing_tool"
}
}
}
Tool discovery responses now include complete baseline tool metadata, including
inputSchema, so hosted MCP clients can construct valid calls from tools/list
without separate tool documentation.
Representative hosted tools/list output still includes the deep research
tools used in earlier foundation slices:
{
"jsonrpc": "2.0",
"id": "req-list",
"result": {
"tools": [
{
"name":"search",
"description":"Search the retrieval corpus for relevant documents.",
"inputSchema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1}},"additionalProperties":false}
},
{
"name":"fetch",
"description":"Fetch the full contents of a previously identified document.",
"inputSchema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","minLength":1}},"additionalProperties":false}
}
]
}
}
For retrieval-contract completeness work, hosted discovery is expected to be strong enough that clients can build:
- a valid
searchrequest from the publishedqueryschema - a valid
fetchrequest from the publishedidschema - an explicit invalid legacy-shape request that proves the compatibility boundary
Hosted session durability verification expects the hosted tool catalog to remain discoverable and then validates session continuation through the same protected MCP entrypoint.
Representative hosted POST continuation example:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-H 'MCP-Session-Id: SESSION_ID' \
-d '{"jsonrpc":"2.0","id":"req-search","method":"tools/call","params":{"name":"search","arguments":{"query":"remote MCP research"}}}' \
https://YOUR_SERVICE_URL/mcp
Representative hosted fetch examples derived from discovery:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-H 'MCP-Session-Id: SESSION_ID' \
-d '{"jsonrpc":"2.0","id":"req-fetch","method":"tools/call","params":{"name":"fetch","arguments":{"id":"doc-remote-mcp-001"}}}' \
https://YOUR_SERVICE_URL/mcp
Representative successful retrieval payload:
{
"id":"doc-remote-mcp-001",
"url":"https://example.com/remote-mcp-research",
"content": [
{
"type": "text",
"text": "{\"id\":\"doc-remote-mcp-001\",\"title\":\"Remote MCP Research Workflows\",\"text\":\"Remote MCP research workflows depend on discoverable tools and stable document retrieval.\",\"url\":\"https://example.com/remote-mcp-research\",\"metadata\":{\"sourceName\":\"Example Research\"}}"
}
]
}
Representative unsupported legacy-shape example:
curl -i \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-H 'MCP-Session-Id: SESSION_ID' \
-d '{"jsonrpc":"2.0","id":"req-fetch-legacy","method":"tools/call","params":{"name":"fetch","arguments":{"resourceId":"res_remote_mcp_001"}}}' \
https://YOUR_SERVICE_URL/mcp
Representative hosted reconnect example:
curl -i \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-H 'MCP-Session-Id: SESSION_ID' \
-H 'Last-Event-ID: STREAM_EVENT_ID' \
https://YOUR_SERVICE_URL/mcp
Open or resume an SSE stream without a replay cursor:
curl -i \
-H 'Accept: text/event-stream' \
-H 'Authorization: Bearer YOUR_MCP_AUTH_TOKEN' \
-H 'MCP-Session-Id: SESSION_ID' \
-H 'Last-Event-ID: STREAM_EVENT_ID' \
https://YOUR_SERVICE_URL/mcp
Protected /mcp requests now follow these hosted security rules:
- Browser callers that send
Originmust matchMCP_ALLOWED_ORIGINS. - Non-browser callers may omit
Originonly whenMCP_ALLOW_ORIGINLESS_CLIENTS=true. - Protected
/mcprequests must sendAuthorization: Bearer .... - Missing auth returns
401, denied origin returns403, and malformed security headers return400.
You can still provide --service-url, --revision-name, --service-name,
--runtime-identity, --min-instances, --max-instances, --concurrency,
and --timeout-seconds directly when a deployment record file is not available.
Hosted runtime requests emit structured JSON log events to runtime stdout/stderr
with timestamp, severity, requestId, path, status, latencyMs, and
toolName when the request reaches tool dispatch.
Start the migrated hosted runtime locally with the ASGI entrypoint:
PYTHONPATH=src python3 -m uvicorn mcp_server.cloud_run_entrypoint:app --host 0.0.0.0 --port 8080
The verification output must record pass/fail results for:
reachabilitylivenessreadinessinitialize-invalid-no-sessioninitialize-success-session-createdinitialize-retry-successinitializelist-toolssearch-tool-call-openaifetch-tool-call-openaisearch-tool-call-emptyfetch-tool-call-legacy-shapefetch-tool-call-missingsession-post-continuationsession-get-continuationsession-reconnectsession-invalidbrowser-preflight-approvedbrowser-request-approvedbrowser-origin-deniedbrowser-request-unsupported