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

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

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.