Wellness Pulse MCP

Plug your AI into real wellbeing intelligence.

One connection gives your AI credible public benchmarks (CDC PLACES) plus institution-specific wellness signals — trends, snapshots, and alert checks — from your WellPulse data, returned in plain JSON.

Why teams add this


Instant narrative	Your AI can explain "what changed" without a human analyst
Benchmarks that sell	CDC county mental distress context for marketing and reports
Institution signals	Daily trends + alert checks to catch issues early
One integration	Add the MCP once; reuse across copilots, agents, dashboards

How it works

AI app / agent
   │  (MCP tools)
   ▼
WellPulse MCP (this server)
   ├─ Public benchmarks (CDC PLACES)
   └─ Institution data (your DB)
   ▼
Plain-English insights + structured JSON

Designed for fast "ask → answer" loops in copilots and automations.

What you can ask

"What's our wellness trend for the last 90 days?"
"Did we drop week-over-week? Why might that matter?"
"What's the CDC mental distress benchmark for this ZIP?"
"Write a short exec update with numbers and context."

Available Tools

Tool	Description
`get_mental_health_benchmark`	CDC PLACES frequent mental distress (FMD) for a `zip` or `county_fips`; returns scope, values, optional `national_percentile_rank`, and `marketing_copy`
`get_sector_snapshot`	Sector-level snapshot over a window; returns `institutions_with_responses`, `total_responses`, `avg_wellness_score`
`get_basic_alert_guidance`	Default alert thresholds by `org_size` and `location_type`
`get_institution_snapshot`	Counts, `avg_wellness_score`, `last_response_at` for an institution over a window
`get_institution_trend_daily`	Daily series of `{ day, avg_wellness, responses }`
`get_institution_alert_check`	Compares last 7d vs prior 7d; returns `drop_pct` and `alert` flag

Endpoints

Transport	URL
HTTP Stream	`https://wellpulse.org/mcp`
SSE	`https://wellpulse.org/sse`

Use JSON-RPC. For HTTP streaming, include: Accept: application/json, text/event-stream

Quickstart (cURL)

1 — Initialize session

curl -s https://wellpulse.org/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "example", "version": "1.0.0" }
    }
  }'

Capture the mcp-session-id response header for subsequent calls.

2 — List tools

curl -s https://wellpulse.org/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <SESSION_ID>" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }'

3 — Call a tool

curl -s https://wellpulse.org/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <SESSION_ID>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_mental_health_benchmark",
      "arguments": { "zip": "94597" }
    }
  }'

Running locally

Prerequisites

Node.js 18+
PostgreSQL database with the WellPulse schema (pulse schema, search_path set accordingly)

Setup

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your real DB credentials and preferred port

# 3. Start the server
npm start

The server starts at http://localhost:8383 by default (configurable via MCP_PORT in .env).

Environment variables

Variable	Description	Default
`DB_HOST`	PostgreSQL host	`localhost`
`DB_PORT`	PostgreSQL port	`5432`
`DB_NAME`	Database name	(required)
`DB_USER`	Database user	(required)
`DB_PASSWORD`	Database password	(required)
`MCP_PORT`	Port the MCP server listens on	`8383`

Project structure

wellpulse-mcp/
├── .env.example              ← environment variable template
├── .gitignore
├── package.json
└── src/
    ├── index.js              ← entry point
    ├── db.js                 ← shared PostgreSQL pool
    └── tools/
        ├── mentalHealthBenchmark.js
        ├── sectorSnapshot.js
        ├── basicAlertGuidance.js
        ├── institutionSnapshot.js
        ├── institutionTrendDaily.js
        └── institutionAlertCheck.js

Notes

ZIP codes are resolved to county FIPS automatically via public APIs (zippopotam.us + FCC).
If county-level CDC data is unavailable, responses include a national fallback with scope: "national_fallback".
Institution tools require a valid institution_id present in your database.

Wellness Pulse