Sapphire User MCP Server

A Python Model Context Protocol (MCP) server that exposes user profile data from the Sapphire Wellness App to AI assistants — including health alerts, personalised recommendations, and partner service subscriptions.

Tools Exposed

Architecture

Agent Container
      │  HTTP SSE
      ▼
sapphire-user-mcp:10003
      │
      ├──httpx──▶  User Profile API:8091
      │
      └──httpx──▶  Partner Service API:8085

• Transport: HTTP SSE — required for multi-container deployments (stdio only works when the agent spawns the MCP server as a child process)

• Upstream APIs: All tools call REST APIs over HTTP — no direct database access

• Framework: FastMCP with Pydantic v2 response models

Project Structure

SAPPHIRE-USER-MCP/
├── sapphire_user/
│   ├── server.py           # FastMCP app + SSE entry point
│   ├── config.py           # Settings (API URLs, HOST, PORT via env)
│   ├── models/             # Pydantic response models
│   │   ├── alerts.py
│   │   ├── recommendations.py
│   │   ├── partner_service.py
│   │   └── subscriptions.py
│   └── tools/              # MCP tool definitions
│       ├── alerts.py
│       ├── recommendations.py
│       └── subscriptions.py
├── pyproject.toml
├── Dockerfile
└── .env.example

Prerequisites

• Python 3.11+

• A running Sapphire User Profile API (default: http://localhost:8091)

• A running Sapphire Partner Service API (default: http://localhost:8085)

Quick Start

Local Development

# 1. Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# 2. Install dependencies
pip install -e .

# 3. Configure environment
cp .env.example .env
# Edit .env — set USER_PROFILE_API_BASE_URL and PARTNER_SERVICE_API_BASE_URL

# 4. Run the server
python -m sapphire_user.server
# Server starts at http://0.0.0.0:8001

Containerised (Docker)

# Build the image
docker build -t sapphire-user-mcp .

# Run the container
docker run -p 10003:10003 --env-file .env sapphire-user-mcp

The MCP server will be available at http://localhost:10003/sse.

To connect your agent container, set:

MCP_SERVER_URL=http://sapphire-user-mcp:10003/sse

Configuration

All settings are read from environment variables (or a .env file):

Tool Reference

All tools accept a single user_email parameter.

get_user_alerts

Fetches health alerts for the user from the User Profile API. Each alert includes:

• severity — alert urgency level (e.g. critical, warning)

• category — metric category that triggered the alert

• alertMessage — human-readable description of the alert

• metricName / metricType — the specific metric that breached a threshold

get_user_recommendations

Returns personalised partner service recommendations ranked by relevance score. Each recommendation includes:

• relevanceScore — integer ranking of how well the service matches the user's health profile

• partnerService — service name, category, type, and description

• generatedAt — timestamp when the recommendation was computed

get_user_subscriptions

Fetches the user's active partner service subscriptions and enriches each with full service details from the Partner Service API. Each subscription includes:

• partnerServiceId — the enrolled service identifier

• isActive — whether the subscription is currently active

• associationContext — contract end date and other contextual metadata

• service_details — full service spec, pricing, availability, and contract information

Inspecting Tools

Use the MCP Inspector to explore tool schemas and make test calls:

npx @modelcontextprotocol/inspector http://localhost:8001/sse

Connecting to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "sapphire-user": {
      "url": "http://localhost:8001/sse"
    }
  }
}

Then ask Claude: "What health alerts does sarah.chen@sapphirewellness.com have?" and it will call get_user_alerts with the provided email.

Extending

Adding a new tool:

1. Create sapphire_user/models/<name>.py — Pydantic response model

2. Create sapphire_user/tools/<name>.py — @mcp.tool() definition calling the appropriate API

3. Register in server.py