🌌 Gemini Enterprise MCP Server & Agent Skills

Welcome to the Gemini Enterprise MCP Server.

This open-source project (released under the Apache 2.0 license) implements a Model Context Protocol (MCP) server in TypeScript/ESM to connect AI coding assistants and orchestration frameworks with the powerful Google Cloud Discovery Engine APIs (which power Gemini Enterprise App).

The server handles both Data Plane operations (semantic search, conversational RAG with the Answer API, document retrieval) and Control Plane operations (automated datastore creation, JSON schema management, ranking/Serving Configs tuning, and SaaS connector configurations).

🚀 Key Features & API Coverage

The server provides complete (100% operational coverage) mapping to the core gRPC/REST endpoints of Google Cloud Discovery Engine:

🔍 Data Plane (Semantic Search & RAG)

• Search (gemini_enterprise_search): Semantic search on one data store (datastore_id) or across every source attached to an app (engine_id), with filters, ordering, relevance threshold, pagination and cost-saving search_addon_spec.

• Grounded answers (gemini_enterprise_ask): Answer API with citations, grounding score, related questions and multi-turn sessions.

• Document Retrieval (gemini_enterprise_get_document): Full content and metadata of an indexed document.

⚙️ Control Plane (Administration & Tuning)

• Read-only inspection (gemini_enterprise_inspect, gemini_enterprise_inspect_licenses): Dedicated readOnlyHint: true tools covering every control-plane resource and license pool/usage check so audits and pre-change checks run in parallel with zero confirmation prompts inside Gemini Enterprise.

• Apps (gemini_enterprise_manage_apps): CRUD and IAM for apps (engines).

• Data stores (gemini_enterprise_manage_datastore): CRUD, resource-level IAM on data stores and connector collections, and project-level data store access control.

• Connectors (gemini_enterprise_configure_connector): Real DataConnector API: get, setup, connector runs, and citation_mappings for custom MCP data stores.

• Target sites, documents, schema, controls: website crawling patterns, GCS/BigQuery import and purge, JSON schemas, boost/filter/synonym controls.

• Feature toggles (gemini_enterprise_manage_features): All 38 web app toggles of the API (Projects, Workflow Builder, speech-to-text, Canvas, Skills, orchestration, ...), with a safe enable_all_features and cleanup_invalid_keys.

• Models (gemini_enterprise_manage_models): Model availability (Gemini 4 Argon, 3.8/3.7/3.6 Flash, 3.1 Pro, image models, Claude Opus/Sonnet 5.5) plus a generic model_configs map.

• Assistant (gemini_enterprise_manage_assistant): The real default_assistant: system instructions, models, web grounding, banned phrases, Model Armor, Sensitive Data Protection, Knowledge Catalog, chat history retention.

• Search UI, observability, Knowledge Graph: autocomplete, feedback, pinned links, OpenTelemetry and prompt logging, Knowledge Graph toggles.

• Agents (gemini_enterprise_manage_agents): A2A, Agent Designer (low-code, multi-agent) and ADK agents on Agent Engine, with sharing scope and starter prompts.

• Platform skills (gemini_enterprise_manage_skills): Vertex AI Skill Registry (create, get, retrieve, revisions, patch, delete).

• Operations (gemini_enterprise_get_operation): Poll long-running operations returned by other tools.

• Licenses (gemini_enterprise_manage_licenses): License pools, seat usage, assign and unassign.

Related MCP server: BigQuery MCP Server

🛠️ Installation & Setup

1. Prerequisites

• Node.js: v22 or higher.

• Google Cloud SDK (gcloud) installed and configured.

• An active Google Cloud project with the Discovery Engine API enabled.

2. Local Authentication

Configure your local Application Default Credentials (ADC) pointing to your target GCP project:

gcloud auth application-default login

3. Environment Variables

Create a .env file in the root of the project (or set variables in your shell/IDE environment):

GCP_PROJECT=your-gcp-project-id
GCP_LOCATION=global # optional, defaults to global (supports us, eu, etc.)
GCP_COLLECTION=default_collection # optional, defaults to default_collection

# OPTIONAL BUT RECOMMENDED:
# Set this variable if you encounter a local quota/billing project mismatch error from gcloud.
GOOGLE_CLOUD_QUOTA_PROJECT=your-gcp-project-id

# SECURITY SCOPES (Enforces Least Privilege):
# Comma-separated list of allowed scopes: search, admin, billing.
# Example: Use 'search' for standard coding assistants, and 'search,admin' for SRE agents.
# Defaults to 'search,admin,billing' if not specified.
MCP_SCOPES=search,admin,billing

