Heor Agent MCP Server

HEORAgent MCP Server

AI-powered Health Economics and Outcomes Research (HEOR) agent as a Model Context Protocol server.

Try it now → HEORAgent on ChatGPT (ChatGPT Plus / Team) · Web UI (Claude, BYOK) · npx heor-agent-mcp for Claude Desktop / Claude Code

Automates literature review across 44 data sources, risk of bias assessment (RoB 2 / ROBINS-I / AMSTAR-2), EQ-5D value set impact estimation, state-of-the-art cost-effectiveness modelling, HTA dossier preparation for NICE / EMA / FDA / IQWiG / HAS / EU JCA, and a persistent project knowledge base — all callable as MCP tools from Claude.ai, Claude Code, and any MCP-compatible host.

Built for pharmaceutical, biotech, CRO, and medical affairs teams who need rigorous, auditable HEOR workflows without building infrastructure from scratch.

---

First 60 seconds

Verify your install works before wiring it into Claude / Cursor / Continue. Open two terminal tabs:

Tab 1 — start the server in HTTP mode:

MCP_HTTP_PORT=8080 npx heor-agent-mcp@latest

You should see:

HEORAgent MCP server running on HTTP port 8080

Tab 2 — confirm it responds:

curl -s http://localhost:8080/health

Expected output:

{"status":"ok","server":"heor-agent-mcp","version":"1.10.2"}

✅ If you see the JSON above, the npm package works on your machine. Any further issues are in your MCP client config (Claude Desktop / Cursor / Continue), not the server.

❌ If you see command not found, run node --version — you need Node ≥20. If you see a different error, file a quick issue at https://github.com/neptun2000/heor-agent-mcp/issues with the output.

Now stop Tab 1 (Ctrl+C) and pick your client below — you don't need the HTTP mode for the actual integration; Claude / Cursor / Continue all use stdio.

---

Quick Start (per client)

Pick your MCP host:

Claude Code

claude mcp add heor-agent -- npx heor-agent-mcp

Then restart Claude Code.

Claude Desktop / claude.ai Desktop

Edit your MCP config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add:

{
  "mcpServers": {
    "heor-agent": {
      "command": "npx",
      "args": ["heor-agent-mcp"]
    }
  }
}

Then restart Claude Desktop.

Cursor / Continue / Cline

Same config shape as Claude Desktop above; the file path differs by client:

• Cursor: Settings → MCP → Add new MCP server
• Continue: ~/.continue/config.json under the mcpServers key
• Cline: Settings → MCP Servers → Edit MCP Settings

Hosted (no install)

• ChatGPT (Plus / Team): HEORAgent on ChatGPT — type /heor to use it; works on any conversation.
• Web UI (Claude, BYOK): web-michael-ns-projects.vercel.app — bring your Anthropic API key; runs the full v1.6.3 toolset.

---

Your first prompt

Once your MCP host is configured, paste any of these to verify end-to-end:

Run a literature search for semaglutide cost-effectiveness in T2D
using PubMed, NICE TAs, and ICER reports. Set runs=2.

Run irb_review for an industry-funded interventional Phase 2 trial in
relapsed MM — multi-site US+EU, pseudonymized data, greater-than-minimal
risk. I need the review tier, GDPR/HIPAA DMP, SAE framework, and the
ready-to-paste cover letter.

Run jca_pico_scope for osimertinib in EGFR-mutant 2L NSCLC across
DE/FR/IT/ES/NL. Then prepare an EU JCA dossier draft using the picos.

The first prompt exercises literature_search + validate_links (free, no API keys needed). The second exercises irb_review (pure decision tree, instant). The third exercises jca_pico_scope → hta_dossier pipeline.

---

What's new

See CHANGELOG.md for full version history. Current: v1.13.0 (28 tools, 44 data sources).

v1.13.0 — AI Transparency Disclosure (ISPOR ELEVATE-GenAI aligned)

16 tools now accept an ai_disclosure_level parameter:

Default by tool tier: HTA/regulatory tools (hta_dossier, hta_workflow, jca_pico_scope, pv_classify, etc.) default to "submission"; analysis tools (risk_of_bias, cost_effectiveness_model, etc.) default to "standard". Pass ai_disclosure_level: "off" to suppress.

Environment-level default: set HEORAGENT_DISCLOSURE_LEVEL=off|standard|submission to override the built-in per-tool defaults globally.

Web UI persona defaults: payer and HTA-reviewer personas always use "submission"; analyst personas default to "standard" and switch to "off" for scratch / exploratory prompts.

v1.0.4 highlights (still in v1.6.3)

Pharmacovigilance + workflow orchestration:

