Institutional · Behind the firewall

On-prem deployment

The MeasureGPT hospital package contains a Docker image, a streamable HTTP MCP server at /mcp, and two auth modes. These auth modes do not use the Clerk OAuth of the public demo. Thus CHOIR and the approved internal systems can call the service inside the perimeter.

Docker · HTTP /mcp · token or network · no public data-collection path

The public site on this host is an educational demo. It has accounts, rate limits, and OAuth on /mcp. The on-prem installation is a different profile of the same codebase. It has the same corpus and the same tools. Hospital programmers can install it behind the firewall. They do not need to clone the research monorepo. They do not need to open the service to the internet.

Rights

License and CHOIR relationship

MeasureGPT was developed to support CHOIR. It also supports the approved institutional workflows that operate with CHOIR behind the firewall. The software is closed source. It is not part of the CHOIR open-source project or the CHOIR license.

Topic	Position
What this is	Proprietary software with curated psychometric metadata: cutoffs, norms, bands, citations, and provenance
CHOIR	The software integrates with CHOIR and SHC systems. It does not have a second license as CHOIR. You cannot redistribute it under the CHOIR terms.
Institutional use	Permitted only under a separate written agreement with the copyright holder
Not granted	Public redistribution, sublicensing, and use of the package as CHOIR open source
Not in the package	The closed-access paper PDFs in `papers/`. The service does not need them at runtime.

More detail for the operator is in LICENSE, NOTICE.md, and docs/INSTALL-HOSPITAL.md. These files are in the source tree and in the offline bundle.

This is an educational interpretation service. It is not a diagnostic device. Each output has caveats. Use an output as decision support. Do not use it as a diagnosis.

Problem

Why a separate on-prem profile

FirewallOften a clinical workflow cannot call a public SaaS MCP server. The service must run inside the institutional network. Scoring must not need an outbound connection.

Not the public demoThe public /mcp endpoint uses Clerk OAuth, user tiers, and protection against automatic data collection. A hospital needs perimeter authentication and, optionally, a shared secret. A hospital does not need controls against the creation of many accounts.

What the operator receivesThe hospital IT department should receive a Docker image with a version and an installation document. It should not receive the full git history of the research, the spot checks, and the closed-access PDFs.

Same contractCHOIR continues to use streamable HTTP at /mcp. The tools are the same as the tools of this site: list_measures, interpret_score, the profile tools, and the optional analysis recipes.

Institutional network: internet to CHOIR, CHOIR to private MeasureGPT, no direct MeasureGPT internet path — The institutional placement. Public traffic goes to CHOIR. CHOIR and the approved systems call MeasureGPT inside the firewall. MeasureGPT does not need a public internet endpoint.

Package

What the package contains (same repository, optional profile)

There is no second git repository in the working tree. Development stays in this monorepo. The distribution is an offline bundle with a version tag. npm run package:hospital builds it.

Artifact	Role
`measuregpt-hospital:<ver>`	The Docker image with Node, R, and Python. It gives the web UI and the streamable HTTP `/mcp` endpoint.
`docker-compose.hospital.yml`	Starts the service with one command. It reads the environment from `.env.hospital` only.
`MCP_AUTH_MODE`	Use `token` (recommended) or `network`. Do not use the public `oauth` mode.
`hospital-smoke.sh`	Checks the health profile. It also checks the MCP endpoint for a 401 response and for bearer authentication.
`mcp-contract/`	The pinned tool schemas and example envelopes for the CHOIR developers
`samples/choir-interpret-score-phq9.json`	One PHQ-9 request and response example
`k8s/`	A short example of a ClusterIP Deployment, a Service, and a NetworkPolicy
`THIRD-PARTY-NOTICES.md` and `sbom.cdx.json`	The license inventory of the production npm packages, and an SBOM that uses a CycloneDX-style format

The related source files are src/lib/mcp-auth-mode.ts, src/mastra/http.ts, docs/INSTALL-HOSPITAL.md, docs/hospital/, scripts/package-hospital-image.sh.

Security

Auth modes for /mcp

