FreshMCP

FreshMCP provides a Python-based MCP interface for FreshMCP operations, enabling standardized interactions with Cosmos DB and AI Search through a single, observable channel. You can start local MCP servers that expose SSE endpoints for database and index operations and connect your MCP-enabled clients to manage data and search indexes efficiently.

How to use

You connect your MCP-enabled client to the local MCP servers to perform Cosmos DB and AI Search operations. Start the two local servers, then configure your client to listen to their Server-Sent Events endpoints. Use the Cosmos DB MCP endpoint to manage containers and items, and the AI Search MCP endpoint to manage search indexes. Your client will receive updates as operations complete and can display real-time telemetry.

How to install

Prerequisites you need before installing and running the MCP servers are listed here.

# Prerequisites
# - Python 3.11 or higher
# - Azure CLI
# - Azure Developer CLI (azd)
# - Docker
# - Azure subscription with appropriate permissions

# Optional: system utilities for your OS

Follow these concrete steps to set up and run the MCP servers locally. If you have not cloned the project yet, obtain the project files from your source control and place them on your machine.

# Step 1: Install Python package runner (if not already installed)
pip install uv

# Step 2: Create and activate a virtual environment
uv venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

# Step 3: Install project dependencies (if the project requires syncing config or deps via uv)
uv sync

# Step 4: Set up environment variables (example placeholders)
pc .env.example .env
# Edit .env to include Azure credentials and service settings

# Step 5: Start the MCP servers (two separate terminals recommended)
python -m src.cosmos.mcp.server

If you prefer to run the AI Search MCP server instead, use the following sequence in a separate terminal.

python -m src.search.mcp.server

Additional configuration and security

The system uses Azure services under the hood. You manage access with RBAC and assign the system-managed identities for Cosmos DB and AI Search containers. Ensure you grant the required roles to the managed identity used by each MCP service.

Environment variables you will configure include credentials and telemetry settings.

RBAC and environment details

Cosmos DB RBAC needs a role assignment for the system-assigned managed identity used by the MCP service. AI Search RBAC requires similar permissions for the search service. Typical roles involved include Cosmos DB SQL data plane roles and AI Search Contributor equivalents.

Environment variables table

Use the following environment variables when configuring the local MCP runtime and client access.

Monitoring and deployment

For local development, you can monitor the deployment status with your cloud tooling once you publish or test remotely. When you deploy to Azure, you can use command-line monitoring utilities to observe latency, throughput, and error rates.

Available tools

Cosmos DB operations

Create, list, read, update, delete containers; manage items within containers (create, read, update, delete, query)

AI Search operations

Create index, list indexes, delete index; manage AI Search resources