MSG — Modern Selfcare Guidance MCP Server

Evidence-based symptom triage, red flag detection, and self-care recommendations for AI assistants.

MSG is an MCP (Model Context Protocol) server that provides AI assistants with medical self-care guidance capabilities including symptom search, triage assessment, red flag detection, self-care recommendations, and medical guidelines. It constrains AI output to curated, sourced clinical data — preventing the AI from generating unsafe or unverifiable medical advice.

Documentation

| Document | Audience | Description | | --- | --- | --- | | Comparison Report | Researchers, clinicians | Side-by-side comparison of raw LLM vs LLM + MSG across 6 medical scenarios with real API output samples | | Clinical Brief | Physicians, nurses, medical researchers | How MSG works, clinical use cases, research implications, and the role of physician expertise | | Pre-Visit Guide | Patients, patient advocates | How AI-assisted guidance helps patients prepare for appointments and seek appropriate care |

Overview

This package is a lightweight MCP proxy that connects to the MSG backend API. It exposes all backend tools, resources, and prompts through the standard MCP stdio transport, making it compatible with any MCP-compatible AI assistant (Claude Desktop, Cursor, Windsurf, etc.).

Why MSG?

Patients increasingly turn to AI chatbots for medical advice before contacting a physician. Without clinical guardrails, AI can miss life-threatening red flags, recommend unsafe self-care, or present fabricated guidance. MSG addresses this by providing AI assistants with:

• Deterministic emergency-first pipeline — red flags are always checked before self-care is recommended
• Sourced clinical data — guidelines from AHA/ACC, CDC, IDSA with last-updated dates and evidence strength
• Safety notes and contraindications — every self-care recommendation includes explicit safety boundaries
• Crisis detection — suicidal/overdose keywords trigger immediate emergency resources before any medical lookup
• Demographic awareness — atypical presentations for women, elderly, and diabetic patients
• Triage confidence scoring — numeric confidence (0-1) so the AI can communicate uncertainty

MSG does not diagnose, prescribe, or replace physician expertise. It helps patients arrive at their appointment informed, prepared, and with appropriate expectations. See the Clinical Brief for details.

Features

• Symptom Search — Find symptoms from natural language descriptions
• Triage Assessment — Determine care urgency (emergency, urgent care, primary care, self-care)
• Red Flag Detection — Identify serious medical conditions requiring immediate attention
• Self-Care Recommendations — Safe home remedies and lifestyle guidance with contraindications
• Medical Guidelines — Evidence-based clinical guidelines with source attribution and strength ratings
• Triage Pipeline — Complete automatic evaluation in a single call with emergency interrupt
• Resources — Symptom database, guidelines, healthcare systems, seasonal disease data
• Prompts — Pre-built prompt templates for common medical guidance scenarios

Installation

npm install -g @vahix/msg

Or use directly with npx:

npx @vahix/msg

Configuration

Set the following environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | MSG_BACKEND_URL | Yes | — | Backend MCP endpoint URL (e.g., https://api.example.com/mcp) | | MSG_API_KEY | No | — | API key for backend authentication (required if backend enforces auth) | | MSG_TIMEOUT | No | 30000 | Request timeout in milliseconds | | MSG_LOG_LEVEL | No | info | Log level (debug, info, warn, error) |

Obtaining an API Key

The backend requires API key authentication. Keys are managed via the admin endpoint:

# Create a new API key (requires ADMIN_KEY)
curl -X POST https://your-backend-url/admin/keys \
  -H "Authorization: Bearer your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"label": "my-client"}'

# List all API keys
curl https://your-backend-url/admin/keys \
  -H "Authorization: Bearer your-admin-key"

# Revoke a key
curl -X DELETE https://your-backend-url/admin/keys \
  -H "Authorization: Bearer your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"label": "my-client"}'

The API key is returned only once at creation time. Store it securely.

Usage

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "msg": {
      "command": "npx",
      "args": ["-y", "@vahix/msg"],
      "env": {
        "MSG_BACKEND_URL": "https://your-backend-url/mcp",
        "MSG_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "msg": {
      "command": "npx",
      "args": ["-y", "@vahix/msg"],
      "env": {
        "MSG_BACKEND_URL": "https://your-backend-url/mcp",
        "MSG_API_KEY": "your-api-key"
      }
    }
  }
}

Direct CLI

MSG_BACKEND_URL=https://your-backend-url/mcp npx @vahix/msg

Tools

| Tool | Description | |---|---| | searchSymptom | Normalize and search for symptoms from natural language | | getTriage | Assess urgency level and provide care options | | getRedFlags | Detect emergency warning signs for a symptom | | getSelfCare | Provide safe self-care recommendations | | getGuideline | Retrieve evidence-based medical guidelines | | runTriagePipeline | Complete automatic triage pipeline in one call | | getObservabilityStats | Get tool usage analytics and performance metrics |

Resources

| URI | Description | |---|---| | symptom://database | Complete symptom database | | guideline://database | Evidence-based medical guidelines | | location://healthcare-systems | Healthcare systems by location (US states, Canada provinces) | | seasonal://disease-prevalence | Seasonal disease patterns and prevalence data |

Prompts

| Prompt | Description | |---|---| | symptom-analysis | Comprehensive symptom analysis with full evaluation | | triage-assessment | Focused triage assessment for a specific symptom | | self-care-guidance | Self-care recommendations for symptom management | | medical-guideline-lookup | Medical guidelines with seasonal optimization |

Architecture

┌─────────────────┐     stdio      ┌─────────────────┐     HTTP      ┌─────────────────┐
│  AI Assistant   │ ◄──────────► │   MSG (this)    │ ◄──────────► │   MSG Backend   │
│  (Claude, etc)  │   MCP protocol │   MCP Proxy     │   JSON-RPC    │   (private)     │
└─────────────────┘                └─────────────────┘               └─────────────────┘

This package is a thin proxy — all medical data, business logic, and tool implementations live in the private MSG backend. The proxy forwards MCP requests over HTTP to the backend and returns responses to the AI assistant.

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run type-check

# Run locally
MSG_BACKEND_URL=https://your-backend-url/mcp npm start

Disclaimer

MSG provides general medical guidance for informational purposes only. It is not a medical device, does not diagnose, does not prescribe, and is not a substitute for professional medical advice, diagnosis, or treatment. Always seek the advice of a qualified healthcare provider with any questions about a medical condition.

MSG helps patients prepare for clinical encounters by providing structured symptom information, red flag awareness, and safe self-care guidance. It does not replace the physician's clinical judgment, physical examination, or knowledge of the patient's history. The physician's experience and expertise remain essential to quality care — MSG is designed to complement, not replace, the doctor-patient relationship.

Acknowledgements

This project is developed under the Life Sciences AI Community of BC AI.

Developed by Vahid Ghafarpour

License

Apache License 2.0 — See LICENSE for details.