• pv_classify tool — classifies a planned study into its EMA pharmacovigilance regulatory category (PASS imposed/voluntary, PAES, RMP Annex 4, DUS, active surveillance registry, pregnancy registry, spontaneous reporting, ICH E2E plan). Returns the matching GVP module (V/VI/VIII/VIII Addendum I), ENCePP protocol template ID, RMP implications, FDA analogue, and submission obligations. Pure decision-tree per EMA GVP rev 4 + EU Regulation 1235/2010 Article 107a. <200ms response.
• hta_dossier Pharmacovigilance Plan section — pass pv_classification from pv_classify to hta_dossier and the dossier output now includes a PV Plan section between RoB and CEA. Without it, a one-line "PV plan not provided" note flags the gap so reviewers see what's missing.
• maic_workflow orchestrator (v1.0.6) — runs the full MAIC discovery+screening pipeline (ITC feasibility + parallel literature_search + screening + RoB + network) in one MCP call. Built for ChatGPT-5.3 surfaces where chaining 5+ tool calls in parallel is unreliable; works equally well from Claude.
• examples tool (v1.0.5) — pre-filled JSON inputs for heavy-schema tools (CEA, BIA, survival, MAIC, Bucher) plus a maic_workflow_recipe multi-step prompt template for ChatGPT users.
• CMS IRA awareness — when pv_classify is called with US jurisdiction, output explicitly notes that CMS IRA Medicare price-negotiation calculations exclude PV cost data — track those obligations in the regulatory budget, not the HEOR cost-effectiveness model.
• GRADE I²-based inconsistency, GRADE upgrading (Guyatt 2011), Bucher consistency check, EQ-5D 5L baseline-utility-aware impact (v1.0.4) — see CHANGELOG.md.
• ChatGPT Custom GPT support (v1.0.4) — OpenAPI 3.1 adapter at /api/openapi lets you build a Custom GPT in 5 minutes. See ChatGPT Custom GPT below.
• Surface-tagged analytics (v1.0.4) — every tool_call PostHog event carries a surface property (claude_anthropic_web / chatgpt_adapter / claude_desktop / direct_mcp).

See CHANGELOG.md for the full diff.

---

Tools (28)

literature_search

Searches across 44 sources in parallel. Every call returns a source selection table showing which of the 44 sources were used and why — essential for HTA audit trails.

Example call:

{
  "query": "semaglutide cardiovascular outcomes type 2 diabetes",
  "sources": ["pubmed", "clinicaltrials", "nice_ta", "cadth_reviews", "icer_reports"],
  "max_results": 20,
  "output_format": "text"
}

cost_effectiveness_model

Multi-state Markov model (default) or Partitioned Survival Analysis (oncology), following ISPOR good practice and NICE reference case (3.5% discount rate, half-cycle correction). Includes:

• PSA — 1,000–10,000 Monte Carlo iterations, probability cost-effective at WTP thresholds
• OWSA — one-way sensitivity analysis with tornado summary
• CEAC — cost-effectiveness acceptability curve
• EVPI — expected value of perfect information
• WTP assessment — verdict against NHS (£25–35K/QALY, updated April 2026), US payer ($100–150K), societal thresholds

Example call:

{
  "intervention": "Semaglutide 1mg SC weekly",
  "comparator": "Sitagliptin 100mg daily",
  "indication": "Type 2 Diabetes Mellitus",
  "time_horizon": "lifetime",
  "perspective": "nhs",
  "model_type": "markov",
  "clinical_inputs": { "efficacy_delta": 0.5, "mortality_reduction": 0.15 },
  "cost_inputs": { "drug_cost_annual": 3200, "comparator_cost_annual": 480 },
  "utility_inputs": { "qaly_on_treatment": 0.82, "qaly_comparator": 0.76 },
  "run_psa": true,
  "output_format": "docx"
}

hta_dossier_prep

Drafts submission-ready sections for six HTA frameworks with gap analysis:

Accepts piped output from literature_search and cost_effectiveness_model.

risk_of_bias

Assesses risk of bias using the appropriate Cochrane instrument, auto-detected from study_type:

Returns a rob_results object you can pass directly to hta_dossier_prep — this replaces the heuristic RoB estimate in the GRADE table with structured domain judgments.

Example call:

{
  "studies": [{ "id": "pmid_1", "study_type": "RCT", "title": "...", "abstract": "..." }],
  "output_format": "json"
}

Pipeline:

literature_search → screen_abstracts → risk_of_bias → hta_dossier_prep

Knowledge base tools

Projects live at ~/.heor-agent/projects/{project-id}/ with:

• raw/literature/ — auto-populated literature search results
• raw/models/ — auto-populated model runs
• raw/dossiers/ — auto-populated dossier drafts
• reports/ — generated DOCX files
• wiki/ — manually curated, Obsidian-compatible markdown with [[wikilinks]]

Pass project: "project-id" to any tool and results are saved automatically.

---

Examples

Copy-paste prompts to try in Claude Code, Claude Desktop, or the web UI.

Single-tool examples

Literature search

Search the literature for tirzepatide cardiovascular outcomes in type 2 diabetes. Use PubMed, ClinicalTrials.gov, and NICE TAs.

Survival curve fitting

Fit survival curves to this OS data from KEYNOTE-189: time 0 survival 1.0, time 6 survival 0.88, time 12 survival 0.72, time 18 survival 0.60, time 24 survival 0.51, time 36 survival 0.38. Use months.

Budget impact

Estimate the 5-year NHS budget impact of semaglutide for obesity. 200,000 eligible patients, drug cost £1,200/year, comparator (orlistat) £250/year, uptake 15% year 1 to 40% year 5.

Cost-effectiveness model

Build a CE model for semaglutide vs sitagliptin in T2D, NHS perspective, lifetime horizon, with PSA.

Indirect comparison (Bucher)

I have two trials: SUSTAIN-1 showed semaglutide vs placebo HR 0.74 (0.58-0.95) for HbA1c, and AWARD-5 showed dulaglutide vs placebo HR 0.78 (0.65-0.93). Run a Bucher indirect comparison between semaglutide and dulaglutide.

MAIC (population-adjusted comparison)

Run a MAIC between SUSTAIN-7 (N=300, semaglutide vs placebo, HR 0.74, CI 0.58-0.95, age 56±10, BMI 33±5) and AWARD-11 (N=600, dulaglutide vs placebo, HR 0.78, CI 0.65-0.93, age 58±9, BMI 35±6). Adjust for age and BMI.

Multi-tool workflows

Abstract screening workflow

Search PubMed for pembrolizumab in NSCLC, then screen the results with population adults with NSCLC, intervention pembrolizumab, comparator chemotherapy, outcomes overall survival and PFS.

Evidence network + NMA feasibility

Search for GLP-1 receptor agonists in T2D using PubMed, build an evidence network from the results, and assess NMA feasibility.

CE model with scenarios

Build a CE model for dapagliflozin vs placebo in heart failure, NHS perspective, lifetime horizon, with PSA. Add scenarios: "20% price reduction" with drug cost 400, "10-year horizon" with time_horizon 10yr.

End-to-end HTA workflow

Full dossier preparation

Create a project for semaglutide in obesity targeting NICE and ICER. Search literature for evidence, screen the results for adults with obesity comparing semaglutide to placebo for weight loss outcomes, assess risk of bias on the screened studies, then draft a NICE STA dossier using the screened results and rob_results.

This single prompt exercises: project_create → literature_search → screen_abstracts → risk_of_bias → hta_dossier_prep (GRADE RoB from structured assessment).

---

Data Sources

44 sources across 10 categories. Every literature_search call includes a source selection table showing used/not-used status and reason for each.

• PubMed — 35M+ biomedical citations (NCBI E-utilities)
• ClinicalTrials.gov — NIH/NLM trial registry (CT.gov v2 API)
• bioRxiv / medRxiv — Life sciences and medical preprints
• ChEMBL — Drug bioactivity, mechanisms, ADMET (EMBL-EBI)
• Wiley Online Library — Pharmacoeconomics, Health Economics, Journal of Medical Economics, Value in Health (CrossRef, ~77% abstract coverage, no key required)

• WHO GHO — WHO Global Health Observatory
• World Bank — Demographics, macroeconomics, health expenditure
• OECD Health — OECD health statistics (expenditure, workforce, outcomes)
• IHME GBD — Global Burden of Disease (DALYs, prevalence across 204 countries)
• All of Us — NIH precision medicine cohort

• FDA Orange Book — Drug approvals and therapeutic equivalence
• FDA Purple Book — Licensed biologics and biosimilars

• NICE TAs (UK) · CADTH (Canada) · ICER (US) · PBAC (Australia)
• G-BA AMNOG (Germany) · IQWiG (Germany) · HAS (France)
• AIFA (Italy) · TLV (Sweden) · INESSS (Quebec, Canada)

• CMS NADAC (US drug acquisition costs)
• PSSRU (UK unit costs) · NHS National Cost Collection · BNF (UK drug pricing)
• PBS Schedule (Australia)

• DATASUS · CONITEC · ANVISA (Brazil)
• PAHO (Pan American regional) · IETS (Colombia) · FONASA (Chile)

