🌌 Gemini Enterprise MCP Server & Agent Skills

Welcome to the official repository of 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)

• Advanced Search (gemini_enterprise_search): Executes semantic queries on datastores, returning titles, snippets, URIs, and structured data formatted in clean Markdown for your agents.

• Conversational Search (gemini_enterprise_ask): Queries the Answer API (Conversational RAG) receiving grounding answers, confidence scores, and structured references.

• Document Retrieval (gemini_enterprise_get_document): Allows the agent to download the entire contents and structured metadata of an indexed document for in-depth analysis.

⚙️ Control Plane (Administration & Tuning)

• App & Engine Management (gemini_enterprise_manage_apps): Complete CRUD operations to create and configure search and chat applications with Long-Running Operations (LRO).

• DataStore Management (gemini_enterprise_manage_datastore): Instantiation and deletion of structured and unstructured Data Stores with custom industry verticals (e.g., GENERIC, MEDIA).

• Advanced Web Search (gemini_enterprise_manage_target_sites): Management of target sites (URLs and glob patterns) for automatic website crawling.

• Bulk Document Ingestion (gemini_enterprise_manage_documents): Asynchronous ingestion and purging of documents from Cloud Storage (gs://...) or BigQuery sources.

• Custom Schema Management (gemini_enterprise_manage_schema): Upload, modification, and retrieval of JSON schemas for indexing structured documents.

• Tuning & Controls (gemini_enterprise_manage_controls): Creation of boost/bury rules, synonyms, redirects, and filters on Serving Configs.

• SaaS Connectors (gemini_enterprise_configure_connector): High-fidelity simulated flow with synchronization state management for Jira, Salesforce, and Confluence.

• Agent Management (gemini_enterprise_manage_agents): End-to-end CRUD operations (create, list, delete, update) for native, server-side Gemini Enterprise Agents.

• License & Billing Management (gemini_enterprise_manage_licenses): Programmatic management of user seats on Gemini Enterprise / Gemini Code Assist license pools.

Related MCP server: Google Cloud Docs MCP Server

🛠️ Installation & Setup

1. Prerequisites

• Node.js: v18.x 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 four ready-to-use testing scripts 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 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 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 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 test_agents_write.mjs

5. 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 test_mcp_scopes.mjs

🏃 Running the Server

The MCP server communicates via stdio transport and can be run either directly from the npm registry (recommended for seamless integration) or compiled locally from source.

Option A: Run directly via npx (No Cloning Required)

You can configure your IDE or MCP client to run the server directly from npm using npx. This completely bypasses the need to manually clone and compile the repository:

npx -y ge-app-mcp

Option B: Compile and Run Locally

If you cloned the source code locally, build and execute using:

# Compile and start
npm run build
npm start

# In development with hot-reloading:
npm run dev

🧩 Managing Pre-Built Agent Skills (CLI)

The package includes a built-in CLI utility to help you discover and install pre-built Vertex AI platform/agent skills directly into your local workspaces:

1. List Available Pre-Built Skills

List all skills included in the package alongside their IDs and descriptions:

npx ge-app-mcp skills list

2. Install a Pre-Built Skill

Copy a pre-built skill template file into your local project workspace (defaults to ./skills/ if the 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)
│   ├── config.ts              # GCP environment variable configuration
│   └── 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 (instruction prompt markdown files)
    ├── admin-assistant.md     # Skill for DevOps and infrastructure orchestration
    ├── enterprise-context.md  # Skill for secure zero-trust enterprise search
    └── codebase-rag.md        # Skill for debugging and conversational code context

📄 License

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