Hormonaly Public MCP Server

Hormonaly — Public API & Integration Reference

The AI-native infrastructure for peptide, hormone, and longevity medicine.

This repository is the public-facing integration reference for enterprise partners and API integrators. The MCP server source is published in this repository at Hormonaly-ai/hormonaly-public. For clinical access, visit hormonaly.ai.

---

Table of Contents

1. Platform Overview
2. Architecture Overview
3. Partner API Reference
4. MCP Server — Tool Schema
5. Authentication
6. Rate Limits & Quotas
7. Errors & Status Codes
8. Subscription Tiers
9. Scribe API
10. Security & Compliance
11. Getting Access
12. Three-Lens Scoring
13. Webhook Events
14. API Versioning & Stability
15. Hormonaly-1 LLM
16. About Hormonaly

Platform Overview

Hormonaly combines three pillars into one platform:

• Evidence Synthesis — Multi-agent RAG over PubMed + 594 curated protocols with GRADE-style grading (A–D). 6 biomedical databases queried per response: PubMed, ClinicalTrials.gov, Cochrane, Europe PMC, OpenAlex, Semantic Scholar.
• Clinical Decision Support — Real-time answers, SOAP/DAP/Narrative notes, interaction checks, dosing, and monitoring plans grounded in verified citations.
• Workflow Tools — The operating layer for clinics, compounding pharmacies, and research teams in the peptide/hormone/longevity space.

By the numbers:

Core products available via API:

Architecture Overview

Hormonaly is built on a 42-agent orchestration architecture organized into six categories: Evidence, Research, Clinical, Content, Copilot, and Extraction — plus six continuously-running background agents.

Query Pipeline

Every Helix API call flows through the same deterministic pipeline:

Client query
│
▼
NeMo Guardrails (PII redaction · off-topic filter · nvidia/llama-3.1-nemotron-nano-8b-v1)
│
▼
Agent Router (intent classification → tier selection)
│
├── TIER_1_BEST: Claude Sonnet 4.6 → GPT-4o fallback (complex/clinical queries)
├── TIER_2_BALANCED: Claude Sonnet 4.6 → GPT-4o → Claude Haiku 4.5 fallback (Scribe, CDS, Rx)
└── TIER_3_FAST: Claude Haiku 4.5 → GPT-4o Mini → Gemini 2.5 Flash → Claude Sonnet 4.6 fallback (free tier, Three-Lens scoring)
│
▼
Multi-Database RAG Retrieval (6 databases · 80K token cap)
│
▼
Cross-Encoder Reranker (threshold ≥ 0.35, fallback 0.15)
│
▼
NeMo Parse — Full-text PMC enrichment (top 5 citations)
│
▼
Supervisor/Worker agents (complex multi-compound queries)
│
▼
Quality Gate (13 checks · 70% composite threshold · async)
│
▼
Citation Grounding (PMID verification · 4s timeout per citation)
│
▼
NeMo Output Guardrail (dosing safety scan · inline flags)
│
▼
Streaming SSE response → client

Agent Categories

Model Routing

Model routing note: All tiers use a primary + fallback chain. TIER_1: Claude Sonnet 4.6 → GPT-4o. TIER_2: Claude Sonnet 4.6 → GPT-4o → Claude Haiku 4.5. TIER_3: Claude Haiku 4.5 → GPT-4o Mini → Gemini 2.5 Flash → Claude Sonnet 4.6. NVIDIA NIM (nvidia/llama-3.3-nemotron-super-49b-v1, self-hosted on 8×H100 SXM) is used for citation grounding and the Ask Hormonaly copilot agent. Hormonaly-1 is Hormonaly's proprietary fine-tuned model — deployed on the same H100 infrastructure and progressively integrated to reduce third-party API dependence. See Hormonaly-1 LLM.

Evidence Quality Pipeline

• Reranker — Cross-encoder scores every RAG chunk ≥ 0.35 (fallback 0.15 for niche compounds)
• Token cap — 80,000 tokens max RAG context passed to LLM
• Quality gate — 13 checks across citation validity, answer completeness, clinical coherence, safety flags — composite score ≥ 70% threshold (async, post-hoc)
• Citation grounding — Every PMID verified against PubMed with 4s timeout; unverified citations are dropped
• NeMo Parse — Full PMC article text fetched for top 5 citations, structured into intro/methods/results, passed as enriched context

Partner API Reference

Base URL: https://hormonaly.ai/api/v1

Auth: Authorization: Bearer YOUR_API_KEY on every request.

Machine-readable OpenAPI spec: GET /api/v1/helix/openapi.json

All endpoint paths below are relative to the base URL.