• HITAP (Thailand)

• ISPOR — HEOR methodology and conference abstracts
• OHE (Office of Health Economics) — EQ-5D value set research and HEOR methodology
• EuroQol Group — EQ-5D instruments, value sets, and registry

---

Output Formats

All tools support output_format:

• text (default) — Markdown with formatted tables and headings
• json — Structured objects for downstream tools
• docx — Microsoft Word document, saved to disk, path returned in response

DOCX files are saved to ~/.heor-agent/projects/{project}/reports/ (when a project is set) or ~/.heor-agent/reports/ (global). The tool response contains the absolute path — ready to attach to submissions or share with stakeholders.

---

Audit Trail

Every tool call returns a full audit record:

• Source selection table — all 44 sources with used/not-used and reason
• Sources queried — queries sent, response counts, status, latency
• Inclusions / exclusions — counts with reasons
• Methodology — PRISMA-style for literature, ISPOR/NICE for economics
• Assumptions — every assumption logged with justification
• Warnings — data quality flags, missing API keys, failed sources

Suitable for inclusion in HTA submission appendices.

---

Configuration

# Optional — enterprise data sources
ELSEVIER_API_KEY=...        # Embase + ScienceDirect
COCHRANE_API_KEY=...        # Cochrane Library
CITELINE_API_KEY=...        # Citeline
PHARMAPENDIUM_API_KEY=...   # Pharmapendium
CORTELLIS_API_KEY=...       # Cortellis
SERPAPI_KEY=...             # Google Scholar

# Optional — knowledge base location
HEOR_KB_ROOT=~/.heor-agent  # Default

# Optional — localhost proxy for enterprise APIs behind corporate VPN
HEOR_PROXY_URL=http://localhost:8787

# Optional — hosted tier (future)
HEOR_API_KEY=...

---

Web UI

A companion chat interface is available at:

https://web-michael-ns-projects.vercel.app

• Chat with Claude Sonnet 4.6 + all 22 HEOR tools
• BYOK (Bring Your Own Key) — paste your Anthropic API key in the settings; it stays in your browser's localStorage and is never stored on our servers
• Markdown rendering with styled tables, tool call cards with live progress timers, and theme-aware mermaid network diagrams
• 12 example prompts covering literature search, CEA, BIA, NMA, ITC feasibility, RoB, EQ-5D 5L, EU JCA dossiers
• Per-request MCP sessions (no cross-user session bleed)

The web UI calls the hosted MCP server on Railway for tool execution. No setup required — just add your API key and start querying.

Self-hosting the web UI

cd web
npm install
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local  # optional server-side fallback
npm run dev -- -p 3456

Set MCP_SERVER_URL to point to your own MCP server instance (default: the public Railway deployment).

---

ChatGPT Custom GPT

🟢 Live: HEORAgent on ChatGPT →

Open in ChatGPT (Plus / Team / Enterprise account required), pick a conversation starter, and you're querying 44 HEOR data sources.

HEORAgent is also available as a ChatGPT Custom GPT — useful when you (or your team) prefer the ChatGPT interface or have a ChatGPT Plus/Team account but no Anthropic API access.

Behind the scenes, the web tier exposes an OpenAPI 3.1 adapter at /api/openapi, with one POST endpoint per tool at /api/v1/{tool_name}. ChatGPT speaks this contract natively.

What's different from the Anthropic surface

The caps exist because ChatGPT Actions hard-fail at the 45-second response timeout. PSA, multi-run literature search, and full max_results would routinely exceed it. The web UI and MCP clients are unaffected.

Build a Custom GPT (ChatGPT Plus / Team required)

1. Visit chatgpt.com/gpts/editor and click Create.
2. Configure tab — fill in name (e.g., "HEORAgent"), description, and conversation starters. Paste the system prompt from web/lib/claude.ts (or write your own — the tool descriptions are self-documenting).
3. Actions → Create new action → Import from URL → paste:

   https://web-michael-ns-projects.vercel.app/api/openapi
   

   ChatGPT auto-imports all 17 endpoints with their schemas.
4. Authentication — choose None for the open public endpoint, or API Key with the CHATGPT_ADAPTER_TOKEN value if you've configured one (recommended for prod).
5. Privacy policy URL — required by GPT Store. Use the web UI's privacy URL or your own.
6. Test in the playground (right pane), then Publish → "Anyone with the link" or "GPT Store".

Securing the adapter for production

