EPA CompTox MCP Server

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

Public MCP endpoint for EPA Computational Toxicology (CompTox) evidence federation. Expose chemical identity, hazard, exposure, bioactivity, metadata, screening-prioritization summaries, contract-manifest discovery, and cross-suite handoff builders to any MCP-aware agent (Codex CLI, Gemini CLI, Claude Code, etc.).

Maintainer: Ivo Djidrovski (@senseibelbi)

Contact: Use GitHub Issues for bugs, usage questions, and feature requests; use the in4r.ai contact form for private general inquiries; and report vulnerabilities through GitHub's private security advisory channel.

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 + WebSocket entrypoints\n/healthz, /readyz, /mcp, /mcp/ws"]
    Registry["Tool registry\ninputSchema + outputSchema"]
    Tools["Tool handlers\nretrieval, validation, handoff"]
  end

  subgraph Evidence["Tier-0 Evidence and Federation Layer"]
    Chemical["Chemical identity"]
    Hazard["Hazard datasets"]
    Exposure["Exposure + HTTK"]
    Bioactivity["Bioactivity + AOP link-outs"]
    Metadata["Model cards + applicability"]
    Prioritization["Screening prioritization\nAED / exposure signals"]
    Manifest["Contract manifest\nresources / tools / schemas"]
    Interop["Portable evidence packs\nAOP / PBPK handoff builders"]
  end

  subgraph Contracts["Contract and Artifact Layer"]
    McpSchemas["MCP response schemas\n/docs/contracts/schemas"]
    Portable["Portable object schemas\n/schemas"]
    Tests["Catalog, schema, and handoff tests"]
  end

  subgraph Upstream["Upstream Sources"]
    CTX["EPA CTX APIs"]
    Bundles["Packaged metadata bundles"]
  end

  Clients --> Router
  Router --> Registry
  Registry --> Tools
  Tools --> Chemical
  Tools --> Hazard
  Tools --> Exposure
  Tools --> Bioactivity
  Tools --> Metadata
  Tools --> Prioritization
  Tools --> Manifest
  Tools --> Interop
  Chemical --> CTX
  Hazard --> CTX
  Exposure --> CTX
  Bioactivity --> CTX
  Metadata --> Bundles
  Tools --> McpSchemas
  Interop --> Portable
  McpSchemas --> Tests
  Portable --> Tests

The current implementation follows a layered model:

• FastAPI + JSON-RPC expose /mcp and /mcp/ws, with /healthz and /readyz kept separate from domain logic.

• Retrieval resources own CompTox-native evidence access for chemical, hazard, exposure, bioactivity, cheminformatics, and metadata.

• Screening prioritization stays separate from interop builders and emits explicitly caveated AED/exposure prioritization summaries instead of final risk decisions.

• Contract manifest publishes the live public catalog plus schema inventory in machine-readable form for downstream MCP consumers.

• Interop tools package portable evidence objects for downstream MCP consumers without cloning AOP OECD semantics or PBPK execution semantics.

• Contract layers are split intentionally: docs/contracts/schemas/ for MCP response wrappers, schemas/ for cross-suite portable evidence objects.

• Regression gates keep README, live discovery, published schemas, and AOP/PBPK handoff fixtures aligned before release.

Related MCP server: TogoMCP

What's New In v0.2.6

This packaging hotfix makes the release wheel self-contained.

• All MCP response schemas now ship with the wheel under the active Python installation's data directory.

• Contract loading now checks the installed schema bundle when the server is launched outside a source checkout.

• Release verification now includes starting the server and calling MCP discovery from a clean wheel-only environment.

See the full release notes in docs/releases/v0.2.6_release_description.md.

For earlier changes, see the CHANGELOG.md, GitHub releases, or the versioned notes in docs/releases/.

Published Schemas

The portable CompTox handoff objects are now published as machine-readable JSON Schemas under schemas/, with matching examples under schemas/examples/.

Published object family:

• schemas/chemicalIdentityRecord.v1.json

• schemas/hazardEvidenceSummary.v1.json

• schemas/exposureEvidenceSummary.v1.json

• schemas/bioactivityEvidenceSummary.v1.json

• schemas/aopLinkageSummary.v1.json

• schemas/pbpkContextBundle.v1.json

• schemas/comptoxEvidencePack.v1.json

Design intent:

• keep the stable core fields required and allow additive convenience fields

• keep AOP OECD normalization outside CompTox MCP

• keep PBPK execution, qualification, and internal exposure objects outside CompTox MCP

• make the portable evidence layer consumable by downstream validators and orchestrators without scraping examples out of tests

See schemas/README.md, tests/test_portable_schemas.py, and tests/test_cross_suite_handoffs.py for the maintainer gates that keep published objects aligned with live payload generation.

