MCP server¶

clincalc can expose every clinical calculator as a local Model Context Protocol (MCP) server for LLM hosts. This makes the calculator catalogue discoverable as native tools: the host sees one tool per calculator, each with the calculator's own JSON Schema as its input contract.

The MCP surface is optional. The normal clincalc CLI remains the default install, and the pure engine still stays a serde-only leaf when built with default-features = false.

Install with MCP support¶

MCP support is behind the optional mcp Cargo feature:

cargo install clincalc --features mcp

Until the crate is published to crates.io, install from Git:

cargo install --git https://github.com/pacharanero/clincalc clincalc --features mcp

Check that the command is available:

clincalc mcp

clincalc mcp is a stdio MCP server, so it is expected to keep running while an MCP host is connected. It is not an interactive CLI command and it does not print the calculator catalogue to your terminal.

If your binary was built without MCP support, clincalc mcp prints a targeted reinstall hint instead of treating mcp as an unknown calculator.

Configure an MCP host¶

Most local MCP hosts take a command and arguments. Use:

{
  "mcpServers": {
    "clincalc": {
      "command": "clincalc",
      "args": ["mcp"]
    }
  }
}

If clincalc is not on the host's PATH, use the absolute path to the installed binary:

{
  "mcpServers": {
    "clincalc": {
      "command": "/home/you/.cargo/bin/clincalc",
      "args": ["mcp"]
    }
  }
}

The exact configuration file location depends on the MCP host. The important point is that the host launches clincalc mcp over stdio.

Tool names¶

Each calculator is exposed as:

clincalc_<name>

Examples:

clincalc_feverpain
clincalc_news2
clincalc_cha2ds2vasc
clincalc_qrisk3
clincalc_qfracture

Tool definitions are generated from clincalc::all(). Adding a calculator to the registry automatically exposes it through MCP, with no MCP-specific wrapper.

Inputs¶

Each MCP tool's input schema is the same JSON Schema returned by the CLI:

clincalc calc feverpain --schema

For example, clincalc_feverpain expects the same object as:

clincalc calc feverpain --input examples/feverpain.json --format json

{
  "fever": true,
  "purulence": true,
  "attend_rapidly": true,
  "inflamed_tonsils": false,
  "absence_of_cough": false
}

The MCP server does not infer missing clinical facts. If a required field is absent or invalid, the calculator returns a validation error and the model should ask for the missing information.

Results¶

MCP calls return the same structured CalculationResponse shape as the CLI's JSON output:

{
  "calculator": "feverpain",
  "result": 3,
  "interpretation": "...",
  "working": {
    "score": 3
  },
  "reference": "..."
}

That shape is intentionally timestamp-free and patient-free. A host that records the calculation should add patient linkage, timestamps, author identity, and audit metadata outside clincalc.

Why use MCP instead of the CLI?¶

The CLI is still the universal surface for humans, shell scripts, and simple agents. MCP adds one specific advantage: native LLM discoverability.

With the CLI, an agent must learn to run clincalc list, inspect clincalc calc <name> --schema, construct JSON, and call clincalc calc <name> --input .... That works, and the CLI is designed for it.

With MCP, the host presents the calculators directly as typed tools. The model sees the available calculators and their input schemas without first learning the command-line protocol.

Safety boundaries¶

• The server is local stdio only; it does not open a network listener.
• The server does not read patient records or workspace files.
• The server does not store results.
• The server does not add timestamps, patient ids, or audit entries.
• The server does not invent missing clinical inputs.
• Proprietary unavailable stubs are still visible and callable, so licence-locked tools are named rather than silently hidden.

Developer notes¶

The implementation lives in src/mcp.rs and is compiled only with the mcp feature. The feature pulls in rmcp and tokio; these dependencies are not present in the default-features = false engine build.

Useful checks while changing MCP support:

cargo test --no-default-features
cargo test
cargo test --features mcp
cargo clippy --all-targets --features mcp -- -D warnings

The design spec is spec/mcp.md.