Mode	When	Client requirement
`oauth`	For the public demo. This is the default when the variable is not set.	A Clerk OAuth bearer token. Do not use this mode in an isolated hospital network.
`token`	Recommended on-prem	`Authorization: Bearer <MCP_SERVICE_TOKEN>`
`network`	Trust from the perimeter only, such as a VPN or a private subnet	None. The service trusts every host that can connect to the port.

In token mode and in network mode, the service gives each successful caller a trusted institutional identity. This identity has full access to the rubrics for internal use.
The hospital profile does not need Clerk or Turnstile.
GET /api/health reports deployment.profile: "hospital" and protections.ready. It does not need the bot checks of the public demo.
Warning: never set network on a host that the public internet can reach.

Runbook

Install (offline image)

Load the image
```
gunzip -c measuregpt-hospital-1.0.0-image.tgz | docker load
# → measuregpt-hospital:1.0.0
```
If you use more than one node, or if you use Kubernetes, you can add a tag and push the image to a private registry. This step is optional. The image is the same as the image in the tar file.

Configure

cp .env.hospital.example .env.hospital
# For token mode (the default), set MCP_SERVICE_TOKEN.
# For network mode, set MCP_AUTH_MODE=network and leave the service token empty.
# MEASUREGPT_VERSION=1.0.0

Start

docker compose -f docker-compose.hospital.yml --env-file .env.hospital up -d
# The application and the MCP server are at http://localhost:3583/mcp

Compose reads .env.hospital into the container. It does not use the public-demo .env file of a developer.

Test the installation

curl -fsS http://127.0.0.1:3583/api/health
# The result must have deployment.profile == "hospital" and protections.ready == true

bash hospital-smoke.sh
# In token mode, run: MCP_SERVICE_TOKEN=… bash hospital-smoke.sh

The full operator guide is docs/INSTALL-HOSPITAL.md. A maintainer builds the bundle with npm run package:hospital.

Integration

Point CHOIR at /mcp

The endpoint uses streamable HTTP MCP. It has the same tools as the MeasureGPT web UI. Token mode is the recommended mode.

Token mode (recommended)

MEASUREGPT_MCP_URL=https://measuregpt.your-hospital.internal/mcp
MEASUREGPT_MCP_AUTHORIZATION="Bearer ${MCP_SERVICE_TOKEN}"

{
  "mcpServers": {
    "measuregpt": {
      "url": "https://measuregpt.your-hospital.internal/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_MCP_SERVICE_TOKEN"
      }
    }
  }
}

Network mode

MEASUREGPT_MCP_URL=https://measuregpt.your-hospital.internal/mcp
# no Authorization header

Tools CHOIR can call

Tool	Purpose
`list_measures` and `get_measure`	Give the catalog and the full rubric
`interpret_score`	Converts a measure and a score to a severity and norm interpretation
`get_validation_studies`	Gives the cited validation literature
`list_profiles` and `interpret_profile`	Give the multi-score batteries
`list_analysis_recipes`, `submit_analysis`, and `get_analysis_job`	Run the optional R and Python recipes on the same host

The same host also has two optional REST routes: GET /api/measures and POST /api/interpret. For offline development, use the contract snapshots in mcp-contract/ and the PHQ-9 example in samples/.

Operations

Operations notes

Port. The default port is 3583. Terminate TLS at the institutional reverse proxy. For /mcp, disable body buffering and permit long streams.
Outbound traffic. The catalog, the interpretation, the profiles, and the analysis do not need outbound traffic. The optional chat needs a model API key and an outbound connection.
Upgrade. Do these steps: load the new image tag, set MEASUREGPT_VERSION, and recreate the container. Keep the previous tag until the checks pass.
Token change. Do these steps: change MCP_SERVICE_TOKEN, recreate the container, and update the CHOIR configuration.
Kubernetes. See k8s/ in the package. It uses ClusterIP only. It has no public LoadBalancer by default.
More detail on the architecture. See /architecture. It has the system map, the installation steps, and the patterns.

Short checklist before you start the service

The written institutional agreement is on file. The CHOIR open-source terms do not apply.
The image checksum and the image tag agree with MEASUREGPT_VERSION.
The service is not on the public internet.
MCP_AUTH_MODE=token, or network as a deliberate decision.
The health route gives profile: hospital and ready: true.
CHOIR can call tools/list and one example interpret_score.

Related: Architecture · Home · source docs/INSTALL-HOSPITAL.md