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

1. Client Request: VSCode/Cursor or web application sends request to APIM

2. APIM Processing:

   • Authentication and authorization

   • Rate limiting and throttling

   • Request routing based on service type

3. MCP Agent Processing:

   • Tool execution based on request type

   • Service-specific operations

   • Response formatting

4. 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

1. Clone the repository:

2. Install uv (if not already installed):

pip install uv

3. Create and activate a virtual environment using uv:

uv venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

4. Install dependencies using uv:

uv sync

5. 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)

1. 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

2. 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

1. 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

1. 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):

Monitoring

To monitor your application:

azd monitor -e dev

Contributing

1. Fork the repository

2. Create a feature branch

3. Commit your changes

4. Push to the branch

5. Create a Pull Request

License

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