Google Threat Intelligence MCP Server

A production-ready, highly optimized Model Context Protocol (MCP) server for Google Threat Intelligence (GTI) (incorporating VirusTotal and Mandiant threat analytics). This server supports cloud-native network deployments via Stateless HTTP (streamable-http) or Server-Sent Events (SSE), making it fully compatible with Google Cloud Run or any other container-native environment.

Project Origin & Deployment Philosophy

This repository is 100% based on the official Google open-source implementation hosted in the google/mcp-security repository.

While the official project is designed as a broad, developer-focused, multi-tool mono-repo, this project was created specifically to empower non-technical users, security analysts, and IT administrators to deploy a secure, enterprise-grade Google Threat Intelligence (GTI) MCP server in minutes with zero friction.

🔍 How This Repository Differs from the Official Mono-Repo

Related MCP server: Google Threat Intelligence MCP Server

Table of Contents

1. Project Origin & Deployment Philosophy

2. Core Features

3. Configuration & Customization (Optional)

4. Getting Started

5. Local Development & Setup

   • Verifying Your Local SSE Server (No Agent Required)

6. Containerization & Docker

7. Production Google Cloud Run Deployment (Strict Secret Manager)

   • Verifying Your Cloud Run Stateless HTTP Server (No Agent Required)

8. Gemini Enterprise Integration (Optional)

Core Features

This MCP server exposes high-performance threat intelligence endpoints to any compatible LLM agent.

🔍 Intelligence & Hunting

• search_iocs(query, limit): Queries Indicators of Compromise (IOCs) using advanced search filters.

• get_hunting_ruleset & get_entities_related_to_a_hunting_ruleset: Accesses and maps structured threat detection signatures.

📁 Files & Artifacts

• get_file_report(hash): Inspects MD5, SHA1, or SHA256 hashes to check multi-engine detections and threat actor classifications.

• get_file_behavior_report(id) & get_file_behavior_summary(hash): Retreives deep sandbox execution data.

🌐 Domains, IPs, and URLs

• get_domain_report(domain) & get_entities_related_to_a_domain: Resolves passive DNS mappings, registrar details, and reputational classifications.

• get_ip_address_report(ip_address): Retrieves geolocations, Autonomous System Numbers (ASN), and detections.

• get_url_report(url) & get_entities_related_to_an_url: Inspects specific URLs.

Configuration & Customization (Optional)

This project is pre-configured and completely ready to run out-of-the-box. You do not need to modify any of these files to deploy. However, if you have specific network or architectural requirements, you can customize these configuration files:

Getting Started

Regardless of whether you plan to run the server locally, package it in a container, or deploy it directly to Google Cloud Run, you must first clone the repository and navigate into the project directory:

# Clone this repository
git clone <your-repository-url>

# Enter the project directory
cd gti-mcp-server

🚀 Choose Your Path

Once inside the directory, choose the section that matches your goal:

• 💻 Laptop (Python): Proceed to Local Development & Setup.

• 🐳 Local Docker Container: Skip to Containerization & Docker.

• ☁️ Google Cloud Run (Production): Skip to Production Google Cloud Run Deployment.

Local Development & Setup

Prerequisites

• Python 3.11 or higher.

• A valid Google Threat Intelligence (VirusTotal) API key.

Quick Start (Local Python)

1. Configure your API Key (In-Memory Only): Export your Google Threat Intelligence API key directly in your terminal session. This key resides only in your shell's temporary RAM and is never written to disk:

   export VT_APIKEY="your_actual_gti_api_key_here"

2. Install the package and dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install -e .

3. Run the server locally:

   Start the server in SSE/HTTP network mode. This boots the server as an HTTP service listening on port 8000 by default and outputs active startup logs once initialized:

   gti-mcp-server

🧪 Verifying Your Local SSE Server (No Agent Required)

Because Model Context Protocol (MCP) uses Server-Sent Events (SSE) under the hood, you can verify your local server using standard command-line tools without needing a desktop AI client or agent installed.

This test requires two additional terminal windows (or tabs), leaving your local server running in your current window from the previous step:

Step 1: Run the Server (Terminal Window 1)

This is the server you already started in the previous Quick Start step! (If you stopped it, simply open Terminal Window 1, activate your virtual environment, and run gti-mcp-server again). Leave this server running.

Step 2: Open the Event Stream (Terminal Window 2)

Establish a streaming SSE connection. Because SSE is a streaming protocol, this connection will stay open ("hanging") to capture real-time responses:

curl -i -N http://localhost:8000/sse

What you will see: It will connect instantly and output the initial dynamic connection endpoint along with a unique session ID:

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

event: endpoint
data: /messages/?session_id=a1b2c3d4e5f6...

Leave this window running and copy your generated session_id.