Helix Endpoints

POST /helix/query

Submit a clinical question and receive a full Helix response with evidence grade, citations, and clinical verdict.

Request:

{
  "query": "What is the evidence for BPC-157 in tendon repair?",
  "mode": "evidence",
  "stream": true
}

Response (streaming SSE):

data: {"type":"agent_step","step":"classifying intent"}
data: {"type":"agent_step","step":"searching evidence","sources":26}
data: {"type":"agent_step","step":"verifying citations"}
data: {"type":"content","text":"BPC-157 has demonstrated..."}
data: {"type":"metadata","evidence_grade":"C","confidence":62,"verdict":"CONSIDER","citations":5,"sources_consulted":26}
data: {"type":"done"}

Response metadata fields:

GET /helix/protocols/:compound

Look up evidence-quality-rated protocols for a specific compound.

Example: GET /helix/protocols/bpc-157

Response:

{
  "compound": "bpc-157",
  "evidence_grade": "C",
  "protocols": [
    {
      "indication": "Tendon repair",
      "dose_range": "200–500 mcg/day",
      "route": ["subcutaneous", "intramuscular"],
      "cycle_duration": "4–12 weeks",
      "monitoring": ["liver enzymes at baseline", "symptom review at 4 weeks"]
    }
  ],
  "interactions": [],
  "citations": 5
}

POST /helix/dossier

Generate a comprehensive evidence dossier for a compound (async job). Advanced or Enterprise tier required.

Request:

{ "compound": "semaglutide", "sections": ["mechanism", "efficacy", "safety", "dosing"] }

Response: { "job_id": "dossier_abc123", "status": "queued" }

Poll with GET /helix/dossier/:job_id until status: "complete".

POST /helix/compare

Compare 2–4 protocols head-to-head across evidence grade, safety, dosing, and clinical readiness. Advanced or Enterprise tier required.

Request:

{ "compounds": ["testosterone-cypionate", "testosterone-enanthate"] }

GET /helix/health

Service health check. No authentication required.

{ "status": "ok", "latency_p50_ms": 4200, "citation_coverage": "99%" }

MCP Server — Tool Schema

Package: @hormonaly/mcp-server

The Hormonaly MCP server exposes 24 tools that allow Claude Desktop, Cursor, or any MCP-compatible agent to query the full Helix clinical intelligence stack directly — with no HTTP client code required on your side.

Installation (Claude Desktop)

The MCP server source is available in our GitHub repository. Clone and build locally:

git clone https://github.com/Hormonaly-ai/hormonaly-public.git
cd hormonaly-public/mcp/hormonaly-mcp-server
npm install && npm run build

Then configure Claude Desktop as follows:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "hormonaly": {
      "command": "node",
      "args": ["/path/to/hormonaly-mcp-server/dist/index.js"],
      "env": {
        "HORMONALY_API_URL": "https://hormonaly.ai",
        "HORMONALY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop — tools appear immediately.

HTTP/SSE mode (for server-side agents):

HTTP_PORT=3100 node dist/index.js
# SSE: GET http://localhost:3100/sse?sessionId=YOUR_ID
# POST: POST http://localhost:3100/messages?sessionId=YOUR_ID
# Health: GET http://localhost:3100/health

See the mcp/README.md for full setup instructions.

Remote MCP — Claude.ai One-Click Connect

Live · Published May 2026 · Registry: registry.modelcontextprotocol.io

The Hormonaly MCP server is deployed as a remote HTTP/SSE server and listed on the official MCP Registry as io.github.Hormonaly-ai/hormonaly. Enterprise customers using Claude.ai get a one-click Connect experience — no local installation, no Docker, no claude_desktop_config.json edits required.

One-Click Connect Flow (Claude.ai Enterprise)

1. Claude.ai discovers Hormonaly via the MCP Registry — no manual URL entry needed
2. User clicks Connect — Claude prompts: "Enter your x-api-key"
3. User pastes their hk_live_... Partner API key (from Partner Portal → API Keys)
4. All 24 tools activate immediately in the conversation

Authentication & Access Tiers

Partner API keys start with hk_live_ and are issued from the Partner Portal. The key is passed as the x-api-key SSE header — Claude.ai will prompt for it on first connect.

Full Tool Schema

Helix Tools

Protocol Tools

Evidence Tools

Compound Tools

User Tools (session auth required)

Admin Tools (admin session required)

Agentic Workflow Tools

Three tools activate the full multi-agent pipeline:

run_clinical_workflow — Supervisor/worker pattern. Decomposes complex clinical questions into 3–4 parallel sub-tasks (evidence search, interaction check, protocol lookup, clinical synthesis), dispatches specialist agents, and returns a synthesized report with orchestration_steps[] showing each agent's task, result, timing, and confidence. Latency: 30–90 seconds for complex queries.

helix_deep_analysis — Extended deep analysis using the full RAG pipeline. Returns Three-Lens scoring across three independent clinical lenses (Longevity / Health & Disease / Performance), full PMID citation list, confidence breakdown by section, and overall evidence grade (A–D).

monitor_protocol_updates — Checks saved protocols against a 90-day staleness threshold. Returns a review_recommended flag and last evidence update date per protocol. Use weekly/monthly to stay current with the literature.

MCP Tool Input Schemas

All 24 tool schemas. The inputSchema block is what Claude Desktop and MCP clients use to validate parameters before sending.

helix_query

{
  "name": "helix_query",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question": { "type": "string", "description": "Clinical question", "maxLength": 10000 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "detail_level": { "type": "string", "enum": ["clinical","summary"], "default": "clinical" },
      "include_citations":{ "type": "boolean", "default": true },
      "include_three_lens":{ "type": "boolean", "default": false },
      "api_key": { "type": "string", "description": "Override env API key" }
    },
    "required": ["question"]
  }
}