4. Build the Project

Install dependencies and compile TypeScript files into JavaScript ESM:

npm install
npm run build

🧪 Testing Suite

To ensure stability and facilitate onboarding, the repository includes a suite of testing scripts under the tests/ directory to validate connectivity, security, and the MCP interface:

1. test_mcp_client.mjs (MCP Protocol Handshake): Performs a standard handshake with the MCP server via stdio and prints the list of registered tools with their JSON schemas.

   node tests/test_mcp_client.mjs

2. test_suite_readonly.mjs (GCP Read-Only Validation): Scans the available datastores in the configured GCP project, querying schemas, target sites, serving controls, and testing search queries.

   node tests/test_suite_readonly.mjs

3. test_admin_write.mjs (GCP Control Plane Safe Write/Delete): Executes a complete read/write lifecycle on the Control Plane (creates a temporary synonym control, verifies its existence via list, and immediately deletes it). 100% safe with zero residue left on your Cloud project.

   node tests/test_admin_write.mjs

4. test_agents_write.mjs (Native Agent Lifecycle Safe Write/Delete): Executes a complete lifecycle check on native Discovery Engine Agents (creates a temporary agent, lists and updates it, then deletes it with zero residues remaining).

   node tests/test_agents_write.mjs

5. test_iam.mjs (App IAM Policy Roundtrip Validation): Verifies that retrieving and setting IAM policies on individual Engines/Apps works correctly and safely.

   node tests/test_iam.mjs

6. test_mcp_scopes.mjs (Scope & Security Enforcement Suite): Validates that environment-based tool restrictions (MCP_SCOPES) work correctly. It tests search only, search,billing, and full scopes, verifying that unauthorized attempts to call out-of-scope tools are securely rejected with access denied responses.

   node tests/test_mcp_scopes.mjs

🏃 Running & Installing the Server

The MCP server communicates via stdio transport by default (see below for the remote HTTP mode). You can easily register it, compile it locally, or automate the entire setup.

⚡ Option A: Automatic Installation (Highly Recommended)

You can automatically add and register ge-app-mcp in your favorite AI coding assistant (Claude Desktop, Cursor, Claude Code, etc.) using the open-source add-mcp utility:

npx add-mcp ge-app-mcp --env "GCP_PROJECT=your-gcp-project-id" --env "MCP_SCOPES=search,admin,billing"

(This automatically discovers your installed AI agents, configures their configuration files, and passes the required environment variables securely.)

Option B: Manual Execution via npx

To run the server directly from npm without cloning:

npx -y ge-app-mcp

Option C: Compile and Run Locally

# Clone, install dependencies, compile and start:
npm install
npm run build
npm start

# In development with hot-reloading:
npm run dev

🏢 Using the Server inside Gemini Enterprise (Cloud Run, on behalf of the user)

Gemini Enterprise can call these tools as actions through a Custom MCP Server data store. In this mode the server runs on Cloud Run over Streamable HTTP and every call is executed with the signed-in user's own Google OAuth token: users can only do what their IAM roles allow, and audit logs show the real user. Local harnesses (Antigravity, Claude Code, Codex, Cursor...) are unaffected and keep using stdio.

sequenceDiagram
    participant U as Admin
    participant GE as Gemini Enterprise
    participant CR as Cloud Run (ge-app-mcp)
    participant API as Discovery Engine API
    U->>GE: natural language request
    GE->>CR: tools/call + X-Serverless-Authorization (GE service agent) + Authorization (user token)
    CR->>CR: verify token (allowed OAuth client, scope, verified email)
    CR->>API: call with the user's token
    API-->>CR: 200, or 403 if the user lacks the role

1. Allow Custom MCP data stores (Organization Policy Administrator, project level):

cat > policy.yaml <<'YAML'
name: projects/PROJECT_NUMBER/policies/discoveryengine.managed.disableCustomMcpServerConnector
spec:
  rules:
  - enforce: false
YAML
gcloud org-policies set-policy policy.yaml --update-mask=spec

If the project is VPC-SC protected or listed in enforcedProjects, also add custom_mcp to allowedDataSources and the Cloud Run host plus accounts.google.com and oauth2.googleapis.com to allowedEgressFqdns.

2. Create an OAuth client (Google Auth Platform, type Web application, consent screen Internal) with the redirect URI https://vertexaisearch.cloud.google.com/oauth-redirect.

3. Deploy to Cloud Run (private service, runtime service account without roles):

