Hormonaly MCP Server

Model Context Protocol (MCP) server for the Hormonaly evidence platform. Exposes the Helix AI engine, protocol library, compound database, and admin tools to Claude Desktop and any MCP-compatible AI agent.

Installation

Option A — npx / local build (recommended)

# Clone the repo and build
git clone https://github.com/hormonaly/hormonaly-platform
cd hormonaly-platform/mcp/hormonaly-mcp-server
npm install
npm run build

Option B — Run from the repo directly

node /path/to/hormonaly-platform/mcp/hormonaly-mcp-server/dist/index.js

Configuration for Claude Desktop

Add the following to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "hormonaly": {
      "command": "node",
      "args": [
        "/absolute/path/to/hormonaly-platform/mcp/hormonaly-mcp-server/dist/index.js"
      ],
      "env": {
        "HORMONALY_API_URL": "https://hormonaly.ai",
        "HORMONALY_API_KEY": "hk_live_YOUR_PARTNER_API_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving.

Authentication

Helix API key (required for helix_* tools)

Get your API key from the Hormonaly Partner Portal. Keys start with hk_live_ and are 72 characters long.

Set via environment variable:

export HORMONALY_API_KEY=hk_live_...

Or pass per-call using the api_key parameter on any helix_* tool.

Session token (required for user_* tools)

Get your session cookie from your browser:

1. Log into hormonaly.ai
2. Open DevTools → Application → Cookies
3. Copy the value of connect.sid

export HORMONALY_SESSION_TOKEN=s%3A...

Or pass per-call using the session_token parameter.

Admin session token (required for admin_* tools)

Same as session token but for an admin account:

export HORMONALY_ADMIN_SESSION_TOKEN=s%3A...

Or pass per-call using the admin_session_token parameter.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | HORMONALY_API_URL | https://hormonaly.ai | Base URL of the platform | | HORMONALY_API_KEY | — | Helix B2B API key (hk_live_...) | | HORMONALY_SESSION_TOKEN | — | User session cookie value | | HORMONALY_ADMIN_SESSION_TOKEN | — | Admin session cookie value | | HTTP_PORT | — | Set to run HTTP/SSE transport instead of stdio |

HTTP/SSE Transport (for remote agents)

Start the server in HTTP mode:

HTTP_PORT=3100 node dist/index.js
# or
node dist/index.js --http

Endpoints:

• GET http://localhost:3100/sse — SSE stream (connect first)
• POST http://localhost:3100/messages — Send tool calls
• GET http://localhost:3100/health — Health check

Available Tools

Helix Tools (require Helix API key)

helix_query

Send a clinical question to the Helix AI engine. Returns an evidence-based answer with citations, confidence score, and GRADE rating.

{
  "question": "What is the optimal BPC-157 dose for gut repair?",
  "language": "en",
  "detail_level": "clinical",
  "include_citations": true,
  "include_three_lens": false,
  "api_key": "hk_live_..."
}

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | question | string | ✅ | — | Clinical question (max 10,000 chars) | | language | en | ar | — | en | Response language | | detail_level | clinical | summary | — | clinical | Response depth | | include_citations | boolean | — | true | Include PubMed citations | | include_three_lens | boolean | — | false | Include longevity/health/performance scoring | | api_key | string | — | env var | Override HORMONALY_API_KEY |

helix_compare

Compare 2–3 compounds head-to-head. Returns structured comparison with use-case recommendations. Requires Professional or Enterprise tier.

{
  "compounds": ["semaglutide", "tirzepatide"],
  "indication": "weight loss in type 2 diabetes",
  "language": "en"
}

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | compounds | string[] | ✅ | — | 2–3 compound names | | indication | string | — | "General comparison" | Clinical context | | language | en | ar | — | en | Response language | | api_key | string | — | env var | Override HORMONALY_API_KEY |

helix_protocol

Get all protocols for a compound from the Helix API.

{
  "compound": "BPC-157",
  "language": "en"
}

helix_dossier_start

Start an async dossier generation job for a compound. Returns job_id. Requires Professional or Enterprise tier.

{
  "compound": "semaglutide",
  "language": "en"
}

helix_dossier_status

Poll a dossier generation job by job_id.

{
  "job_id": "dossier_abc123"
}

Protocol Tools (no auth required)

protocol_search

Search the protocol library by compound, condition, or category.

{
  "query": "testosterone replacement",
  "category": "hormones",
  "limit": 10
}

protocol_get

Get the full details of a protocol by ID or slug.

{
  "id": "semaglutide-weight-loss"
}

protocol_list_categories

List all protocol categories with protocol counts.

{}

protocol_get_interactions

Check for known interactions between a set of compounds. Uses the public /api/interactions/for/:slug endpoint — no authentication required.

{
  "compounds": ["semaglutide", "metformin", "insulin"]
}

Evidence Tools (no auth required)

evidence_search

Search PubMed for research on a compound or condition.

{
  "compound": "BPC-157",
  "max_results": 15
}

evidence_get

Get full details for a specific evidence record by ID.

{
  "id": "ev_12345"
}

Compound Tools (no auth required)

compound_search

Search the compound database by name or category.

{
  "query": "GLP-1",
  "category": "peptides"
}

compound_get_interactions

Get all known interactions for a specific compound.

{
  "slug": "semaglutide"
}

User Tools (require session token)

user_get_profile

Get the current user's profile.

{
  "session_token": "s%3A..."
}

user_get_usage

Get AI usage statistics for the current user.

{}

user_get_saved_protocols

Get the list of protocols saved by the current user.

{}

Admin Tools (require admin session token)

admin_get_stats

Get platform-wide statistics (users, protocols, AI costs).

{
  "admin_session_token": "s%3A..."
}

admin_list_users

List platform users with optional search and pagination.

{
  "limit": 20,
  "offset": 0,
  "search": "[email protected]"
}

admin_get_ai_costs

Get AI cost breakdown by model and endpoint.

{
  "days": 30
}

Example Queries

Ask Helix about a peptide protocol

"Use helix_query to ask: What is the evidence for BPC-157 in tendon healing? Include citations."

Compare GLP-1 agonists

"Use helix_compare to compare semaglutide vs tirzepatide for weight loss in T2D."

Search protocols

"Use protocol_search to find all protocols for testosterone replacement therapy."

Check compound interactions

"Use protocol_get_interactions to check interactions between semaglutide, metformin, and insulin."

Get admin stats

"Use admin_get_stats to show me the platform usage overview."

Tier Requirements

| Tool | Minimum Tier | |------|-------------| | helix_query | Starter | | helix_protocol | Starter | | helix_compare | Professional | | helix_dossier_start | Professional | | helix_dossier_status | Professional | | helix_deep_analysis | Professional | | run_clinical_workflow | Professional | | monitor_protocol_updates | Starter | | All protocol/compound/evidence tools | No auth needed | | user_* tools | Registered user | | admin_* tools | Admin user |

Development

# Build
npm run build

# Clean build
npm run clean && npm run build

# Run in stdio mode (for local testing)
HORMONALY_API_KEY=hk_live_... node dist/index.js

# Run in HTTP mode
HTTP_PORT=3100 HORMONALY_API_KEY=hk_live_... node dist/index.js