# Aop Mcp

> MCP server for Adverse Outcome Pathway (AOP) discovery, semantics, and draft authoring.

- **Type:** MCP server
- **Install:** `agentstack add mcp-toxmcp-aop-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ToxMCP](https://agentstack.voostack.com/s/toxmcp)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ToxMCP](https://github.com/ToxMCP)
- **Source:** https://github.com/ToxMCP/aop-mcp
- **Website:** https://github.com/ToxMCP/toxmcp

## Install

```sh
agentstack add mcp-toxmcp-aop-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AOP MCP Server

[](https://github.com/ToxMCP/aop-mcp/actions/workflows/ci.yml)
[](https://doi.org/10.64898/2026.02.06.703989)
[](./LICENSE)
[](https://github.com/ToxMCP/aop-mcp/releases)
[](https://www.python.org/)

> Part of **ToxMCP** Suite → https://github.com/ToxMCP/toxmcp

**Public MCP endpoint for Adverse Outcome Pathway (AOP) discovery, scientific review, and draft-to-publication workflows.**  
Expose AOP-Wiki, AOP-DB, CompTox, semantic tooling, quantitative review helpers, and draft review/export flows to any MCP-aware agent (Codex CLI, Gemini CLI, Claude Code, etc.).

## Architecture

```mermaid
flowchart LR
    subgraph Clients["Clients and Agents"]
        Codex["Codex CLI / Desktop"]
        Gemini["Gemini CLI"]
        Claude["Claude Code"]
        Scripts["Scripts / notebooks"]
    end

    subgraph API["FastAPI MCP Service"]
        Router["HTTP entrypoints\n/health and /mcp"]
        Registry["Tool registry\ninputSchema + outputSchema"]
        Tools["Tool handlers\nread, review, assay, draft"]
    end

    subgraph Semantics["Semantic and Contract Layer"]
        Normalizers["OECD-aligned normalizers\nontology terms, applicability,\nevidence blocks, provenance"]
        Contracts["JSON Schemas\n/docs/contracts/schemas"]
    end

    subgraph Adapters["External Adapters"]
        AOPWiki["AOP-Wiki RDF / SPARQL"]
        AOPDB["AOP-DB SPARQL"]
        CompTox["EPA CompTox\nDashboard + CTX APIs"]
    end

    subgraph Authoring["Draft and Authoring Path"]
        Drafts["Draft graph store\nKE / KER / stressor edits"]
        Validation["OECD draft validation\ncompleteness checks"]
    end

    subgraph Offline["Offline and QA Paths"]
        Fixtures["Fixture fallback\nAOP_MCP_ENABLE_FIXTURE_FALLBACK=1"]
        Tests["Pytest + MCP smoke\nschema regression checks"]
    end

    Clients --> Router
    Router --> Registry
    Registry --> Tools
    Tools --> Normalizers
    Normalizers --> Contracts
    Tools --> AOPWiki
    Tools --> AOPDB
    Tools --> CompTox
    Tools --> Drafts
    Drafts --> Validation
    Tools -. fixture mode .-> Fixtures
    Contracts --> Tests
    Fixtures --> Tests
```

The current implementation follows a layered model:

- `FastAPI + JSON-RPC` expose `/mcp` and `/health`, and keep transport concerns separate from domain logic.
- `Tool handlers` are the agent-facing API. They validate inputs, call adapters, and emit structured responses with JSON Schemas.
- `Semantic normalizers` reshape upstream RDF/API payloads into OECD-aligned objects such as `event_components`, `applicability`, `evidence_blocks`, and `provenance`.
- `Adapters` isolate AOP-Wiki, AOP-DB, and CompTox specifics so upstream changes do not leak into MCP contracts.
- `Draft tooling` remains separate from the read/review path, which keeps pathway evidence, assay discovery, and authoring concerns from collapsing into one surface.
- `Fixture fallback + smoke tests` let the server degrade cleanly in offline development and keep the public MCP contract regression-tested.

See `docs/architecture.md` for the fuller narrative and `docs/contracts/oecd-aligned-schema.md` for the OECD read-contract targets that now shape `get_aop`, `get_key_event`, `get_ker`, and `assess_aop_confidence`.
For task-oriented walkthroughs, see `docs/quickstarts/README.md`, especially `docs/quickstarts/oecd-draft-authoring.md` for the governed draft essentiality flow.

## What's new in v0.9.0

- **Research-grade trust layer** - added a documented trust and auditability model for draft replay, durable MCP tool-call audit logs, bounded audit evidence export, and explicit regulatory limits.
- **Registry handoff support** - added `review_registry_handoff_bundle` and `attach_registry_handoff_to_draft`, and now surface imported Registry support plus limitations inside normal draft review bundles and artifacts.
- **Durable MCP audit evidence** - added optional `AOP_MCP_AUDIT_LOG_PATH` JSONL persistence, hash-chain verification with `verify_tool_call_audit_log`, recent process-local audit inspection with `list_tool_call_audit_records`, and bounded durable evidence export with `export_tool_call_audit_log_evidence`.
- **Replay package reproducibility** - `export_draft_replay_package` now includes draft integrity, external support, saved artifact verification, audit persistence status, recent audit records, and a `runtime_manifest` with server/runtime/config posture, schema hashes, tool catalog hash, and best-effort git commit.
- **Trust docs and scenarios** - added `docs/trust-auditability.md`, `docs/evaluations/trust-scenarios.md`, and README/tool-catalog guidance for reproducing and reviewing the audit trail.

## What's new in v0.8.2

- **Hardened SPARQL query construction (AOP-01)** — replaced unsafe `template.format(**params)` interpolation with `TemplateCatalog.render_safe()`, which escapes string literals, validates URI schemes, and separates trusted structural fragments from user-facing parameters. Fixed a CAS-URI injection path in `map_chemical_to_aops`.
- **Added circuit-breaker resilience (AOP-02)** — per-endpoint circuit breaker with CLOSED/OPEN/HALF_OPEN states, exponential backoff + jitter between retries, and immediate surfacing of non-retryable 4xx errors.
- **Strengthened draft audit chain (AOP-03 / AOP-04)** — `VersionMetadata` now enforces `checksum` and `previous_checksum`, records `checksum_algorithm` (default `sha256-v1`), and supports `ElectronicSignature` records with `authored`/`reviewed`/`approved`/`rejected` semantics. `verify_audit_chain()` rejects unsupported algorithms, empty checksums, and broken chains.
- **Ontology drift protection scaffold (AOP-05)** — replaced hardcoded `_iri_to_curie()` logic with configurable `CurieResolver`, and added an `OntologyMigrator` framework with BFS pathfinding and term-mapping support.

## What's new in v0.8.1

- Expanded the scientific review surface beyond the original read path with specificity-aware assay ranking, HGNC-backed KE assay search, KER citation concordance, conservative taxonomic LCA inference, draft topology validation, directional concordance checks, and supplemental assay-cutoff ordering review.
- Added a coherent draft review workflow: `review_draft_bundle`, `review_draft_evidence_gaps`, `export_draft_review_artifact`, `save_draft_review_artifact`, `list_saved_draft_review_artifacts`, and `plan_linear_draft_review_document`.
- Added mechanistic discovery tooling for orphan stressor discovery across one AOP, multiple AOPs, and phenotype or mechanism queries, plus chemical trace overlays on draft graphs.
- Hardened live operations with a refreshed MCP smoke script, stronger CompTox caching and bounded concurrency, and real-server validation for KE assay search, orphan discovery, confidence review, and draft review/export flows.
- Added release-facing documentation for validated scientific examples in [docs/quickstarts/live-scientific-examples.md](/Volumes/Storage/topotox_space_relief_20260220/AOP_MCP/docs/quickstarts/live-scientific-examples.md).

## Previous highlights from v0.8.0

`v0.8.0` focused on draft-store hardening, broader schema/runtime contract coverage, improved assay-tool steering and diagnostics, and expanded regression coverage across the assay and draft integrity surfaces.

## Why this project exists

AOP research depends on stitching together heterogeneous sources (AOP-Wiki, AOP-DB, CompTox, AOPOntology, MediaWiki drafts) while enforcing ontology, provenance, and publication rules. Traditional pipelines are bespoke notebooks or scripts that agents cannot safely reuse.  

The AOP MCP server wraps those workflows in a **secure, programmable interface**:

- **Unified MCP surface** – discovery, semantics, scientific review, draft authoring, and handoff utilities share a single tool catalog exposed over JSON-RPC.
- **Semantic guardrails** – applicability/evidence helpers normalize identifiers and validate responses against JSON Schema.
- **Draft-to-publish path** – create drafts, edit key events and KERs, run topology/evidence review, export publication-style artifacts, and feed publish planners without leaving MCP.

> Already using the O-QT MCP server? This project mirrors that experience with domain adapters tuned for AOP evidence and authoring.

---

## Feature snapshot

| Capability | Description |
| --- | --- |
| 🧬 **AOP discovery adapters** | Schema-validated tooling for AOP-Wiki, AOP-DB, and CompTox federation with improved phenotype search ranking, synonym expansion, and curated AOP retrieval. |
| 🧪 **Assay and chemical discovery** | Reverse AOP-to-assay lookup, KE-centered CompTox assay search with HGNC-backed gene resolution, phrase-only assay fallback, specificity-aware ranking, multi-AOP aggregation, orphan stressor discovery, and query-driven assay or chemical triage. |
| 🧭 **Semantic services** | CURIE normalization, applicability helper, and evidence matrix builder; enforced via JSON Schema responses. |
| 🔬 **Scientific review** | OECD-oriented KE/KER review helpers, citation concordance, conservative taxonomic LCA inference, supplemental assay-cutoff ordering checks, and confidence review surfaces that combine narrative and assay-derived signals. |
| ✍️ **Draft review and authoring** | Create/update drafts, key events, relationships, and stressor links with provenance and diff support, plus topology validation, directional concordance review, evidence-gap analysis, quantitative KER review, and chemical trace overlays. |
| 📦 **Artifacts and handoff** | Export review bundles as JSON or Markdown, save indexed local review artifacts, build publication-style reports, review and attach Registry `aop_context` handoff bundles with preserved caveats/provenance, surface attached Registry support automatically inside normal draft review exports, produce Linear-ready document payloads, and export assay tables in `csv`/`tsv`. |
| 🔎 **Trust and auditability** | Export replay packages with runtime manifests, verify durable MCP audit-log hash chains, list recent process-local audit records, and export bounded durable audit evidence packages for review. |
| ⚙️ **Configurable transports** | FastAPI JSON-RPC service with configurable endpoints, retries, and observability hooks. |
| 🤖 **Agent friendly** | Verified with Codex CLI, Gemini CLI, and Claude Code; includes quick-start snippets, live scientific examples, and an end-to-end MCP smoke script. |

---

## Table of contents

1. [Architecture](#architecture)
2. [Quick start](#quick-start)
3. [Configuration](#configuration)
4. [Tool catalog](#tool-catalog)
5. [Running the server](#running-the-server)
6. [Integrating with coding agents](#integrating-with-coding-agents)
7. [Output artifacts](#output-artifacts)
8. [Security checklist](#security-checklist)
9. [Current limitations](#current-limitations)
10. [Development notes](#development-notes)
11. [Contributing](#contributing)
12. [Security policy](#security-policy)
13. [Code of conduct](#code-of-conduct)
14. [Citation](#citation)
15. [Roadmap](#roadmap)
16. [License](#license)

---

## Quickstart TL;DR

```bash
# 1) install
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

# 2) configure
cp .env.example .env

# 3) run
uvicorn src.server.api.server:app --reload --host 0.0.0.0 --port 8003

# 4) verify
curl -s http://localhost:8003/health | jq .
BASE_URL=http://localhost:8003 ./scripts/test_mcp_endpoints.sh
```

## Quick start

```bash
git clone https://github.com/ToxMCP/aop-mcp.git
cd aop-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
cp .env.example .env
uvicorn src.server.api.server:app --reload --host 0.0.0.0 --port 8003
```

> **Heads-up:** Federated SPARQL queries benefit from internet access. When offline, enable fixture fallbacks in `.env` (see [Configuration](#configuration)).

Once the server is running:

- HTTP MCP endpoint: `http://localhost:8003/mcp`
- Health check: `http://localhost:8003/health`
- Task walkthroughs: `docs/quickstarts/find-aop.md`, `docs/quickstarts/live-scientific-examples.md`, `docs/quickstarts/oecd-draft-authoring.md`, and `docs/quickstarts/publish.md`

## Docker quick start

Build and run the hosted runtime image from the repository root:

```bash
docker build -t aop-mcp:local .
docker run --rm -p 8003:8000 aop-mcp:local
curl -s http://localhost:8003/health | jq .
```

The container listens on port `8000`; the example maps it to the existing local
development port `8003`. The image intentionally includes `docs/contracts/schemas`,
`tests/golden`, and `vendor/schema-spine` because schema validation, fixture
fallback, and the scientific-invariants bridge depend on those review assets.

For production deployments, configure bearer auth and origin controls rather
than exposing the development defaults:

```bash
docker run --rm -p 8003:8000 \
  -e AOP_MCP_ENVIRONMENT=production \
  -e AOP_MCP_AUTH_MODE=bearer \
  -e AOP_MCP_AUTH_BEARER_TOKEN="$AOP_MCP_AUTH_BEARER_TOKEN" \
  -e AOP_MCP_ALLOWED_ORIGINS="https://example.org" \
  aop-mcp:local
```

## Verification (smoke test)

Once the server is running, use the scripted smoke run first:

```bash
BASE_URL=http://localhost:8003 ./scripts/test_mcp_endpoints.sh
```

That smoke script validates the modern draft-review workflow end to end, including:

- `tools/list`
- draft creation and editing
- `review_draft_bundle`
- `export_draft_review_artifact`
- `save_draft_review_artifact`
- `list_saved_draft_review_artifacts`
- `plan_linear_draft_review_document`

If you only want a lightweight manual probe, the basic health and tool-list checks still work:

```bash
curl -s http://localhost:8003/health | jq .
curl -s http://localhost:8003/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq .
```

---

## Configuration

Settings are loaded through [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/settings/) with `.env`/`.env.local` support. Start from `.env.example` and keep `.env` untracked. Key environment variables:

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `AOP_MCP_ENVIRONMENT` | Optional | `development` | Controls defaults like permissive CORS and logging detail. |
| `AOP_MCP_LOG_LEVEL` | Optional | `INFO` | Application log level. |
| `AOP_MCP_AOP_WIKI_SPARQL_ENDPOINTS` | Optional | `https://aopwiki.rdf.bigcat-bioinformatics.org/sparql` | Comma-separated list of AOP-Wiki SPARQL endpoints. |
| `AOP_MCP_AOP_DB_SPARQL_ENDPOINTS` | Optional | `https://aopwiki.rdf.bigcat-bioinformatics.org/sparql` | Comma-separated list of AOP-DB SPARQL endpoints (defaults to AOP-Wiki for fallback). |
| `AOP_MCP_COMPTOX_BASE_URL` | Optional | `https://comptox.epa.gov/dashboard/api/` | Base URL for CompTox enrichment calls. |
| `AOP_MCP_COMPTOX_BIOACTIVITY_URL` | Optional | `https://comptox.epa.gov/ctx-api/` | Base URL for CompTox Bioactivity API (required for assay mapping). |
| `AOP_MCP_COMPTOX_API_KEY` | Optional | – | API key for CompTox (required for assay mapping and higher quota). |
| `AOP_MCP_ENABLE_FIXTURE_FALLBACK` | Optional | `0` | Set to `1` to serve fixture data when remote SPARQL endpoints are unavailable. |
| `AOP_MCP_AUDIT_LOG_PATH` | Optional | – | When set, appends hash-chained MCP tool-call audit records as JSONL while preserving the in-memory audit buffer used by replay packages. |

See `docs/contracts/endpoint-matrix.md` and `src/server/config/settings.py` for the extended configuration surface (auth, retries, cache sizing, job service knobs).

---

## Tool catalog

| Category | Highlight tools | Notes |
| --- | --- | --- |
| AOP discovery | `search_aops`, `get_aop`, `list_key_events`, `list_kers` | Federated AOP-Wiki queries with pagination, schema validation, and improved ranking for phenotype searches. |
| OECD review helpers | `get_key_event`, `get_ker`, `get_related_aops`, `assess_aop_confidence`, `find_paths_between_events` | Exposes richer KE/KER metadata, shared-AOP discovery, partial OECD-aligned heurist

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ToxMCP](https://github.com/ToxMCP)
- **Source:** [ToxMCP/aop-mcp](https://github.com/ToxMCP/aop-mcp)
- **License:** Apache-2.0
- **Homepage:** https://github.com/ToxMCP/toxmcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-toxmcp-aop-mcp
- Seller: https://agentstack.voostack.com/s/toxmcp
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.