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:

3. MCP Agent Processing:

4. Azure Service Interaction:

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  \
    --resource-group  \
    --role-definition-id "00000000-0000-0000-0000-000000000002" \
    --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  \
    --role "Search Service Contributor" \
    --scope /subscriptions//resourceGroups//providers/Microsoft.Search/searchServices/

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