helix_compare (Advanced/Enterprise)

{
  "name": "helix_compare",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compounds": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 4 },
      "indication": { "type": "string", "default": "General comparison" },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["compounds"]
  }
}

helix_protocol

{
  "name": "helix_protocol",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compound": { "type": "string", "maxLength": 200 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["compound"]
  }
}

helix_dossier_start (Advanced/Enterprise)

{
  "name": "helix_dossier_start",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compound": { "type": "string", "maxLength": 500 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["compound"]
  }
}

helix_dossier_status

{
  "name": "helix_dossier_status",
  "inputSchema": {
    "type": "object",
    "properties": {
      "job_id": { "type": "string" },
      "api_key": { "type": "string" }
    },
    "required": ["job_id"]
  }
}

helix_deep_analysis (Enterprise)

{
  "name": "helix_deep_analysis",
  "inputSchema": {
    "type": "object",
    "properties": {
      "topic": { "type": "string", "description": "Clinical topic for deep analysis", "maxLength": 10000 },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["topic"]
  }
}

run_clinical_workflow

{
  "name": "run_clinical_workflow",
  "inputSchema": {
    "type": "object",
    "properties": {
      "question": { "type": "string", "description": "Complex clinical question", "maxLength": 10000 },
      "patient_context": { "type": "string", "description": "Optional: age, sex, conditions, medications" },
      "language": { "type": "string", "enum": ["en","ar"], "default": "en" },
      "api_key": { "type": "string" }
    },
    "required": ["question"]
  }
}

monitor_protocol_updates (session auth)

{
  "name": "monitor_protocol_updates",
  "inputSchema": {
    "type": "object",
    "properties": {
      "session_token": { "type": "string" },
      "compound_filter": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific compounds" }
    }
  }
}

protocol_search

{
  "name": "protocol_search",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string", "description": "e.g. 'weight-loss', 'hormones'" },
      "limit": { "type": "number", "default": 10 }
    },
    "required": ["query"]
  }
}

protocol_get

{
  "name": "protocol_get",
  "inputSchema": {
    "type": "object",
    "properties": { "id": { "type": "string" } },
    "required": ["id"]
  }
}

protocol_list_categories

{
  "name": "protocol_list_categories",
  "inputSchema": { "type": "object", "properties": {} }
}

protocol_get_interactions

{
  "name": "protocol_get_interactions",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compounds": { "type": "array", "items": { "type": "string" }, "minItems": 2,
      "description": "Compound slugs to screen" }
    },
    "required": ["compounds"]
  }
}

evidence_search

{
  "name": "evidence_search",
  "inputSchema": {
    "type": "object",
    "properties": {
      "compound": { "type": "string" },
      "max_results": { "type": "number", "default": 10 }
    },
    "required": ["compound"]
  }
}

evidence_get

{
  "name": "evidence_get",
  "inputSchema": {
    "type": "object",
    "properties": { "id": { "type": "string" } },
    "required": ["id"]
  }
}

evidence_grade

{
  "name": "evidence_grade",
  "inputSchema": {
    "type": "object",
    "properties": {
      "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20,
      "description": "Evidence record IDs to GRADE-score" }
    },
    "required": ["ids"]
  }
}

compound_search

{
  "name": "compound_search",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "category": { "type": "string" }
    },
    "required": ["query"]
  }
}

compound_get_interactions

