Pbpk Mcp

PBPK MCP Server

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

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

Public MCP endpoint for physiologically based pharmacokinetic (PBPK) simulation, qualification, and dossier export. Expose PK-Sim / MoBi .pkml, MCP-ready rxode2 .R, deterministic and population runs, and OECD-oriented validation/reporting 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\npbpk-mcp.v1 contracts"]
        Tools["Tool handlers\ndiscovery, validation,\nexecution, reporting"]
    end

    subgraph Contracts["Discovery and Qualification Layer"]
        Catalog["Filesystem model catalog\nADAPTER_MODEL_PATHS"]
        Manifest["Static manifest validation\nvalidate_model_manifest"]
        Qualification["Qualification metadata\ncapabilities, profile,\nvalidation, qualificationState"]
        Verification["Executable verification\nrun_verification_checks"]
        Reports["OECD dossier export\nexport_oecd_report"]
    end

    subgraph Backends["Execution Backends"]
        OSPSuite["OSPSuite backend\nPK-Sim / MoBi (.pkml)"]
        Rxode2["rxode2 backend\nMCP-ready R (.R)"]
        Convert["Conversion-only inputs\n.pksim5 and .mmd -> .pkml or .R"]
    end

    subgraph Runtime["Runtime and QA Path"]
        Jobs["Celery + Redis jobs\nasync runs and result handles"]
        Overlay["Source-overlay runtime\nbind mounts + worker image"]
        Tests["Unit + live smoke tests\nrelease readiness checks"]
    end

    Clients --> Router
    Router --> Registry
    Registry --> Tools
    Tools --> Catalog
    Tools --> Manifest
    Tools --> Qualification
    Qualification --> Verification
    Qualification --> Reports
    Tools --> OSPSuite
    Tools --> Rxode2
    Convert --> OSPSuite
    Convert --> Rxode2
    Tools --> Jobs
    Overlay --> Tools
    Qualification --> Tests
    Overlay --> Tests

The current implementation follows a layered model:

• FastAPI + JSON-RPC expose /mcp and /health, and keep transport concerns separate from PBPK model logic.
• Tool handlers are the agent-facing API. They validate inputs, call adapters, and emit structured responses with normalized pbpk-mcp.v1 payloads.
• Discovery and manifest validation make model files visible before load, and keep curation checks separate from runtime execution.
• Execution backends route .pkml files to ospsuite and MCP-ready .R modules to rxode2, while treating .pksim5 and .mmd as conversion-only inputs.
• Qualification metadata keeps capabilities, profile, validation, and qualificationState separate so runnable does not get conflated with scientifically qualified.
• Executable verification adds lightweight but structured runtime checks on top of qualification metadata, including parameter-unit consistency, structural flow/volume consistency, deterministic smoke, result-integrity, and repeat-run reproducibility checks without conflating them with formal qualification evidence.
• Packaged-default runtime + overlay smoke tests keep the documented tool surface synchronized with the live API while still leaving an explicit maintainer override path for workspace iteration.
• Release metadata checks now verify that package version markers, compose/env SERVICE_VERSION, README release markers, the top changelog entry, and the matching docs/releases/ note stay aligned.
• Release artifact evidence now retains a machine-readable report with sdist/wheel hashes and the linked contract-manifest identity during tag builds.

See docs/architecture/dual_backend_pbpk_mcp.md for the fuller architecture narrative, docs/architecture/capability_matrix.md for the published support matrix, docs/architecture/mcp_payload_conventions.md for the response contract, docs/deployment/runtime_patch_flow.md for the operator path behind the current local deployment model, and docs/pbpk_model_onboarding_checklist.md for the recommended trust pipeline when onboarding another chemical model. See docs/architecture/exposure_led_ngra_role.md for the explicit boundary statement on what PBPK MCP does and does not own inside exposure-led NGRA workflows. See docs/architecture/toxmcp_suite_index.md for the shortest cross-service routing guide inside the ToxMCP suite. See benchmarks/regulatory_goldset/regulatory_goldset_summary.md for the current gold-set documentation benchmark summary derived from the fetched public-code PBPK corpus. Internal examples such as the bundled synthetic reference model remain bounded MCP rehearsal models, not benchmark exemplars.

What's new in v0.5.0

