Architecture

System map

What runs in one process

One server.ts process holds five parts: the Mastra MCP server, the optional psychometrist agent, the deterministic interpretation engine, the host for the R and Python analysis, and the Next.js web UI. The UI and the deterministic /api routes call /mcp through the loopback interface. Analysis jobs enter through the Mastra MCP tools. They do not enter through a separate Next.js route.

Structure

The structure in short

A single Node process runs one Mastra instance. The instance gives four psychometric tools. It also gives the additional profile tools and analysis tools. It gives these tools through a streamable HTTP MCP server and an optional chat agent. A Next.js application in the same process calls that MCP server through the loopback interface. Thus the demo uses the same contract as an external client. You submit a multivariate recipe through the Mastra analysis tools. The recipe then runs as an asynchronous Python or R worker job on the same host.

Institutional deployment

Behind the firewall

Usually, a hospital or a health system cannot send a clinical workflow to a public SaaS MCP server. Thus MeasureGPT is designed to run inside the SHC perimeter, behind CHOIR. It uses public psychometric facts only. It does not store patient data. It does not use an external database. The Node hosting can move to a different platform. The service has no public internet access.

What stays local

• All score calculations and cutoffs. The code in src/engine/interpret.ts calculates them from the supplied corpus.
• The citations and the source locators. The tools return them as structured JSON for an audit.
• The analysis. After submit_analysis, a pain-cluster recipe runs as a Python or R worker on the same host. Redis is an optional shared job record only.
• The request path. A single-score request contains one measure and one number. The service is educational. It does not store patient records.

What can leave the perimeter

• Nothing is necessary. The MCP tools, the REST interpret route, and the form UI need no outbound traffic.
• There is no public endpoint. An institutional deployment keeps MeasureGPT behind CHOIR and the firewall. The MCP function is for CHOIR and approved SHC projects only.
• Model traffic is optional. It occurs only if you set a provider key for the CopilotKit chat. The chat uses the same tools. It adds a generative language layer only. Many sites keep the chat off.

The hospital package contains the Docker image, the MCP_AUTH_MODE setting, the CHOIR environment examples, and the installation checks. See On-prem deployment →

Runbook

How to install and start the service

These six steps go from an empty host to institutional clients. If the operators must not use the full monorepo, use the Docker package in On-prem deployment. These details agree with README.md, ARCHITECTURE.md, and docs/INSTALL-HOSPITAL.md.

1. Provision a host on the trusted network

   Use a virtual machine, a bare-metal node, or a container on your institutional network. The service is a plain Node process. It does not use APIs that are specific to Vercel or to one cloud platform. Use Node 24 or later, because the service uses native TypeScript type stripping. The default listen port is 3583. To change the port, set PORT.

2. Install, build, and start

   If the operators must not use the full monorepo, use the hospital Docker profile:

   # Use the offline image bundle, or run this command:
   docker compose -f docker-compose.hospital.yml --env-file .env.hospital up --build -d
   # The service is then at http://localhost:3583
   # The MCP server is at /mcp
   # For authentication, set MCP_AUTH_MODE=token or MCP_AUTH_MODE=network
   # For the detail, see docs/INSTALL-HOSPITAL.md

   If you use a full clone, use these commands. The clone has the public demo defaults. Clerk is optional on a local host.

   npm install
   npm run build
   npm start
   # The service is then at http://localhost:3583
   # The MCP server is at /mcp

   server.ts is the production entry point. It sends /mcp to the Mastra MCP server. It sends all other requests to Next.js. Warning: do not use next start alone. next start cannot serve the streamable HTTP MCP transport.

3. Put CHOIR and institutional controls in front

   Install MeasureGPT on a private interface. Put CHOIR and the institutional edge in front of it. Terminate HTTPS on your reverse proxy. nginx, HAProxy, and F5 are examples. Then send only private traffic to the Node process. The service should not be accessible from the internet. CHOIR and the existing SHC controls select the users and the internal systems that can use MeasureGPT.