{
  "name": "compound_get_interactions",
  "inputSchema": {
    "type": "object",
    "properties": { "slug": { "type": "string", "description": "e.g. 'semaglutide'" } },
    "required": ["slug"]
  }
}

compound_get_dosing

{
  "name": "compound_get_dosing",
  "inputSchema": {
    "type": "object",
    "properties": { "slug": { "type": "string", "description": "e.g. 'testosterone-cypionate'" } },
    "required": ["slug"]
  }
}

user_get_profile

{
  "name": "user_get_profile",
  "inputSchema": {
    "type": "object",
    "properties": { "session_token": { "type": "string" } }
  }
}

user_get_usage

{
  "name": "user_get_usage",
  "inputSchema": {
    "type": "object",
    "properties": { "session_token": { "type": "string" } }
  }
}

user_get_saved_protocols

{
  "name": "user_get_saved_protocols",
  "inputSchema": {
    "type": "object",
    "properties": { "session_token": { "type": "string" } }
  }
}

admin_get_stats

{
  "name": "admin_get_stats",
  "inputSchema": {
    "type": "object",
    "properties": { "admin_session_token": { "type": "string" } }
  }
}

admin_list_users

{
  "name": "admin_list_users",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": { "type": "number", "default": 20 },
      "offset": { "type": "number", "default": 0 },
      "search": { "type": "string" },
      "admin_session_token": { "type": "string" }
    }
  }
}

admin_get_ai_costs

{
  "name": "admin_get_ai_costs",
  "inputSchema": {
    "type": "object",
    "properties": {
      "days": { "type": "number", "default": 30 },
      "admin_session_token": { "type": "string" }
    }
  }
}

Authentication

Hormonaly uses two independent auth systems — do not mix them:

1. Helix Data API — Bearer Token

