ppenumatsa1/mcp-remote-server-azure

MCP Remote server (customer)

This repository contains an optimized MCP (Model Context Protocol) server using FastMCP that wraps a FastAPI-based customer API. The MCP server exposes tools and resources over HTTP for integration and testing.

Tech stack

• Python 3.12
• FastAPI (HTTP API) — backend/app
• Uvicorn (ASGI server)
• MCP (mcp package) for the tool/resource/prompt surface with streaming support
• httpx, pydantic, sqlmodel and other dependencies listed in backend/requirements.txt

See docs/ for design notes, project structure and feature breakdown.

Quick start (development)

1. Create and activate a virtual environment in the repository root and install dependencies:

# Unix / macOS
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

# Windows (PowerShell)
py -3.12 -m venv .venv
# activate the venv in PowerShell
. .\.venv\Scripts\Activate.ps1
pip install -r backend\requirements.txt

2. Configure environment variables. Copy the example file and edit backend/.env if you need to customize the API host/port or other settings:

cp backend/.env.example backend/.env

3. Start the services you need for local development:

• Start the FastAPI backend (serves the customer API on port 8000 by default):

uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

• Start the optimized FastMCP HTTP server (serves MCP tools/resources on port 8002):

uvicorn backend.mcp_remote.mcp_customer_server_optimized:app --host 0.0.0.0 --port 8002 --reload

Using Docker Compose (development)

You can build and run both services together with live-reload using Docker Compose. The compose file mounts the local backend/ folder into the containers so code changes trigger Uvicorn reload.

Build and start (rebuild images):

docker-compose up --build

Stop and remove containers/networks created by compose:

docker-compose down

Notes:

• The Compose setup uses --reload for development. For production builds, remove reload and source mounts and use a process manager (Gunicorn + Uvicorn workers).
• If you see missing packages at runtime after mounting the host folder, rebuild images without the mounted volume or adjust the volume to avoid hiding build-time installed files.
• Cosmos RBAC authentication expects az login to have been run on the host first. The compose file mounts ${HOME}/.azure read-only into the FastAPI container so the bundled Azure CLI can reuse your token cache. Run az login --tenant <tenant-id> (and az account set --subscription <subscription-id> if needed) before docker compose up.

Cosmos DB RBAC configuration

• The FastAPI container uses Azure AD authentication via DefaultAzureCredential and no longer accepts Cosmos DB keys. The deployment script (deploy/deploy_split.sh) automatically assigns the Cosmos DB Built-in Data Contributor role to the Container App's system-managed identity.
• For local development, complete the following once per user:
  1. Sign in to the correct tenant with your development account, for example: az login --tenant <tenant-id>.
  2. Capture the Azure AD object ID for the user. Members can run az ad user show --id <user-upn> --query id -o tsv. For guest users, use the rewritten UPN (e.g., 'ppenumatsa_microsoft.com#EXT#@MngEnvMCAP328033.onmicrosoft.com') or copy the Object ID from the Entra ID portal.
  3. Grant the Cosmos DB role:

az cosmosdb sql role assignment create \
	--resource-group <rg-name> \
	--account-name <cosmos-account-name> \
	--scope / \
	--principal-id <developer-object-id> \
	--role-definition-id 00000000-0000-0000-0000-000000000002

After the assignment, DefaultAzureCredential will pick up your az login token for Cosmos access during local development.

Using MCP Inspector (Node.js)

You can use the MCP Inspector UI to test and inspect your running MCP server (such as the FastMCP HTTP server on port 8002).

1. Start MCP Inspector (no need to add to your project):

npx @modelcontextprotocol/inspector

2. Open the Inspector UI (usually at http://localhost:6274) in your browser.

3. Enter your MCP server URL (e.g., http://localhost:8002/mcp) in the Inspector to connect and test tools/resources.

Running the tests

These tests exercise the FastMCP HTTP server and the customer API. Ensure the FastAPI backend is running (port 8000) before running the tests.

• Run the FastMCP server tool tests:

pytest -q backend/tests/test_mcp_customer_server_optimized.py

• Run the customer and orders router method tests:

pytest -q backend/tests/test_customers_orders_router.py

• Run all test suites:

pytest -q backend/tests/

More documentation

Project design, user flows and technical notes live in docs/design/.