OathMCP

An agent-native Model Context Protocol server
for 39 established clinical calculators and structured interpretation tools.
OathMCP gives AI agents strict input and output schemas, per-value unit handling,
plausibility guards, cited evidence resources, and deterministic calculation
paths over stdio, stateless HTTP, and Cloudflare Workers.

The included calculators are documented clinical instruments, formulas, and
policy models. OathMCP is an implementation of those sources, not new clinical
research and not a replacement for the original publications, governing
policies, or local protocols.

Responsible use: OathMCP provides clinical decision-support calculations,
not medical advice, diagnosis, or treatment. The clinician remains responsible
for selecting the appropriate calculator, confirming its population and
version, checking the inputs and units, interpreting the result in context,
and making every clinical decision. See
Responsible Use for the complete responsibility,
deployment, privacy, warranty, and limitation-of-liability notice.

Release status

Version 0.1.0 is the planned first open-source release and is not yet
published to npm.
All 39 calculator dossiers and all four review groups currently derive
scenario_verified, and the ordinary acceptance, clinical-release, transport,
compatibility, and package gates pass.

In OathMCP, scenario_verified has a precise repository meaning: the implemented
model and its declared population, variant, inputs, outputs, warnings,
interpretations, and exclusions are linked to reviewed sources and pass frozen
source-derived cases through the engine, full MCP tool, and compact MCP tool.
It does not mean regulatory approval, guarantee suitability for an individual
patient, or remove clinician discretion.

• Release attestation
• Release process
• Changelog

Quick start

From source

Requires Node.js 22 or later.

git clone https://github.com/OATH-md/OathMCP.git
cd OathMCP
npm ci
npm run check
npm run start:stdio

Configure an MCP-compatible client to run the built stdio server:

{
  "mcpServers": {
    "oath": {
      "command": "node",
      "args": ["/absolute/path/to/OathMCP/dist/server/stdio.js"]
    }
  }
}

npm package

After the first registry publication:

npx oath-mcp

{
  "mcpServers": {
    "oath": {
      "command": "npx",
      "args": ["-y", "oath-mcp"]
    }
  }
}

Remote deployment

The remote server is stateless: each request receives a fresh MCP server and no
session state is retained. A client points at the deployed streamable HTTP URL:

{
  "mcpServers": {
    "oath": {
      "url": "https://mcp.oath.md/mcp"
    }
  }
}

Run the HTTP transports locally:

npm run start:http          # Node/Express on http://127.0.0.1:3000/mcp
npx wrangler dev            # Cloudflare Workers development server on /mcp

The Node server binds to 127.0.0.1 by default. Set HOST and PORT only when
the deployment boundary is intentional. Browser clients must have their exact
origin in the comma-separated allowlist:

OATH_ALLOWED_ORIGINS=https://app.example,https://review.example npm run start:http

An absent Origin is accepted for non-browser MCP clients. Any nonempty origin
not present in OATH_ALLOWED_ORIGINS receives HTTP 403; wildcard origin rules
are not supported. Use the same binding for Worker deployments. Both HTTP
implementations accept CORS preflight with OPTIONS /mcp, perform MCP requests
with POST /mcp, and return a JSON 405 without reading the body for every other
method on that path.

Deploy to Workers only after reviewing Responsible Use,
the security and privacy boundary, and the release checklist. The official
Worker uses Cloudflare Workers Builds: a push to main runs npm run check:deploy, then deploys with the checked-in wrangler.jsonc only if that
gate succeeds. For a manual recovery deployment:

npm run deploy:worker

The official documentation is available at https://mcp.oath.md/docs/, and the
public unauthenticated endpoint is https://mcp.oath.md/mcp. The endpoint serves
the compact four-tool dispatch surface,
applies an edge limit of 120 requests per client per minute, accepts browser
requests only from https://oath.md and https://mcp.oath.md, and enables
10% sampled Workers observability. Application code does not log request bodies.
Service metadata is available at https://mcp.oath.md/health; the complete
notice is available at https://mcp.oath.md/responsible-use and through the MCP
resource oath://responsible-use. The independently deployed Blume source lives
in the documentation site directory.
See Hosted endpoint operations.

OathMCP does not require patient identifiers. A deployment that accepts
protected or personal health information is the deployer's responsibility and
must provide the authentication, authorization, logging, retention, contractual,
and regulatory controls required in its jurisdiction.

MCP surface

For each calculator, full mode registers:

• calculate_<id> — a read-only calculation tool returning result schema 1.1;
• evidence_<id> — a resource at calc://<id>/evidence containing citations,
  interpretation bands, limitations, and safety notes;
• interpret_<id> — for ABG, CSF, and hepatitis B, a prompt that asks the host
  model to summarize deterministic findings without adding a diagnosis or
  treatment plan.

Four agent-dispatch tools sit above the catalog:

• find_calculator returns a bounded ranked set plus matched,
  needs_clarification, or no_match; a clarification state must be resolved
  before calculation;
• describe_calculator returns the exact model, inputs, outputs, limitations,
  version, and evidence metadata;
• calculate_panel runs selected calculators against compatible shared inputs,
  with isolated per-calculator failures; duplicate ids and unused shared or
  override keys are rejected instead of silently ignored;
• calculate dispatches one calculator in compact mode with the same clinical
  contract as its direct tool.

Set OATH_MCP_MODE=compact to expose only the four dispatch tools while keeping
all evidence resources. Full mode is the compatibility default.

Analyte inputs accept either a bare number in the documented canonical unit or
an explicit quantity:

{
  "creatinine": {
    "value": 106,
    "unit": "umol/L"
  }
}

Bare values always use the field's declared canonical unit. There is no global
US/SI mode.

Calculator catalog

Architecture and assurance

Each live calculator consists of three reviewed artifacts:

1. specs/<id>.yaml defines the strict runtime and MCP contract;
2. src/compute/<id>.ts provides a pure, exactly typed calculation over
   normalized inputs;
3. validation/calculators/<id>.yaml records searches, exact claim locators,
   current sources, and frozen reference, edge, and agent cases.

The server derives its tools, prompts, and resources from the specs. Runtime
specs contain no test fixtures. Review state is derived by code rather than
authored in YAML, and release checks fail when required sources, cases,
attestations, or currentness windows are incomplete.

The assurance ledger verifies that OathMCP implements the declared calculator
version and documented behavior. It does not claim that OathMCP invented or
revalidated the underlying clinical instrument.

Development and contribution

npm run check                   # complete acceptance gate
npm run check:clinical-release  # source, scenario, currentness, and attestation gate
npm run new:calculator -- --id example --archetype formula
npm run check:calculator -- --id example
npm run promote:calculator -- --id example
npm run lint:specs
npm run typecheck
npm run test
npm run build

See Contributing, the
calculator authoring guide, and the
spec house style. Report security or patient-safety
issues through Security Policy and never include patient data in
an issue, test, or example.

Documentation

• Responsible use and responsibility allocation
• Calculator authoring and promotion
• Specification house style
• Clinical assurance ledger
• Reproducible source-review protocol
• Release process
• Security policy
• Changelog

License

OathMCP is available under the Apache License 2.0. Copyright and
attribution information is provided in NOTICE. The license governs
permission to use, modify, and distribute the software; it does not replace the
clinical and operational boundaries in Responsible Use.