apeiron-mcp

An MCP server exposing client health data from the Apeiron backend (https://api.apeiron.life). Tool surface is intentionally consolidated by data shape (time-series vitals, periodic assessments, unstructured text, derived aggregates) rather than by raw domain, to keep LLM tool-selection unambiguous.

Tools

¹ Uses the …-day variant (GET /activity_feed/sleep-analytics-day, GET /activity_feed/exercise-analytics-day) when the requested window is a single day.

See Endpoint mapping for the parameters sent to each endpoint and the filters that are applied server-side vs. locally.

All tools return the envelope:

{
  "client_id": "...",
  "domain": "...",
  "period": {"start": "...", "end": "..."},
  "data": [],
  "unit_system": "metric",
  "last_synced_at": "...",
  "source": "apeiron-api",
  "notes": ["..."]
}

• source is "apeiron-api" for live data and "stub" when no credentials are configured.

• notes is only present when there is something to explain: a filter the server could not apply, a retried request, or an argument the API ignores.

• data carries the API payload as returned by the backend — the server does not reshape it into an invented schema, so field names and units (weight_lbs, height_inch, …) are the backend's.

• client_id is the Apeiron person_id and must be numeric whenever credentials are configured.

Related MCP server: carechronicle-mcp

Install & run

pip install -e .
apeiron-mcp                                # stdio (default)
MCP_TRANSPORT=streamable-http apeiron-mcp  # HTTP on http://127.0.0.1:8000/mcp

The transport is selected with MCP_TRANSPORT; see Configuration for the bind address, port and other options.

Register with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "apeiron": {
      "command": "apeiron-mcp"
    }
  }
}

Run with Docker

The image is host-agnostic: it defaults to the network-friendly streamable-http transport so it can run as a long-lived service, and it can also be driven over stdio by a local MCP client.

Build

docker build -t apeiron-mcp:0.1.0 .

Run as an HTTP service (recommended for deployment)

# 8000 is taken by apeiron-ml's research-api on the shared EC2 -> publish on 8001.
docker run -d --name apeiron-mcp \
  -p 8001:8000 \
  -e APEIRON_ACCESS_TOKEN="$APEIRON_ACCESS_TOKEN" \
  --restart unless-stopped \
  apeiron-mcp:0.1.0

The endpoint is then http://localhost:8001/mcp. Verify it:

curl -i -X POST http://localhost:8001/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Prefer a plain-JSON reply (easier to script against)? Add -e MCP_JSON_RESPONSE=true.

Run over stdio (for a local MCP client)

-i keeps stdin attached and the image writes all logs to stderr, so stdout stays a clean JSON-RPC stream:

docker run -i --rm -e MCP_TRANSPORT=stdio apeiron-mcp:0.1.0

Point a client at it with:

{
  "mcpServers": {
    "apeiron": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "apeiron-mcp:0.1.0"],
      "env": { "APEIRON_ACCESS_TOKEN": "..." }
    }
  }
}

With Docker Compose

cp .env.example .env      # then edit APEIRON_ACCESS_TOKEN
docker compose up -d --build
docker compose logs -f

The apeiron-mcp service is started by default; a stdio service lives behind a profile (add -T when running from a script or CI, where no TTY is attached):

docker compose --profile stdio run --rm apeiron-mcp-stdio

The container runs as a non-root user (uid/gid 10001) with a read-only root filesystem, all Linux capabilities dropped and a built-in HEALTHCHECK (TCP probe on the configured port). Host port mapping is controlled by MCP_HOST_PORT (host side, default 8001) and MCP_PORT (container side, default 8000). MCP publishes on 8001 because apeiron-ml's research-api already binds 8000 on the shared EC2 instance.

Configuration

Backend credentials:

With none of APEIRON_ACCESS_TOKEN / APEIRON_EMAIL+APEIRON_PASSWORD set, the tools return labelled stub data ("source": "stub") instead of API results, so the demos keep working offline.

Server behaviour:

Security note: binding to a non-loopback address (0.0.0.0, required in a container) disables the SDK's Host/Origin validation so the service is reachable — the server logs a warning when this happens. When you expose the service beyond a trusted network, set MCP_ALLOWED_HOSTS (e.g. apeiron.example.com,apeiron.example.com:* — list both forms, because entries are matched against the Host header including its port) and terminate TLS at a reverse proxy. The server itself ships no authentication layer, so do not publish the port directly to the internet.

CI/CD

Two GitHub Actions workflows mirror the apeiron-ml pipeline: they build the image in CI, push it to AWS ECR, and deploy a chosen tag to the staging/production host.

Image tags

Tags are immutable, so each build pushes a fresh versioned tag rather than overwriting a moving latest. Deploy references an explicit tag.

