heor-agent-mcp

# HEORAgent MCP Server

[![npm version](https://img.shields.io/npm/v/heor-agent-mcp.svg)](https://www.npmjs.com/package/heor-agent-mcp)
[![license](https://img.shields.io/npm/l/heor-agent-mcp.svg)](./LICENSE)
[![node](https://img.shields.io/node/v/heor-agent-mcp.svg)](https://nodejs.org)
[![Try in ChatGPT](https://img.shields.io/badge/Try_in-ChatGPT-10A37F?logo=openai&logoColor=white)](https://chatgpt.com/g/g-69f651f588f48191b1d69d54409857ec-heoragent)
[![Web UI](https://img.shields.io/badge/Web_UI-Vercel-000000?logo=vercel&logoColor=white)](https://web-michael-ns-projects.vercel.app)
[![EU AI Pact](https://img.shields.io/badge/EU_AI_Pact-Signatory-003399?logo=europeanunion&logoColor=FFCC00)](https://web-michael-ns-projects.vercel.app/ai-transparency)
[![AI Transparency](https://img.shields.io/badge/AI-Transparency_Note-blue)](https://web-michael-ns-projects.vercel.app/ai-transparency)

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

> **Try it now →** [HEORAgent on ChatGPT](https://chatgpt.com/g/g-69f651f588f48191b1d69d54409857ec-heoragent) (ChatGPT Plus / Team)
> · [Web UI (Claude, BYOK)](https://web-michael-ns-projects.vercel.app)
> · `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:**

```bash
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:**

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

Expected output:

```json
{"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

```bash
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:

```json
{
  "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](https://chatgpt.com/g/g-69f651f588f48191b1d69d54409857ec-heoragent) — type `/heor` to use it; works on any conversation.
- **Web UI (Claude, BYOK):** [web-michael-ns-projects.vercel.app](https://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](./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:

| 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.

### 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](./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](#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](./CHANGELOG.md) for the full diff.

---

## Tools (28)

| 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)