All /api/v1/* endpoints require: Authorization: Bearer YOUR_API_KEY

API keys are SHA-256 hashed before storage. The plaintext key is shown exactly once at creation — store it immediately in your secrets manager. If lost, revoke and rotate; there is no recovery path. REST /api/v1/* endpoints expect the key in the Authorization: Bearer header; the remote MCP/SSE server expects it in the x-api-key: hk_live_... header.

Key management: Partner Portal → API Keys (/partner/api)

2. Partner Portal — Session Auth

The Partner Portal (/partner/*) uses session-based authentication. Log in at /partner/login with email + password. This session does not grant access to the data API.

Key Lifecycle

1. Create — Full key shown ONCE in modal; copy immediately.
2. Multiple active keys — Creating a new key does NOT revoke existing keys.
3. Revoke — Instant. Any request using that key returns 401 immediately.
4. Lost key — Revoke and create a new key. No plaintext recovery.

Rate Limits & Quotas

Over-limit response: HTTP 429 with Retry-After header. Burst behavior: sliding 60-second window, no burst allowance.

Response Latency

usage Object

Every POST /api/v1/helix/query response includes a top-level usage object reflecting real-time token consumption:

{
  "usage": {
    "tokensUsedThisMonth": 1234567,
    "monthlyTokenBudget": 5000000,
    "percentUsed": 24.7,
    "hardCapTokens": 10000000,
    "hardCapExceeded": false,
    "quotaThresholdsCrossed": [80]
  }
}

Errors & Status Codes

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate exceeded. Retry after 23s.",
    "request_id": "req_01HXYZ..."
  }
}

Subscription Tiers

Scribe API

Mounted at /api/v1/scribe. Available on all plans.

POST /scribe/generate

{
  "note_format": "soap",
  "patient_context": {
    "age": 45, "sex": "male",
    "diagnoses": ["hypogonadism"],
    "active_protocols": ["testosterone-cypionate"],
    "lab_values": { "total_testosterone": "250 ng/dL", "LH": "1.2 mIU/mL" }
  },
  "visit_notes": "Patient presents for quarterly follow-up."
}

Supported note_format: soap | dap | narrative (default: soap). Response includes note, interaction_alerts, monitoring_plan, confidence_score, evidence_grade. Latency: 15–45 seconds.

GET /scribe/health

No authentication required.

Security & Compliance

Security Controls

Compliance Posture

• HIPAA-aligned architecture — No PHI stored by default; patient data is session-scoped unless the Clients feature is explicitly enabled.
• BAA available — Enterprise customers receive a Business Associate Agreement.
• Encryption — TLS 1.3 in transit, AES-256 at rest, geographically redundant encrypted backups.
• Audit logging — All auth events, API key usage, AI calls, and admin actions written to a tamper-evident audit log.
• Data residency — GCC-region and EU residency available on request.
• Infrastructure — GCP (us-central1), Cloud Run (autoscaling), Cloud SQL PostgreSQL + pgvector.

GCP inherits: SOC 2 Type II, ISO 27001, HIPAA, PCI DSS, 150+ compliance certifications at the infrastructure layer.

AI Safety

• NVIDIA NeMo safety layer on every query: input PII redaction + off-topic/harm-framing filter (nvidia/llama-3.1-nemotron-nano-8b-v1, self-hosted on H100); output dosing safety scan with inline warnings.
• PEPTIDE_SAFETY_FOOTER and HELIX_REGULATORY_RULES active on all responses.
• No model training on user data — query data is not used to train or fine-tune any third-party model. Production interactions are quality-filtered and used exclusively in the Hormonaly-1 Data Flywheel (see Hormonaly-1 LLM).

Internal benchmarks (May 2026):

Uptime

• Target SLA — 99.9% monthly uptime for all production API endpoints.
• P1 incidents — Acknowledged within 15 minutes, resolved within 4 hours.
• Status — status.hormonaly.ai
• Maintenance — Announced ≥ 72 hours in advance.

Getting Access

1. Request Partner API Access

Contact the Hormonaly team to request a Partner API account:

• Email: info@hormonaly.ai
• Enterprise / BD: hormonaly.ai/about
• Plans: hormonaly.ai/pricing

You will receive your API key and a cURL quickstart example by email, plus a separate Partner Portal invitation to set up your dashboard at /partner/dashboard.

2. Request Hormonaly-1 LLM Licensing

For enterprise integrators interested in licensing Hormonaly-1 for white-label or embedded clinical AI deployments:

• LLM Licensing: partnerships@hormonaly.ai — subject: Hormonaly-1 Licensing Inquiry
• LLM page: hormonaly.ai/hormonaly-llm

See the Hormonaly-1 LLM section for full model details and licensing tiers.

3. First API Call

curl -X POST https://hormonaly.ai/api/v1/helix/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the evidence for semaglutide in metabolic optimization?", "stream": false}'

4. OpenAPI Spec

curl https://hormonaly.ai/api/v1/helix/openapi.json

5. Full Documentation

Three-Lens Scoring

Three-Lens is Hormonaly's proprietary multi-domain evidence scoring framework. It evaluates a compound independently through three clinical lenses, producing per-lens efficacy and safety scores, an evidence level (A–E), and a synthesized overall recommendation.

Lenses

Score Structure

Each lens returns a DomainScore object:

{
  "domain": "longevity",
  "domainLabel": "Longevity & Anti-Ageing",
  "efficacyScore": 7.4,
  "safetyScore": 8.1,
  "evidenceLevel": "C",
  "evidenceLevelLabel": "Low",
  "studyCount": 12,
  "bestStudyType": "Randomized Controlled Trial",
  "keyFindings": ["Demonstrated mTOR inhibition in human pilot (n=24)"],
  "limitations": ["Most trials are short-duration (<12 weeks)"],
  "relevantEndpoints": ["HbA1c", "fasting insulin", "body weight"]
}

Evidence Levels (5-tier)

Overall Recommendations

Requesting Three-Lens Scores

Three-Lens is returned in helix_query when include_three_lens: true, and always in helix_deep_analysis and run_clinical_workflow:

curl -X POST https://hormonaly.ai/api/v1/helix/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the evidence for rapamycin in longevity?", "include_three_lens": true}'

Webhook Events

Hormonaly delivers async job results (dossiers, batch operations) to partner-configured webhook URLs. Configure in the Partner Portal under Settings → Webhooks.

Event Types

Signature Verification

Every delivery is signed with HMAC-SHA256. The signature is in the X-Hormonaly-Signature header:

X-Hormonaly-Signature: sha256=<hex_digest>

const crypto = require('crypto');
function verifyWebhook(secret, rawBody, receivedSig) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(receivedSig));
}

Delivery policy: 3 attempts maximum, exponential back-off (1s → 8s → 64s), 10s timeout per attempt, HTTP 2xx = delivered.

API Versioning & Stability

Current version: /api/v1/

Changelog

Hormonaly-1 LLM

Live · June 2026 · NVIDIA Innovation Lab Grant · NIM Stack · H100 · Nemotron 49B · Arabic & English

Hormonaly-1 is Hormonaly's proprietary clinical large language model — engineered specifically for peptide, hormone, and metabolic medicine. It is fully trained, merged, and deployed on Hormonaly's own NVIDIA H100 infrastructure via the NVIDIA NIM inference stack, with zero dependency on third-party AI APIs at inference time.

Overview

Documentation truncated — see the full README on GitHub.