Required repository secrets

Deploying

1. Provide a .env.docker in the home directory of the target host (the workflow runs docker run --env-file .env.docker). Start from the committed template and fill in the real values:

   cp .env.example ~/.env.docker   # then edit APEIRON_ACCESS_TOKEN etc.

   See Configuration for every variable.

2. Run the Deploy MCP workflow and pick the image tag and the environment. MCP is published on host port 8001 and the container always listens on 8000; 8000 is left alone because apeiron-ml's research-api uses it.

3. The workflow restarts the container and fails loudly (with the last 50 log lines) if it exits during startup.

The ECR_REPOSITORY (phs/apeiron-mcp), AWS_REGION (us-west-2), CONTAINER_NAME (apeiron-mcp) and HOST_PORT (8001) values live in the env: block at the top of each workflow, so a different registry, region, container name or host port is a one-line change.

Exposing the service: the apeiron-ml EC2 security group only opens ports 8000 and 22, so 8001 is reachable on the host/VPC but not from the internet until an ingress rule for 8001 is added to the terraform security group (apeiron-ml/terraform_utils/research{,_staging}_env/ec2.tf). In the meantime reach it over an SSH/SSM tunnel or front it with a reverse proxy.

Authentication

Every read endpoint needs a bearer token; without one the API answers 401 {"message": "No authorization token found"}. Two ways to supply it:

1. Static token — set APEIRON_ACCESS_TOKEN. Mint one with the login endpoint:

   curl -s https://api.apeiron.life/people/login \
     -H 'Content-Type: application/json' \
     -d '{"email":"you@example.com","password":"secret","app":"dashboard"}'
   # -> {"token": "...", "person": {...}}

2. Email + password — set APEIRON_EMAIL and APEIRON_PASSWORD; the client calls POST /people/login on first use, caches the token, and re-authenticates once if a call comes back 401. To print a token for APEIRON_ACCESS_TOKEN:

   python -c "from apeiron_mcp.apeiron_client import fetch_token; \
              print(fetch_token('you@example.com', 'secret'))"

Endpoint mapping

Swagger spec: https://api.apeiron.life/_api.json (v13.0). The server only uses read (GET) endpoints; the validated dataset types are bio_marker, body_comp, cardiorespiratory, cognitive_health, lifestyle_assessment and physical_assessment.

Filters applied locally

Some tool arguments have no counterpart in the API, so they are applied to the response instead. When a filter matches nothing, the full response is returned and an entry is added to the envelope's notes field, so results are never silently emptied:

• get_exercise_data.activity_type — matched against activity-name fields (activity_type_shown, name, workout, …).

• get_cardio_metrics.metric — resting_hr, hrv, vo2max, blood_pressure and aerobic_capacity are matched against metric/group names (so hrv also matches "heart rate variability").

• get_notes.author — matched against author/role/source fields.

• Date bounds on /datasets/{type} (which takes no date parameter) and on /message/.

• get_chat_history.limit — the most recent N messages are returned.

• get_trends no longer filters by metric: GET /trend_statistics/summary takes only person_id and returns the person's most significant trend changes.

• get_chat_history.conversation_id is ignored: Apeiron keeps a single message thread per client.

Everything else (person_id, group, dates on range-aware endpoints) is sent to the API as query parameters.

Development

pip install -e .
python examples/poc_walkthrough.py                        # all 11 tools, stub data
APEIRON_PERSON_ID=123 python examples/poc_walkthrough.py  # same calls, live data

The walkthrough prints the envelope's source and notes for every call, so it doubles as a wiring check: without credentials everything reports "source": "stub"; with credentials the same calls hit api.apeiron.life. Note that the MCP stdio client only forwards a safe subset of the environment (HOME, PATH, …), which is why the examples pass the APEIRON_* variables to the server process explicitly.

LLM agent chat UI

examples/agent_demo.py puts a small browser chat UI in front of the server: an LLM picks the MCP tools, every tool call is shown above the answer, and the reply streams in as it is written. Start the server over streamable HTTP, set one LLM key, then open http://127.0.0.1:8080:

MCP_TRANSPORT=streamable-http apeiron-mcp   # terminal 1
.venv/bin/pip install anthropic openai
OPENAI_API_KEY=... .venv/bin/python examples/agent_demo.py   # terminal 2 (or ANTHROPIC_API_KEY)

Failures (a bad API key, the server not running) are reported inline in the page instead of as a stack trace. MCP_URL overrides the MCP endpoint and AGENT_HOST / AGENT_PORT the UI bind address.

API failures (bad token, unknown person_id, transport error) surface as MCP tool errors carrying the failing method, path and HTTP status.