4. Keep the MCP endpoint internal-only

   Inbound traffic: the proxy must accept only traffic from CHOIR, an SHC application, a VPN, or a trusted subnet. The proxy sends this traffic to Node for the web UI, /api/*, and /mcp. Do not publish /mcp or the web UI to the public internet. A health check can call GET /api/health from inside the trusted network.
   Local runtime: if you enable the multivariate analysis recipes, install Python 3 and R. The MCP analysis tools start these workers on the same host.
   Outbound traffic (optional): the host needs outbound traffic only if you enable natural-language chat. The host then needs a connection to your model provider. Anthropic is an example. The deterministic core does not connect to the internet. The catalog, the bands, the cutoffs, and the citations are local files in the process.

5. Point CHOIR and internal clients at /mcp

   Inside the firewall, configure CHOIR and the approved SHC projects with your internal base URL. An example is https://measuregpt.your-hospital.internal/mcp. In token mode, set MEASUREGPT_MCP_URL=…/mcp and MEASUREGPT_MCP_AUTHORIZATION="Bearer …". In network mode, set the URL only. The full examples are in docs/INSTALL-HOSPITAL.md. The endpoint has the same psychometric tools and analysis tools as the MeasureGPT web UI. Use the endpoint for CHOIR and approved SHC systems only.

6. Decide if you enable chat (optional)

   For a facts-only service, do not set OPENROUTER_API_KEY. The form, the REST routes, and the MCP server then operate fully. The on-page assistant stays inactive. If your policy permits outbound model traffic, set the key. You can also set PSYCHOMETRIST_MODEL. Chat is an addition. Interpretation never depends on it.

Environment

Reverse-proxy example

# Terminate TLS at the edge. Send the traffic to the Node process on the private network.
# This example uses nginx syntax. Change it for your platform.
#
# location / {
#   proxy_pass http://127.0.0.1:3583;
#   proxy_http_version 1.1;
#   proxy_set_header Host $host;
#   proxy_set_header X-Forwarded-Proto https;
# }
# # /mcp uses streamable HTTP. Do not buffer the body. Permit long streams.
# location /mcp {
#   proxy_pass http://127.0.0.1:3583;
#   proxy_buffering off;
#   proxy_read_timeout 3600s;
# }

HTTP surface

Routes to expose internally

Checks after installation

curl -sS https://measuregpt.your-hospital.internal/api/health
curl -sS https://measuregpt.your-hospital.internal/api/measures | head
curl -sS -X POST https://measuregpt.your-hospital.internal/api/interpret \
  -H 'content-type: application/json' \
  -d '{"measure":"PHQ-9","score":18}'

Why this structure

Patterns you can use again (from ARCHITECTURE.md)

1. The MCP server is internal only. MeasureGPT operates behind CHOIR and the SHC firewall. /mcp supports CHOIR and the approved internal projects. It does not support public clients.
2. There is one MCP contract. Streamable HTTP at /mcp gives the psychometric tools, the profile tools, and the analysis tools to trusted internal clients.
3. The tools are defined one time. The agent and the MCP server use the same createTool sets, which include the analysis tools. Thus the contracts cannot become different.
4. The service uses its own contract. The web application is a true MCP client that calls the loopback interface. Thus a demo that operates correctly shows that the external contract also operates correctly.
5. A verified corpus is behind the model. Generative language is optional. The facts and the calculations are deterministic and have provenance.
6. The payloads are identical. The UI cards show the same tool JSON that an external client receives.
7. The calculation stays on the same host. The analysis tools submit asynchronous jobs to the local host. The host validates the inputs. It then starts the Python or R recipe worker.
8. The AI layer is optional. Without a model key, the core service still operates fully.
9. Tests protect the boundary. Pinned MCP schema snapshots and drift tests protect the consumers and the offline benchmark.
10. The evaluation uses the source of truth. The benchmark keys come from the corpus.
11. The deployment can move platform. The service is plain Node. It runs in the cloud today. It can run in a datacenter later without a rewrite.

More design notes are in ARCHITECTURE.md, docs/corpus-curation.md, and docs/service-contract-benchmark.md.