Aop Mcp

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

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/topotoxspacerelief20260220/AOPMCP/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

# 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

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:

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:

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:

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:

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 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
• Source: ToxMCP/aop-mcp
• License: Apache-2.0
• Homepage: https://github.com/ToxMCP/toxmcp

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