gcloud iam service-accounts create ge-app-mcp-runtime --project=PROJECT_ID
gcloud run deploy ge-app-mcp --source . --project=PROJECT_ID --region=REGION \
  --no-allow-unauthenticated \
  --service-account=ge-app-mcp-runtime@PROJECT_ID.iam.gserviceaccount.com \
  --set-env-vars="^@^GCP_PROJECT=PROJECT_ID@MCP_SCOPES=search,admin,billing@ALLOWED_OAUTH_CLIENT_IDS=CLIENT_ID@ACCEPTED_OAUTH_SCOPES=https://www.googleapis.com/auth/discoveryengine.readwrite@ALLOWED_EMAIL_DOMAINS=example.com"
gcloud run services add-iam-policy-binding ge-app-mcp --region=REGION --project=PROJECT_ID \
  --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com \
  --role=roles/run.invoker

The image is built from the Dockerfile (distroless, non-root, MCP_TRANSPORT=http).

4. Create the data store in the Gemini Enterprise console: Data stores → Create → Custom MCP Server → OAuth 2.0:

Then open Actions → Reload custom actions, select all discovered actions, click Enable actions, and connect the data store to the app used by your administrators (Connected data stores → Add existing data stores). On first use in the Gemini Enterprise web app, each administrator opens Sources / Connectors in the chat bar and clicks Authorize next to the connector to complete per-user OAuth consent. Read-only tools (search, ask, get_document, get_operation, inspect, inspect_licenses) run in parallel without a confirmation prompt; mutating actions (manage_*, configure_connector) show a Review card (Send / Cancel) and run sequentially.

5. Grant roles to administrators: their usual Discovery Engine roles plus roles/serviceusage.serviceUsageConsumer on the project (the server sends x-goog-user-project).

The distributed skills can be imported into the Gemini Enterprise web app (Skills → Add skill → Upload skill, select SKILL.md → Import), invoked in chat with /<skill-name> (e.g. /admin-assistant), and shared with other administrators.

🧩 Managing Pre-Built Agent Skills

This project fully supports the open Agent Skills specification (compatible with Vercel's skills CLI and standard coding agents). You can manage them in two ways:

⚡ Option A: Automatic via Vercel's skills CLI (Recommended)

You can instantly install and load all our pre-built enterprise skills into your workspace using Vercel's skills CLI:

npx skills add miticojo/ge-app-mcp

Option B: Handled via the Local package CLI

If you prefer, you can use the built-in CLI utility bundled with our package to list and copy skills manually:

1. List Available Pre-Built Skills

npx ge-app-mcp skills list

2. Install a Pre-Built Skill

Copy a pre-built skill folder into your local project workspace (defaults to ./skills/ if target directory is omitted):

npx ge-app-mcp skills install <skill-id> [target-directory]

# Example:
npx ge-app-mcp skills install admin-assistant ./my-skills

🤖 AI Agents & IDE Integration (Cursor, Windsurf, Claude Desktop, etc.)

For detailed, copy-paste configurations to integrate this server into your preferred AI agent workflows, see our dedicated integration guide:

👉 AGENTS.md

It provides comprehensive configurations for:

• Cursor / Windsurf / Claude Desktop (Direct stdio setup using npx ge-app-mcp).

• Google Agent Development Kit (ADK) (Native orchestration with MCPToolset).

• LangChain & LangGraph (Python & TypeScript integrations).

• CrewAI.

📂 Project Structure

ge-app-mcp/
├── LICENSE                    # Apache 2.0 License
├── README.md                  # This file
├── AGENTS.md                  # Integration guide for AI Agents (ADK, LangChain, Cursor)
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts               # MCP Server entrypoint (tool routing, stdio/http)
│   ├── config.ts              # Environment configuration
│   ├── gcp.ts                 # Request-scoped credentials and REST helpers
│   ├── http.ts                # Streamable HTTP transport and token verification
│   ├── annotations.ts         # MCP tool annotations
│   ├── domain/                # Pure domain logic (features, models, assistant, licensing, citations)
│   └── tools/
│       ├── search.ts          # Search tool implementations (Data Plane)
│       ├── admin.ts           # Admin tool implementations (Control Plane)
│       └── billing.ts         # Billing & license management tools (Control Plane)
└── skills/                    # Agent Skills templates conforming to Vercel Agent Skills standard
    ├── admin-assistant/
    │   └── SKILL.md           # Skill for DevOps and infrastructure orchestration
    ├── enterprise-context/
    │   └── SKILL.md           # Skill for secure zero-trust enterprise search
    ├── codebase-rag/
    │   └── SKILL.md           # Skill for debugging and conversational code context
    └── agent-workflow-architect/
        └── SKILL.md           # Skill for designing and governing agents and platform skills

📄 License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for more information.