Step 3: Perform the Handshake and Run Queries (Terminal Window 3)

In your third terminal window, run the following three requests sequentially (substituting your copied session_id) to complete the protocol handshake and list your tools:

1. Initialize the MCP Session:

   curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
         "protocolVersion": "2024-11-05",
         "capabilities": {},
         "clientInfo": {
           "name": "curl-test-client",
           "version": "1.0"
         }
       }
     }' \
     "http://localhost:8000/messages/?session_id=YOUR_ACTIVE_SESSION_ID"

   (Check Terminal Window 1: you will see a streamed message event containing the server's protocol capabilities).

2. Confirm Handshake Completion:

   curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "method": "notifications/initialized"
     }' \
     "http://localhost:8000/messages/?session_id=YOUR_ACTIVE_SESSION_ID"

3. List Available Threat Intelligence Tools:

   curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/list",
       "params": {}
     }' \
     "http://localhost:8000/messages/?session_id=YOUR_ACTIVE_SESSION_ID"

Look back at Terminal Window 1: You will see a complete, beautiful JSON-RPC stream containing all your Google Threat Intelligence capabilities (get_file_report, search_iocs, etc.)!

Containerization & Docker (Alternative)

This server is pre-configured with a secure, multi-stage Docker build spec and a companion Docker Compose layout.

Since docker-compose.yml is configured to build your container automatically, you do not need to run a separate build command! You can compile the image and launch the container on-the-fly with a single command:

# Make sure your API key is in your active terminal environment
export VT_APIKEY="your_actual_gti_api_key_here"

# Compile and start the server in the background
docker compose up -d

This starts the containerized server in the background, maps port 8000 to port 8000 on your host computer, and passes your terminal's ${VT_APIKEY} directly into the secure container memory.

Production Google Cloud Run Deployment (Strict Secret Manager)

This section provides a secure-by-default, step-by-step walkthrough for deploying to Google Cloud Run. It uses Google Secret Manager for credential storage and restricts invocations using GCP IAM OIDC Authentication (disallowing unauthenticated access).

Step 1: Set Your Deployment Variables

Replace the placeholder values below with your GCP details:

PROJECT_ID="your-gcp-project-id"   # Your GCP Project ID
REGION="us-central1"               # GCP Region to deploy to
REPO="mcp-servers"                 # Artifact Registry Repository name
IMAGE="gti-mcp-server"             # Container Image name

Step 2: Authenticate and Enable Required GCP Services

Authenticate your local shell session with Google Cloud and enable the APIs required for container hosting and secure secret storage:

# Authenticate your local shell session with Google Cloud
gcloud auth login

# Set your active gcloud project context
gcloud config set project ${PROJECT_ID}

# Enable Secret Manager, Artifact Registry, and Cloud Run APIs
gcloud services enable \
  secretmanager.googleapis.com \
  artifactregistry.googleapis.com \
  run.googleapis.com

Step 3: Secure your API Key in Google Secret Manager

Create a managed secret to host your Google Threat Intelligence (VirusTotal) API key securely:

1. Create the Secret container:

   gcloud secrets create VT_APIKEY --replication-policy="automatic"

2. Add your API key value as version 1 of the secret: Replace YOUR_ACTUAL_GTI_API_KEY with your actual token:

   echo -n "YOUR_ACTUAL_GTI_API_KEY" | gcloud secrets versions add VT_APIKEY --data-file=-

Step 4: Grant Access to the Cloud Run Service Account

Cloud Run services run under a designated service account. By default, Cloud Run uses the Compute Engine default service account to call other GCP APIs.

1. Get your Project Number:

   PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
   echo "Your Project Number is: ${PROJECT_NUMBER}"

2. Determine the Default Service Account Email: The default service account email follows the pattern: ${PROJECT_NUMBER}-compute@developer.gserviceaccount.com

3. Grant Secret Accessor permission to this service account: This authorizes the Cloud Run container to fetch and decrypt the secret at startup:

   gcloud secrets add-iam-policy-binding VT_APIKEY \
     --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"

Step 5: Deploy to Cloud Run (Choose Your Path)

You can choose either of these two paths to compile and deploy your server. Option A is highly recommended for non-technical users as it does not require Docker or manual registry configurations!

🚀 Option A: Direct Source-to-Cloud Deployment (No Local Docker Required)

This is the fastest, simplest method. Google Cloud will securely package your source directory, upload it, run Google Cloud Build in the background using your Dockerfile, automatically provision a private Artifact Registry under the hood, and deploy the service.

Simply run this single command from your repository root:

gcloud run deploy gti-mcp-server \
  --source . \
  --region=${REGION} \
  --platform=managed \
  --no-allow-unauthenticated \
  --set-secrets="VT_APIKEY=VT_APIKEY:latest" \
  --set-env-vars="TRANSPORT=http,STATELESS=1" \
  --port=8000 \
  --max-instances=5 \
  --cpu=1 \
  --memory=512Mi \
  --no-cpu-throttling

🐳 Option B: Traditional Docker Build, Push, & Deploy

Choose this path if you prefer to compile, tag, and push your container image using Docker running locally on your laptop:

1. Create the Docker repository in Artifact Registry:

   gcloud artifacts repositories create ${REPO} \
     --repository-format=docker \
     --location=${REGION} \
     --description="MCP Servers Repository"

2. Authenticate Docker to push to your GCP registry:

   gcloud auth configure-docker ${REGION}-docker.pkg.dev

3. Build and Tag the image (Intel/AMD64 target format):

   docker build --platform linux/amd64 -t ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${IMAGE}:latest .

4. Push the image to GCP:

   docker push ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${IMAGE}:latest

5. Deploy the pushed image to Cloud Run:

    gcloud run deploy gti-mcp-server \
      --image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/${IMAGE}:latest \
      --region=${REGION} \
      --platform=managed \
      --no-allow-unauthenticated \
      --set-secrets="VT_APIKEY=VT_APIKEY:latest" \
      --set-env-vars="TRANSPORT=http,STATELESS=1" \
      --port=8000 \
      --max-instances=5 \
      --cpu=1 \
      --memory=512Mi \
      --no-cpu-throttling

Step 6: Retrieve and Save Your Cloud Run Service URL

Once successfully deployed, retrieve your Cloud Run live service URL and export it as an environment variable in your terminal session. This variable is required to register your server with Gemini Enterprise later:

SERVICE_URL=$(gcloud run services describe gti-mcp-server --region=${REGION} --format="value(status.url)")
echo "Your live Service URL is: ${SERVICE_URL}"

[NOTE] Setting host="0.0.0.0" in our server configuration ensures that the container is fully compatible with Cloud Run and can accept incoming production connections smoothly.

🧪 Verifying Your Cloud Run Stateless HTTP Server (No Agent Required)

Once your service is deployed, you can verify that the live production server is functioning, authenticated, and communicating properly over the network without needing to set up an AI agent first.

Using the official Google Cloud secure proxy is the simplest, safest, and most recommended method because it handles OAuth authentication and Host headers automatically.

This test requires two separate terminal windows (or tabs):

Step 1: Start the Cloud Run Proxy (Terminal Window 1)

Run this command to boot up a secure local authentication tunnel mapped to port 8000:

gcloud run services proxy gti-mcp-server --region=${REGION} --port 8000

Leave this terminal running. It will output a confirmation log indicating that port 8000 is proxying to your secure Cloud Run service.

Step 2: Query the Tools List (Terminal Window 2)

In your second terminal window, send a single JSON-RPC POST request to the proxied server at /mcp to list all available tools:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }' \
  "http://localhost:8000/mcp"

What you will see: It will connect instantly and output a beautiful JSON-RPC response containing your entire suite of Google Threat Intelligence tools (get_file_report, search_iocs, etc.) served directly from your secure Cloud Run deployment!

Gemini Enterprise Integration (Optional)

You can easily connect and register this secure Cloud Run MCP server directly with your Gemini Enterprise App (such as default-chat within Vertex AI Agent Builder) using a 100% command-line driven Discovery Engine custom MCP data store workflow.

Follow these command-driven steps to enable the required APIs, configure your OAuth identity provider, create your data store, authorize security, enable threat intelligence actions, and link them to Gemini:

Step 1: Enable Required APIs

Enable the advanced core APIs required for Discovery Engine custom datastores first, as initialization may take a minute:

gcloud services enable discoveryengine.googleapis.com \
  --project=${PROJECT_ID}

Step 2: Define Your OAuth Endpoints

Configure your session variables for your OAuth identity provider (required by Discovery Engine to federate and authenticate custom MCP servers):

# Default Google Cloud Identity OAuth 2.0 endpoints (change these if you are using a custom/external Identity Provider)
AUTH_URL="https://accounts.google.com/o/oauth2/v2/auth"
TOKEN_URL="https://oauth2.googleapis.com/token"

Step 3: Create an OAuth Client ID

Because OAuth Clients cannot be created programmatically via gcloud APIs, you must create one manually in the Google Cloud Console:

1. Navigate to the Google Cloud Console API Credentials page.

2. Click Create Credentials > OAuth client ID.

3. Select Web application as the application type.

4. Name your client (e.g., GTI MCP Server Client).

5. Under Authorized redirect URIs, add any redirect URIs if required by your identity environment.

6. Click Create and copy your Client ID and Client Secret.

Once you have your credentials, define them in your active terminal session:

CLIENT_ID="your-client-id"                      # Replace with your copied OAuth Client ID
CLIENT_SECRET="your-client-secret"              # Replace with your copied OAuth Client Secret

Step 4: Create the Custom MCP Data Store (via setUpDataConnector REST API)

Because the discoveryengine command group is not standard in the public gcloud SDK, use curl to invoke the Discovery Engine custom MCP setup API directly.

First, define your Discovery Engine settings:

LOCATION="us"                           # Discovery Engine location (e.g., us, global)
COLLECTION_ID="gti-mcp-server-collection"  # Your unique collection identifier
DISPLAY_NAME="Google Threat Intelligence Tools"

Now, execute the API call to establish a federated custom MCP connector:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionDisplayName": "'"${DISPLAY_NAME}"'",
    "dataConnector": {
      "dataSource": "custom_mcp",
      "connectorSourceId": "custom_mcp",
      "params": {
        "oauth_access_token": "unused",
        "auth_type": "AUTHORIZATION_TYPE_UNDEFINED"
      },
      "refreshInterval": "86400s",
      "entities": [
        {
          "entityName": "mcp_data"
        }
      ],
      "dataSourceVersion": 1,
      "staticIpEnabled": false,
      "actionConfig": {
        "actionParams": {
          "instance_uri": "'"${SERVICE_URL}"'/mcp",
          "auth_uri": "'"${AUTH_URL}"'",
          "token_uri": "'"${TOKEN_URL}"'",
          "client_id": "'"${CLIENT_ID}"'",
          "client_secret": "'"${CLIENT_SECRET}"'",
          "scopes": "openid",
          "auth_type": "OAUTH",
          "mcp_server_description": "Google Threat Intelligence (GTI) MCP server. Exposes tools to query Indicators of Compromise (IOCs), threat analytics, domain and IP address intelligence, and file/artifact reputation or sandbox analysis.",
          "mcp_agent_instructions": "You are a security analyst assistant. Use this Google Threat Intelligence (GTI) MCP server to analyze security threats, investigate network artifacts (domains, IPs, URLs), and query file reports or execution behaviors. Always validate hash formats (MD5, SHA1, SHA256) and ensure domain inputs are stripped of protocol schemas before querying.",
          "mcp_server_source": "BYO_MCP"
        },
        "createBapConnection": true,
        "isActionConfigured": false
      },
      "connectorModes": [
        "FEDERATED"
      ]
    }
  }' \
  "https://${LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJECT_ID}/locations/${LOCATION}:setUpDataConnector?collectionId=${COLLECTION_ID}"

Step 5: Authorize the Gemini Enterprise Service Account (IAM)

Because your Cloud Run service is locked down securely (--no-allow-unauthenticated), you must explicitly authorize the Gemini Enterprise Discovery Engine system service account to call and invoke your Cloud Run endpoint.

Run these commands to bind the Cloud Run Invoker role:

# Retrieve your active Discovery Engine system service account email
DISCOVERY_ENGINE_SA="service-${PROJECT_NUMBER}@gcp-sa-discoveryengine.iam.gserviceaccount.com"

# Grant it invoker rights to your Cloud Run service
gcloud run services add-iam-policy-binding gti-mcp-server \
    --member="serviceAccount:${DISCOVERY_ENGINE_SA}" \
    --role="roles/run.invoker" \
    --region=${REGION} \
    --project=${PROJECT_ID}

Step 6: Reload and Enable Your Actions (GCP Console UI)

Because the custom actions discovery and OAuth consent handshake are handled securely by Google Cloud Console's frontend, you must perform a one-time manual reload to authorize and activate your threat intelligence tools:

1. Open the Google Cloud Agent Builder Data Stores Console.

2. Select your newly created Google Threat Intelligence Tools data store.

3. Click on the Actions tab on the left-hand navigation pane.

4. If prompted, click Re-authenticate to sign in and complete the OAuth connection.

5. Click the Reload custom actions button. This will connect to your Cloud Run service's /mcp endpoint and dynamically populate all 45+ GTI tools.

6. Select the tools you want to enable, and click Enable actions.

Step 7: Link the Custom MCP Data Store to your Gemini App (GCP Console UI)

Finally, link your newly configured threat intelligence data store to your active Gemini App configuration (e.g., your chat or search application):

1. Open the Gemini Enterprise Console.

2. In the left-hand navigation pane, click on Apps

3. Click on your Gemini Enterprise application

4. In the left-hand navigation pane, click on Connected data stores.

5. Click Add existing data store

6. Select your newly created Google Threat Intelligence Tools data store from the list.

7. Click Connect (or Save) to confirm.

Your Gemini Enterprise conversational app is now fully integrated with real-time Google Threat Intelligence capabilities, securely authorized, and ready to assist your security operations team! 🚀