• Enforced single-use replay rejection for bearer tokens that carry jti claims, so repeated presentation of the same token identifier is now treated as an auth failure instead of silently succeeding.
• Upgraded /mcp to the MCP 2025-11-25 JSON-RPC behavior, including clean success/error response shapes, standard tool schemas, structured tool results, and standard MCP resources exposed through pbpk:// URIs.
• Moved canonical PBPK tool modules to mcp_bridge.pbpk_tools while keeping a temporary deprecated mcp.* compatibility shim for existing internal scripts.
• Aligned REST and MCP parameter writes on one governance path, so snapshots, audit-backed sweep detection, and the returned governance payload now behave consistently across both transports.
• Fixed set_parameter_value(updateMode="relative") so relative deltas are applied against the current parameter value before validation, audit, and persistence.
• Completed the v0.5.0 release alignment across package metadata, compose/runtime version markers, the README, and the dedicated release-note entry, while moving the remaining legacy env-alias removal target to v0.6.0.

Why this project exists

PBPK workflows often juggle PK-Sim or MoBi transfer files, R-authored mechanistic models, runtime-specific scripts, and incomplete qualification notes. That makes them difficult for coding agents to automate safely and difficult for reviewers to inspect consistently.

The PBPK MCP server wraps those workflows in a single, programmable interface:

• Unified MCP surface – discovery, manifest checks, load, validation, execution, results, and dossier export share one tool catalog.
• Dual-backend execution – .pkml models run on ospsuite; MCP-ready .R models run on rxode2.
• Qualification-aware workflows – runtime capability, scientific profile, preflight validation, and derived qualificationState stay separate.
• NGRA-ready PBPK objects – validation and dossier export expose PBPK-side typed objects such as assessmentContext, pbpkQualificationSummary, uncertaintySummary, uncertaintyHandoff, internalExposureEstimate, a typed external uncertainty-register reference, and a typed external PoD reference handoff, now with explicit boundary/support metadata plus additive semanticCoverage for PBPK-side uncertainty semantics, without collapsing PBPK MCP into a full decision engine.
• Exposure-led boundary clarity – assessmentContext.workflowRole, assessmentContext.populationSupport, pbpkQualificationSummary.evidenceBasis, pbpkQualificationSummary.workflowClaimBoundaries, and pbpkQualificationSummary.reviewStatus now make IVIVE/exposure dependencies, supported population contexts, no-direct-in-vivo status, reviewer-attention requirements, and claim boundaries explicit.
• Static curation feedback for NGRA gaps – validate_model_manifest now exposes manifest.ngraCoverage plus a compact curationSummary, so missing workflow-role, population-support, evidence-basis, and claim-boundary declarations are visible before load in both machine-readable and reviewer-facing form; that summary now also carries an anti-misread block, explicit summary-transport risk for thin/forwarded views, a normalized cautionSummary with advisory-versus-blocking handling, a machine-readable exportBlockPolicy, and rendering guardrails for analyst-facing clients.
• Regulatory benchmark bar – the workspace now also ships a gold-set benchmark dossier under benchmarks/regulatory_goldset/ plus an advisory curationSummary.regulatoryBenchmarkReadiness block, so MCP reviewers can compare a model dossier to public regulatory-grade PBPK packaging without promoting research models to regulatory-ready status. That advisory block now also carries per-dimension evaluation paths, benchmark examples, and concrete next-artifact guidance for closing documentation gaps.
• Reviewer-friendly discovery summaries – discover_models and /mcp/resources/models now surface manifestStatus, qualificationState, and a compact curationSummary so curated illustrative examples can be distinguished from exploratory or partially declared models at discovery time, with explicit anti-misread guidance and no official “bare label only” rendering path.
• Human-review summary – OECD report export now includes a compact humanReviewSummary block that pulls those boundary fields into one reviewer-facing surface, including reviewer-status, unresolved-dissent context, normalized cautionSummary, summary-transport risk, exportBlockPolicy, and rendering guardrails, without creating a second hidden score or decision engine.
• Anti-misread report section – OECD report export now also includes a mandatory misreadRiskSummary block so common over-interpretations are stated explicitly next to the primary report summary instead of being left implicit.
• Audit-backed operator sign-off – trust-bearing outputs now surface an additive operatorReviewSignoff summary plus an explicit operatorReviewGovernance block derived from the real workflow contract, and the REST surface now exposes viewer-readable /review_signoff/history so recorded acknowledgement, bounded-use sign-off, rejection, and revocation remain auditable without being mistaken for a second qualification score, override path, or decision authority.
• Explicit audit-storage boundary – the default local stack keeps reviewer-readable hash-chained audit history on the local filesystem, while stronger off-host immutability depends on the S3/Object-Lock backend and external retention discipline documented for operators.
• Conservative PK/NCA output surface – calculate_pk_parameters and the internal deterministic-result summaries now expose additive auc0Inf, lambdaZ, halfLife, extrapolated-AUC share, terminal-phase point counts, and screening-oriented ncaStatus/ncaWarnings, while clearance and volume distribution remain withheld unless explicit dose context is declared.
• No bundled analyst UI in the current release – trust-bearing review remains on the MCP and REST surfaces for now; /console and /console/api/* are intentionally absent until a stronger reviewer-facing client exists.
• Thin-client trust-surface contract – trust-bearing MCP tool results now also expose a top-level trustSurfaceContract so thin clients can find the nested summary surfaces, required adjacent caveats, and primary block reasons they must carry together instead of rediscovering those paths tool by tool.
• Traceable predictive evidence – performance bundles can now carry traceability supplements, and the report path now warns when bundled benchmark rows do not actually line up with the declared datasets, target outputs, or acceptance criteria.
• Objective performance-evidence metrics – observed-versus-predicted rows now retain additive objectiveEvidence metrics such as fold error, row-level RMSE, and simple acceptance-criterion evaluation when the criterion is machine-interpretable, without replacing the original evidence row semantics.
• Reviewer-facing dossier improvement signals – verification and OECD report export now attach an advisory dossierImprovementSignals block sourced from the regulatory benchmark comparison so maintainers can see the highest-leverage dossier/documentation gaps without changing qualification state.
• Discovery before execution – models are discoverable from disk before they are loaded into a live session.
• Release-tested local deployment – the packaged local runtime and the explicit source-overlay maintainer profile are both exercised with unit tests, live-stack tests, and a readiness check.
• Model-specific executable qualification checks – MCP-ready models can add runtime verification hooks for checks such as flow/volume consistency, mass balance, or numerical stability without overstating regulatory qualification.

> rxode2 is a native PBPK execution engine in this project. It is not limited to Berkeley Madonna conversion workflows.

---

Feature snapshot

| Capability | Description | | --- | --- | | 🧬 Dual-backend PBPK execution | Route .pkml models to ospsuite and MCP-ready .R models to rxode2 through one MCP surface. | | 🗂️ Model discovery and curation | Discover supported model files from ADAPTER_MODEL_PATHS, inspect unloaded models, and run static manifest checks before load. | | 🛡️ OECD-oriented qualification | Keep capabilities, profile, validation, and qualificationState explicit; expose applicability, provenance, uncertainty, implementation verification, software-platform qualification, and qualification gaps. | | 🧱 NGRA-ready PBPK objects | Emit typed PBPK-side objects such as assessmentContext, pbpkQualificationSummary, uncertaintySummary, uncertaintyHandoff, internalExposureEstimate, a typed uncertaintyRegisterReference, a typed pointOfDepartureReference, and a thin BER-ready reference bundle in dossier export, with explicit boundary/support flags plus additive uncertainty semanticCoverage for downstream NGRA orchestration and without embedding BER decision logic in PBPK MCP. | | 📐 Published object schemas | Publish machine-readable JSON Schemas and example payloads for the PBPK-side NGRA handoff object family under schemas/ so downstream tooling can validate the public object layer directly. | | 🔌 External PBPK normalization | Normalize externally generated PBPK outputs, qualification metadata, and optional PoD references through ingest_external_pbpk_bundle without pretending PBPK MCP executed the upstream engine. | | ✅ Executable verification | Run run_verification_checks to capture preflight validation, parameter coverage, parameter-unit consistency, structural flow/volume consistency, deterministic smoke, deterministic result integrity, repeat-run reproducibility, optional population smoke, and verification-evidence summaries in one payload. | | 📈 Deterministic and population jobs | Submit asynchronous deterministic and population simulations, then retrieve result handles, stored results, and PK summaries. | | 🧾 Dossier export | Export a structured OECD-style report with model metadata, validation context, checklist state, parameter provenance, performance evidence, uncertainty evidence, verification evidence, and software-platform qualification evidence when declared. | | ⚙️ Source-overlay deployment hygiene | Recreate the local stack through the documented compose entrypoints and validate the live contract with readiness and smoke gates. | | 🤖 Agent friendly | Verified through MCP HTTP surfaces such as /mcp/list_tools, /mcp/call_tool, and /mcp/resources/models, with live-stack regression checks. |

---

Table of contents

1. [Architecture](#architecture)

…

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

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