Why this project exists

Regulatory and research teams rely on the CompTox API for high-quality chemical, exposure, and hazard data. Traditional workflows involve bespoke scripts or manual dashboard exports that are hard to share with AI copilots.

The EPA CompTox MCP server wraps those workflows in a secure, programmable interface:

• One MCP surface (/mcp HTTP + /mcp/ws WebSocket) delivers discovery and execution across chemical, bioactivity, exposure, hazard, metadata, interop, and supporting utility catalogues.

• Screening prioritization adds a separate, caveated signal-ranking path built from CompTox AED and exposure sources without claiming final NGRA decisions.

• Contract manifest discovery exposes the live public resources, tools, and schema inventory so downstream MCPs do not need to scrape docs to integrate safely.

• Evidence federation role – CompTox acts as the suite's source-grounded evidence ingress layer for downstream AOP, PBPK, O-QT, and orchestration workflows.

• Guardrails + provenance – JSON Schema validation, metadata attachments, transport audit hooks, and signed release attestations improve downstream reproducibility.

• Agent friendly – tested with Codex CLI, Gemini CLI, and Claude (see integration guide).

Experimental predictive and orchestrator components still exist in this repository, but they are not part of the default public MCP tool catalog exposed by the server today.

Feature snapshot

Table of contents

1. Architecture

2. What's new

3. Published schemas

4. Get an EPA CompTox API key

5. Quick start

6. Release verification

7. Configuration

8. Tool catalog

9. Running the server

10. Integrating with coding agents

11. Output artifacts

12. Security checklist

13. Current limitations

14. Development notes

15. Contributing

16. Security policy

17. Support

18. Code of conduct

19. Citation

20. Roadmap

21. License

Get an EPA CompTox API key (required)

The server can start without a key, but its live chemical tools cannot retrieve EPA data until one is configured.

1. Request an API key from EPA. EPA provides individual keys free of charge.

2. For help with the request, email ccte_api@epa.gov.

3. After cloning this repository, copy .env.example to .env and replace your_ctx_api_key_here with your key:

   CTX_API_KEY="your_key_from_epa"

Keep .env private. The readiness check in the quick start confirms that the configured key can authenticate with EPA.

Quick start

# 1) Install
git clone https://github.com/ToxMCP/comptox-mcp.git
cd comptox-mcp
pip install -e .

# 2) Configure the API key requested above
cp .env.example .env
# Open .env and replace your_ctx_api_key_here with your key

# 3) Run
uvicorn epacomp_tox.transport.websocket:app --host 127.0.0.1 --port 8000

# 4) Verify authenticated EPA readiness, then list MCP tools
curl -s http://localhost:8000/readyz | jq .
curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq '.result.tools | length'

With the server running, MCP clients can connect to http://localhost:8000/mcp (HTTP) or ws://localhost:8000/mcp/ws (WebSocket).

Once the server is running:

• HTTP MCP endpoint: http://localhost:8000/mcp

• WebSocket MCP endpoint: ws://localhost:8000/mcp/ws

• Health check: http://localhost:8000/healthz

• Readiness check: http://localhost:8000/readyz

• Architecture docs: docs/architecture_overview.md

• Contract docs: docs/contracts/README.md

• Release verification guide: docs/releases/release_artifact_verification.md

Verification (smoke test)

Once the server is running:

# health
curl -s http://localhost:8000/healthz | jq .

# list MCP tools
curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq '.result.tools | length'

# live Bisphenol A demo (also validates the configured API key)
curl -s http://localhost:8000/readyz | jq .
curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_chemical","arguments":{"query":"Bisphenol A","search_type":"equals"}}}' \
  | jq -r '.result.content[0].text'
curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"resolve_chemical_identifier","arguments":{"identifier":"80-05-7"}}}' \
  | jq -r '.result.content[0].text'

# live interop smoke
python scripts/mcp_interop_smoke.py --endpoint http://localhost:8000/mcp --json

# release-oriented smoke
python scripts/release_smoke.py --endpoint http://localhost:8000/mcp --json

Release verification

For published GitHub releases, signed provenance/SBOM attestation verification is documented in docs/releases/release_artifact_verification.md.

Configuration

Settings are resolved via pydantic-settings with .env/.env.local support. Key environment variables:

See docs/deployment.md for production hardening tips and expanded configuration.

Tool catalog

The default server currently registers ten public resources: chemical, bioactivity, exposure, hazard, chemical list, cheminformatics, metadata, interop, prioritization, and manifest. Full schema definitions (input and output) are returned via the MCP tools/list call. See tests/test_resources.py for examples of exercising each category.

Experimental components

