FreshMCP

A Python-based service that provides a Message Control Protocol (MCP) interface for FreshMCP operations using Azure Cosmos DB and AI Search.

Overview

FreshMCP is a comprehensive service that provides standardized interfaces for interacting with Azure services:

Cosmos DB Operations

Container management (create, list, delete)
Item operations (create, read, update, delete, query)

AI Search Operations

Create index
List indexes
Delete index

Architecture & Flow

System Architecture

graph TB
    subgraph "Client Layer"
        A[VSCode/Cursor Client]
        B[Web Application]
    end

    subgraph "APIM Gateway"
        C[Azure API Management]
        D[Rate Limiting]
        E[Authentication]
        F[Request Routing]
    end

    subgraph "MCP Agent Layer"
        G[Cosmos DB MCP Agent]
        H[Search MCP Agent]
    end

    subgraph "Azure Services"
        J[Cosmos DB]
        K[AI Search]
    end

    A --> C
    B --> C
    C --> D
    C --> E
    C --> F
    F --> G
    F --> H
    G --> J
    H --> K

Request Flow

Client Request: VSCode/Cursor or web application sends request to APIM
APIM Processing:
- Authentication and authorization
- Rate limiting and throttling
- Request routing based on service type
MCP Agent Processing:
- Tool execution based on request type
- Service-specific operations
- Response formatting
Azure Service Interaction:
- Direct API calls to Azure services
- Data retrieval and manipulation
- Telemetry collection

APIM Configuration

The Azure API Management (APIM) serves as the central gateway for all MCP agent communications:

Authentication: Subscription key-based authentication
Rate Limiting: Configurable limits per subscription
Routing: Intelligent routing to appropriate MCP agents
Monitoring: Built-in analytics and monitoring
Caching: Response caching for improved performance

MCP Agent Communication

Each MCP agent communicates via Server-Sent Events (SSE) protocol:

Cosmos DB Agent: Handles all database operations
Search Agent: Manages AI Search index operations

Prerequisites

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

Local Development Setup

Clone the repository:
Install uv (if not already installed):

pip install uv

Create and activate a virtual environment using uv:

uv venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

Install dependencies using uv:

uv sync

Set up environment variables:

cp .env.example .env
# Edit .env with your Azure credentials and service settings

Server Endpoints

Start the Cosmos DB MCP server:

python -m src.cosmos.mcp.server

The server will start on http://localhost:8001/cosmos/sse

Start the AI Search MCP server:

python -m src.search.mcp.server

The server will start on http://localhost:8002/search/sse

Setting up the MCP to the client

Add the tools of any MCP server to VSCode or Cursor providing a JSON configuration file below:

VSCode:

{
  "servers": {
    "cosmos_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8001/cosmos/sse"
    },
    "search_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8002/search/sse"
    }
  }
}

Cursor:

{
  "mcpServers": {
    "cosmos_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8001/cosmos/sse"
    },
    "search_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8002/search/sse"
    }
  }
}

Deployment with Azure Developer CLI (azd)

Initialize azd (if not already done):

azd init -e dev -l eastus

# -e dev is optional, it will create a new dev environment

# -l eastus is optional, it will create the resources in the eastus region

Deploy the application:

azd up

This will:

Packages the project/services
Provision all the necessary Azure services
Build and push the Docker images to the Azure Container Registry
Deploy the images to the Azure Container Apps

Setting up RBAC for Azure Services

Cosmos DB RBAC

Grant the necessary RBAC role to the system-assigned managed identity:

az cosmosdb sql role assignment create \
    --account-name <your-cosmos-account> \
    --resource-group <your-resource-group> \
    --role-definition-id "00000000-0000-0000-0000-000000000002" \
    --principal-id <managed-identity-principal-id> \
    --scope "/"

Note: The system-assigned managed identity is assigned to your cosmosdb Container App by default.

AI Search RBAC

Grant the necessary RBAC role to the system-assigned managed identity:

az role assignment create \
    --assignee <managed-identity-principal-id> \
    --role "Search Service Contributor" \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service-name>

Note: The system-assigned managed identity is assigned to your search Container App by default.

Environment Variables

Required environment variables (use a table to list them):

Variable	Description	Required
`AZURE_TENANT_ID`	Azure tenant ID	Yes (If using Service Principal)
`AZURE_CLIENT_ID`	Client ID for authentication	Yes (If using Service Principal)
`AZURE_CLIENT_SECRET`	Client secret for authentication	Yes (If using Service Principal)
`APPLICATIONINSIGHTS_CONNECTION_STRING`	Application Insights connection string	No

Monitoring

To monitor your application:

azd monitor -e dev

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.