knowledge-search-mcp

An MCP (Model Context Protocol) server that exposes a knowledge_search tool for semantic search over a knowledge base backed by Vertex AI Vector Search and Google Cloud Storage.

How it works

1. A natural-language query is embedded using a Gemini embedding model.
2. The embedding is sent to a Vertex AI Matching Engine index endpoint to find nearest neighbors.
3. The matched document contents are fetched from a GCS bucket and returned to the caller.

Prerequisites

• Python ≥ 3.12
• uv for dependency management
• A Google Cloud project with:
  • A Vertex AI Vector Search index and deployed endpoint
  • A GCS bucket containing the indexed document chunks
  • Application Default Credentials (or a service account) with appropriate permissions

Configuration

Create a .env file (see Settings in main.py for all options):

PROJECT_ID=my-gcp-project
LOCATION=us-central1
BUCKET=my-knowledge-bucket
INDEX_NAME=my-index
DEPLOYED_INDEX_ID=my-deployed-index
ENDPOINT_NAME=projects/…/locations/…/indexEndpoints/…
ENDPOINT_DOMAIN=123456789.us-central1-aiplatform.googleapis.com
# optional
EMBEDDING_MODEL=gemini-embedding-001
SEARCH_LIMIT=10

Usage

Install dependencies

uv sync

Run the MCP server (stdio)

uv run python main.py

Run the MCP server (SSE, e.g. for remote clients)

uv run python main.py --transport sse --port 8080

Run the interactive agent (ADK)

The bundled agent spawns the MCP server as a subprocess and provides a REPL:

uv run python agent.py

Or connect to an already-running SSE server:

uv run python agent.py --remote http://localhost:8080/sse

Docker

docker build -t knowledge-search-mcp .
docker run -p 8080:8080 --env-file .env knowledge-search-mcp

The container starts the server in SSE mode on the port specified by PORT (default 8080).

Project structure

main.py          MCP server, vector search client, and GCS storage helper
agent.py         Interactive ADK agent that consumes the MCP server
Dockerfile       Multi-stage build for Cloud Run / containerized deployment
pyproject.toml   Project metadata and dependencies