The repository also contains predictive and orchestrator code under src/epacomp_tox/predictive/ and src/epacomp_tox/orchestrator/. Treat those modules as experimental until they are registered in the default server, documented as part of the canonical tool catalog, and backed by stable public response contracts.

Running the server

Local development

# install and start the dual-transport server
pip install -e .
uvicorn epacomp_tox.transport.websocket:app --host 127.0.0.1 --port 8000

The FastAPI app exposes both transports:

• HTTP JSON-RPC: http://localhost:8000/mcp

• WebSocket JSON-RPC: ws://localhost:8000/mcp/ws

Quick handshake + tool discovery via HTTP:

curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}'

curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools | length'

Hazard smoke test

Validate the hazard suite once transports are online:

# Bisphenol A toxval summary (expect a 40 mg/kg-day NOEL among the records)
curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_hazard","arguments":{"data_type":"toxval","dtxsid":"DTXSID7020182","summary":true}}}' | jq '.result.structuredContent.data[0]'

# Perfluorooctanoic acid cancer classification (expect CalEPA and IARC calls)
curl -s http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_hazard","arguments":{"data_type":"cancer","dtxsid":"DTXSID8031865","summary":true}}}' | jq '.result.structuredContent.data'

Bisphenol A should return HESS and HPVIS toxicity values (including the 40 mg/kg-day NOEL), while Perfluorooctanoic acid surfaces the ATSDR MRL alongside CalEPA and IARC cancer classifications. Errors typically indicate missing API credentials or upstream CompTox outages; inspect the returned metadata for rate-limit status when troubleshooting.

Endpoint smoke check

Before exposing the MCP server, run the endpoint checker to verify the upstream CompTox APIs are reachable:

python scripts/check_endpoints.py
# add --json for machine-readable output

The script pings each endpoint listed in docs/contracts/endpoint-matrix.md and reports latency plus HTTP status. Provide CTX_API_KEY/EPA_COMPTOX_API_KEY in the environment to avoid 401/403 responses.

Endpoint automation

A scheduled GitHub Action (.github/workflows/endpoint-check.yml) runs python scripts/check_endpoints.py --json every day at 06:00 UTC using the CTX_API_KEY secret. The workflow uploads endpoint_status.json as an artifact so operators can review upstream availability without rerunning the checker locally. Maintainers can also trigger the workflow for a specific pull request by applying the run-endpoint-check label (the job only executes for internal branches so secrets stay protected).

Production deployment

• Run via Gunicorn: gunicorn epacomp_tox.transport.websocket:app -c deploy/gunicorn_conf.py

• Container image: see deploy/Dockerfile for a hardened, non-root runtime.

• Probes: /healthz (liveness) and /readyz (performs CTX connectivity check). Non-200 responses should trigger restarts.

• Metrics: /metrics exposes Prometheus gauges derived from MCPServer.get_transport_metrics(). Sample scrape/OTEL configs live in deploy/prometheus_scrape.yaml and deploy/otel_collector_metrics.yaml.

• Additional rollout guidance (TLS, ingress, scaling) lives in docs/deployment.md.

Integrating with coding agents

The repository includes step-by-step instructions in docs/integration_guides/mcp_integration.md. Highlights:

• Codex CLI: add an HTTP provider pointing to http://localhost:8000/mcp with the Authorization: Bearer <token> header when auth is enabled.

• Gemini CLI: configure the provider transport to http with the same endpoint and optional headers.

• Claude Code / Cursor: update the MCP provider JSON to point to the HTTP endpoint; WebSocket is optional when streaming events are required.

Each guide covers tool listing, sample calls, binary payload handling, and troubleshooting tips (timeouts, auth failures, unexpected 4xx responses).

Output artifacts

Every successful tool invocation returns payloads designed for both agents and people:

• content: human-readable text for chat surfaces; chemical search and resolution include an explicit source line.

• structuredContent: machine-readable object results that exactly match the advertised output schema.

• structuredContent.data: the standard envelope used when a tool's native result is an array or scalar.

• _meta: runtime-only upstream, provenance, and session information that does not alter the scientific result schema.

• Default registered tools are retrieval and federation oriented; experimental predictive/orchestrator modules in this repository are not part of the canonical public surface yet.

Tool annotations identify these public retrieval tools as read-only and idempotent. Approval persistence is controlled by the MCP client (for example Claude Desktop), not by the server.

Security checklist

• Disable BYPASS_AUTH and front the MCP server with OAuth/OIDC once deployed beyond local development.

• Restrict CORS_ALLOW_ORIGINS to approved hosts when exposing the HTTP transport.

• Rotate CTX_API_KEY regularly and store secrets outside the repository (e.g. cloud secret manager or OS keychain).

• Monitor /metrics for negotiated capability changes and unexpected spikes in tools/call failures.

