heor-agent-mcp
Advanced tools
AI-powered Health Economics and Outcomes Research (HEOR) MCP server — 49 tools across literature search (44 data sources incl. PubMed/ClinicalTrials.gov/Cochrane/NICE/CADTH/ICER), risk of bias (RoB 2/ROBINS-I/AMSTAR-2), cost-effectiveness modeling (Markov
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-mcpfor 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.
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.
Pick your MCP host:
claude mcp add heor-agent -- npx heor-agent-mcp
Then restart Claude Code.
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.
Same config shape as Claude Desktop above; the file path differs by client:
Settings → MCP → Add new MCP server~/.continue/config.json under the mcpServers keySettings → MCP Servers → Edit MCP Settings/heor to use it; works on any conversation.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.
See CHANGELOG.md for full version history. Current: v1.23.0 (45 tools, 44 data sources).
A connected RWE + cross-deliverable layer (see docs/FEATURES.md for the full table):
rwe.method_select (study-design selection), pv.comparative_safety (class-level FAERS-style AE ranking), evidence.triangulation (per-outcome RCT↔RWE concordance).rwe.social_listening_protocol + pv.social_listening_triage (GVP Module VI ICSR triage — no scraping).evidence.claim_registry (author/auto-import a figure once), evidence.consistency_check (detect drift across dossier/publication/payer), publication.draft (reuse claims; CONSORT/STROBE/PRISMA/CHEERS + GPP2022/ICMJE).evidence.gap_analysis (iEGP), workflow.living_evidence (SLR → living KB → JCA/HTA runbook), hta.living_gvd (regenerate only the GVD sections whose figures changed).16 tools now accept an ai_disclosure_level parameter:
| Value | Behaviour |
|---|---|
"off" | No disclosure block appended |
"standard" | Model ID · tools called · data sources · date · human-review reminder |
"submission" | Standard block + ISPOR ELEVATE-GenAI full citation |
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.
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.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./api/openapi lets you build a Custom GPT in 5 minutes. See ChatGPT Custom GPT below.tool_call PostHog event carries a surface property (claude_anthropic_web / chatgpt_adapter / claude_desktop / direct_mcp).See CHANGELOG.md for the full diff.
| Tool | Purpose |
|---|---|
literature_search | Search 44 data sources with a full PRISMA-style audit trail |
screen_abstracts | PICO-based relevance scoring and study design classification |
risk_of_bias | Cochrane RoB 2 / ROBINS-I / AMSTAR-2 with GRADE RoB domain summary |
evidence_network | Build treatment comparison network and assess NMA feasibility |
evidence_indirect | Bucher and frequentist NMA with automatic consistency check vs direct h2h evidence (NICE DSU TSD 18) |
population_adjusted_comparison | MAIC and STC for population-adjusted indirect comparisons |
survival_fitting | Fit 5 parametric distributions to KM data (NICE DSU TSD 14) |
itc_feasibility | Assess the 3-assumption ITC framework and recommend Bucher / NMA / MAIC / STC / ML-NMR |
cost_effectiveness_model | Markov / PartSA / decision-tree CEA with PSA, OWSA, CEAC, EVPI, EVPPI; QALY + evLYG support |
budget_impact_model | ISPOR-compliant BIA with year-by-year output and treatment-displacement modelling |
hta_dossier | Draft submissions for NICE, EMA, FDA, IQWiG, HAS, and EU JCA — GRADE table uses structured RoB when rob_results passed; inconsistency uses I² when heterogeneity_per_outcome passed; GRADE upgrading (Guyatt 2011) supported via upgrading_per_outcome |
utility_value_set | EQ-5D-3L / 5L value-set reference + baseline-utility-aware Biz 2026 ICER impact estimator (UK 5L transition) |
validate_links | HTTP validation of citation URLs before presentation |
project_create | Initialize a persistent project workspace |
knowledge_search | Full-text search across a project's raw/ and wiki/ trees |
knowledge_read | Read any file from a project's knowledge base |
knowledge_write | Write compiled evidence to the project wiki (Obsidian-compatible) |
literature_searchSearches 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_modelMulti-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:
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_prepDrafts submission-ready sections for six HTA frameworks with gap analysis:
| Body | Country | Submission types |
|---|---|---|
| NICE | UK | STA, MTA, early_access |
| EMA | EU | STA, MTA |
| FDA | US | STA, MTA |
| IQWiG | Germany | STA, MTA |
| HAS | France | STA, MTA |
| JCA | EU (Reg. 2021/2282) | initial, renewal, variation (with PICOs) |
Accepts piped output from literature_search and cost_effectiveness_model.
risk_of_biasAssesses risk of bias using the appropriate Cochrane instrument, auto-detected from study_type:
| Study type | Instrument |
|---|---|
| RCT | RoB 2 (5 domains: randomization, deviations, missing data, measurement, reporting) |
| Observational | ROBINS-I (7 domains: confounding, selection, classification, deviations, missing data, measurement, reporting) |
| Systematic review | AMSTAR-2 (16 items, critical vs non-critical) |
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
Projects live at ~/.heor-agent/projects/{project-id}/ with:
raw/literature/ — auto-populated literature search resultsraw/models/ — auto-populated model runsraw/dossiers/ — auto-populated dossier draftsreports/ — generated DOCX fileswiki/ — manually curated, Obsidian-compatible markdown with [[wikilinks]]Pass project: "project-id" to any tool and results are saved automatically.
Copy-paste prompts to try in Claude Code, Claude Desktop, or the web UI.
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.
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.
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).
44 sources across 10 categories. Every literature_search call includes a source selection table showing used/not-used status and reason for each.
| Source | Env variable |
|---|---|
| Embase | ELSEVIER_API_KEY |
| ScienceDirect | ELSEVIER_API_KEY |
| Cochrane Library | COCHRANE_API_KEY |
| Citeline | CITELINE_API_KEY |
| Pharmapendium | PHARMAPENDIUM_API_KEY |
| Cortellis | CORTELLIS_API_KEY |
| Google Scholar | SERPAPI_KEY |
All tools support output_format:
text (default) — Markdown with formatted tables and headingsjson — Structured objects for downstream toolsdocx — Microsoft Word document, saved to disk, path returned in responseDOCX 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.
Every tool call returns a full audit record:
Suitable for inclusion in HTA submission appendices.
# 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=...
A companion chat interface is available at:
https://web-michael-ns-projects.vercel.app
The web UI calls the hosted MCP server on Railway for tool execution. No setup required — just add your API key and start querying.
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).
🟢 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.
| Web UI / MCP / Claude Desktop | ChatGPT Custom GPT | |
|---|---|---|
| Streaming | yes (SSE) | no (45s single response) |
psa_iterations | up to 10,000 | capped to 1,000 (CEA) / 500 (BIA) |
literature_search.runs | 1–5 | capped to 1 |
literature_search.max_results | up to 100 | capped to 30 |
| Auth model | BYOK Anthropic | optional X-API-Key header (server-side CHATGPT_ADAPTER_TOKEN) |
| Surface label in PostHog | claude_anthropic_web / claude_desktop | chatgpt_adapter |
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.
web/lib/claude.ts (or write your own — the tool descriptions are self-documenting).https://web-michael-ns-projects.vercel.app/api/openapi
CHATGPT_ADAPTER_TOKEN value if you've configured one (recommended for prod).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.
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).
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 protocolGET /health — health checkGET /.well-known/mcp/server-card.json — Smithery discoverygit 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.
┌────────────────────────────────────────────┐
│ 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, …) │
└────────────┘ └──────────────────┘
MIT — see LICENSE.
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.
Full statement: /ai-transparency — risk classification, human oversight model, methodological references, and reporting channel.
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.
| Channel | How to use | Who pays |
|---|---|---|
| npm | npx heor-agent-mcp | User's Claude subscription |
| Smithery | smithery.ai/servers/neptun2000-70zu/heor-agent-mcp | User's Claude subscription |
| Web UI | web-michael-ns-projects.vercel.app | User's own Anthropic API key (BYOK) |
| Hosted MCP | https://heor-agent-mcp-production.up.railway.app | Free (tool execution only) |
FAQs
AI-powered Health Economics and Outcomes Research (HEOR) MCP server — 49 tools across literature search (44 data sources incl. PubMed/ClinicalTrials.gov/Cochrane/NICE/CADTH/ICER), risk of bias (RoB 2/ROBINS-I/AMSTAR-2), cost-effectiveness modeling (Markov
We found that heor-agent-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.