By default the /api/v1/* endpoint is open. Two layers of protection are recommended for any public-facing GPT:

# 1. Token-gate the endpoint
cd web
vercel env add CHATGPT_ADAPTER_TOKEN production   # generate a long random token
# Configure the same token in your Custom GPT under Authentication → API Key

# 2. Built-in rate limit
# 60 req/min per IP is enforced automatically (lib/rateLimit.ts).
# For multi-region/high-traffic prod, swap in @upstash/ratelimit + Vercel KV.

Sample call (manual, no GPT needed)

curl -X POST https://web-michael-ns-projects.vercel.app/api/v1/utility_value_set \
  -H "Content-Type: application/json" \
  -d '{
        "action": "estimate_impact",
        "indication_type": "non_cancer_qol_only",
        "baseline_utility": 0.85,
        "base_icer": 30000
      }'

Returns the Biz 2026 baseline-utility-adjusted ICER projection (the new EQ-5D 5L impact estimator).

---

HTTP Transport

The server supports both stdio (default, for local MCP clients) and Streamable HTTP (for hosted deployment).

# Stdio mode (default — for Claude Code, Claude Desktop)
npx heor-agent-mcp

# HTTP mode — for hosted deployment, Smithery, web UI backend
npx heor-agent-mcp --http                    # port 8787
MCP_HTTP_PORT=3000 npx heor-agent-mcp        # custom port

HTTP endpoints:

• POST/GET/DELETE /mcp — MCP Streamable HTTP protocol
• GET /health — health check
• GET /.well-known/mcp/server-card.json — Smithery discovery

---

Development

git clone https://github.com/neptun2000/heor-agent-mcp
cd heor-agent-mcp
npm install
npm test          # 401 tests across 84 suites
npm run build     # Compile TypeScript to dist/
npm run dev       # Run with tsx (no build step)

Requires: Node.js ≥ 20.

---

Architecture

┌────────────────────────────────────────────┐
│  MCP Host (Claude.ai / Claude Code / etc.) │
└────────────────┬───────────────────────────┘
                 │ stdio
┌────────────────▼──────────────────────────┐
│  heor-agent-mcp server                    │
│  ┌──────────────────────────────────────┐ │
│  │ 17 MCP tools (Zod-validated)         │ │
│  ├──────────────────────────────────────┤ │
│  │ DirectProvider (default)             │ │
│  │   ├─ 44 source fetchers              │ │
│  │   ├─ Audit builder + PRISMA trail    │ │
│  │   ├─ Markov / PartSA economic models │ │
│  │   ├─ Markdown + DOCX formatters      │ │
│  │   └─ Knowledge base (YAML + MD)      │ │
│  └──────────────────────────────────────┘ │
└───────────────────────────────────────────┘
                 │
    ┌────────────┴─────────────┐
    ▼                          ▼
┌────────────┐         ┌──────────────────┐
│ ~/.heor-   │         │ External APIs    │
│ agent/     │         │ (PubMed, NICE,   │
│ projects/  │         │  ICER, CADTH, …) │
└────────────┘         └──────────────────┘

---

License

MIT — see LICENSE.

---

Trust & Transparency

HEORAgent is a research and analysis tool — not a clinical decision-support system. It is not classified as high-risk under the EU AI Act because it does not drive individual diagnosis, treatment, or monitoring; it falls under limited-risk transparency obligations only. Every output is intended for review by a qualified HEOR/HTA/PV professional before any action is taken.

• EU AI Pact signatory — committed to AI governance, high-risk system mapping, and AI literacy promotion (voluntary commitments per the European Commission, ahead of the AI Act's August 2026 deadline).
• PRISMA-style audit trail on every tool call (sources queried, succeeded, failed, assumptions applied).
• AI commentary explicitly labelled — domain claims (ICERs, trial results, regulatory decisions) come exclusively from tool outputs, never from training-data recall.
• Methodology cited inline — ISPOR, NICE DSU TSDs, NICE PMG36, Cochrane Handbook, GRADE, EMA GVP, Cope 2014, Phillippo 2016, Biz 2026.

Full statement: /ai-transparency — risk classification, human oversight model, methodological references, and reporting channel.

---

Disclaimer

All outputs are preliminary and for research orientation only. Results require validation by a qualified health economist before use in any HTA submission, payer negotiation, regulatory filing, or clinical decision. This tool does not replace professional HEOR expertise.

---

Distribution

---

Links

• npm: https://www.npmjs.com/package/heor-agent-mcp
• GitHub: https://github.com/neptun2000/heor-agent-mcp
• Smithery: https://smithery.ai/servers/neptun2000-70zu/heor-agent-mcp
• Web UI: https://web-michael-ns-projects.vercel.app
• Issues: https://github.com/neptun2000/heor-agent-mcp/issues