• Enable HTTPS/TLS at the ingress or reverse proxy layer.

• Keep GitHub branch protection, dependency review, and CodeQL scanning enabled on the canonical repository.

• Pin GitHub Actions workflows to immutable commit SHAs and update them intentionally during maintenance windows.

• Generate and retain a CycloneDX SBOM for release artifacts so downstream consumers can audit package composition.

• Publish signed provenance and SBOM attestations for release artifacts so consumers can verify what was built and released.

• Follow coordinated vulnerability disclosure guidance in SECURITY.md.

Development notes

Architecture snapshot

┌────────────────┐       ┌────────────────────────────┐       ┌──────────────────────┐
│ MCP Client     │  MCP  │ FastAPI App                │  MCP  │ CompTox Resources    │
│ (CLI / IDE)    │──────▶│ HTTP (/mcp) & WS (/mcp/ws) │──────▶│ • chemical           │
└────────────────┘       │ • tool registry            │       │ • bioactivity        │
       │                 │ • JSON-RPC dispatch        │       │ • exposure / hazard  │
       ▼                 │ • response validation      │       │ • metadata / interop │
                         └────────────────────────────┘       │ • utility catalogs   │
                                                              └──────────────────────┘

Guardrails & governance

• Applicability-domain definitions, policy defaults, and remediation steps live under metadata/ with JSON Schema validation.

• Response contracts live under docs/contracts/schemas/ (see docs/contracts/README.md) and are enforced before MCP responses are returned; upstream failover policies are summarized in docs/contracts/endpoint-matrix.md.

• Experimental predictive/orchestrator modules remain in-repo design and implementation assets; they are not part of the default public tool catalog until explicitly registered and documented.

Testing & quality gates

• tests/test_mcp_conformance_suite.py covers handshake, catalog discovery, and streaming behaviours.

• tests/test_tool_contracts.py enforces output schema declarations for the registered resources.

• scripts/smoke_ctx.sh runs integration smoke tests against the live CTX API.

• scripts/mcp_http_smoke.sh performs a quick JSON-RPC handshake and tool listing against the HTTP transport.

• scripts/mcp_interop_smoke.py validates the public interop tool path end-to-end over the HTTP transport.

• scripts/release_smoke.py exercises authenticated readiness, manifest discovery, deterministic identifier resolution, screening prioritization, interop builders, and WebSocket parity in one release-oriented pass.

• .github/workflows/live-interop-smoke.yml runs the interop smoke path in GitHub Actions on demand or on a weekly schedule when CTX_API_KEY is configured.

• Documentation builds (scripts/build_docs.sh) and CI workflows keep diagrams and links healthy.

• Experimental predictive/orchestrator suites remain valuable internal regression coverage, but they should not be presented as canonical public-surface checks.

Roadmap

• Completed: v0.2.6 release cleanup — self-contained wheel contract schemas and standalone startup verification.

• Completed: v0.2.5 release cleanup — schema-valid, readable chemical search and resolution responses.

• Completed: v0.2.4 release cleanup — strict MCP pagination compatibility for HTTP and WebSocket discovery.

• Completed: v0.2.3 release cleanup — audit hardening, privacy controls, provenance capture, and workflow governance.

• Completed: v0.2.2 release cleanup

• Completed: v0.2.1 stabilization and the matching v0.2.1 release description

• Revisit predictive/orchestrator publication only after the default server, contracts, and docs all agree.

Current limitations

• Predictive and orchestrator code still exists in-repo, but it is not part of the default public MCP tool catalog.

• CompTox MCP publishes AOP linkage summaries, but OECD-style mechanistic normalization still belongs in aop-mcp.

• CompTox MCP publishes PBPK context bundles, but PBPK execution, qualification, uncertainty synthesis, and internal exposure objects still belong in pbpk-mcp.

• BER logic, stop/continue/refine policy, and final NGRA decisions remain out of scope for this server.

• Live evidence retrieval still depends on upstream CTX availability and API credentials.

Contributing

See CONTRIBUTING.md for development workflow, coding standards, and PR expectations.

Security policy

See SECURITY.md for coordinated disclosure guidance and supported reporting channels.

Support

See SUPPORT.md for public support, bug-reporting, and non-security guidance.

Code of conduct

See CODE_OF_CONDUCT.md for collaboration expectations across the project and suite.

Citation

If you use this project in research or derived tooling, please cite:

• Ivo Djidrovski. BioRxiv preprint. DOI / link: 10.64898/2026.02.06.703989v1

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

Acknowledgements

• EPA's Center for Computational Toxicology and Exposure (CCTE)

• The ctx-python project for the official CompTox Python bindings

• The Model Context Protocol community for defining the automation surface we target