Name: FreshMCP
Author: eosho

LABSCO SUMMARY

The gateway is the design, not an afterthought.

Most database MCP servers hand the client a connection string and hope. Here the agents sit behind API Management, so a shared deployment gets per-subscription keys, per-subscription rate limits and central monitoring without either agent implementing any of it — which is what makes this a team deployment rather than a laptop one. The cost is the same shape as the benefit: an Azure subscription, azd, Docker and RBAC assignments before the first call.

What it is

A Python service exposing two Azure surfaces as MCP agents: one for Cosmos DB and one for AI Search. They run as separate servers over SSE, and the deployment shape puts Azure API Management in front of both — so authentication, rate limiting and routing are the gateway's job rather than each agent's.

What you get

Cosmos DB container management — create, list and delete — and item operations covering create, read, update, delete and query
AI Search index management: create an index, list indexes, delete an index
Two independent servers so you can wire up one without the other: Cosmos on http://localhost:8001/cosmos/sse and Search on http://localhost:8002/search/sse
Subscription-key authentication, configurable per-subscription rate limits, request routing and response caching handled at the APIM layer
A one-command Azure deployment through azd up, which packages the services, provisions the resources, builds and pushes images to the container registry and deploys them to Container Apps

Requirements

An Azure subscription with permissions to create the resources, plus the Azure CLI, the Azure Developer CLI and Docker. Python 3.11 or higher; install with uv sync in a uv venv. Authentication in production runs on system-assigned managed identities, which are attached to the Container Apps by default — you grant the Cosmos DB SQL role and the Search Service Contributor role to them. Service principal credentials (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) are the alternative path; APPLICATIONINSIGHTS_CONNECTION_STRING is optional. Both agents speak SSE, so your client needs that transport.

Setup effort

Build from source — git clone https://github.com/eosho/freshMCP.git

See installation options

USE CASES

01

Querying Cosmos DB from an assistant

Run item queries and reads against a container without exporting data or writing a script for each question.

02

Managing search indexes without the portal

Create, list and delete AI Search indexes from the conversation instead of clicking through Azure.

03

Sharing one deployment across a team

Put it behind API Management so each consumer gets a subscription key with its own rate limit, rather than sharing one connection.

04

Keeping connection strings out of the picture

Use the managed identity path with the Cosmos and Search roles granted, so nothing holds a long-lived database credential.

BEFORE YOU INSTALL

What to know first

Requires

A client that can reach a remote MCP server over HTTP
Python 3.11 or later
AZURE_TENANT_ID in your environment
AZURE_CLIENT_ID in your environment
AZURE_CLIENT_SECRET in your environment

INSTALLATION

Connect your client

This one is built from source rather than installed with a single command.

Server setup

TERMINAL

git clone https://github.com/eosho/freshMCP.git
cd freshMCP
uv venv
source .venv/bin/activate
uv sync
cp .env.example .env

Edit .env with your Azure credentials and service settings, then start each server in its own terminal (both from the activated environment) and leave them running:

TERMINAL

python -m src.cosmos.mcp.server
python -m src.search.mcp.server

The Cosmos server listens on http://localhost:8001/cosmos/sse and the Search server on http://localhost:8002/search/sse; add the client entries below.

MCP Clients

VS Code

VS CODE · JSON

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

Cursor

CURSOR · JSON

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

FreshMCP