MetaTwin Physiology MCP

English | 简体中文

A read-only Model Context Protocol server for personal physiology and health data: blood glucose, blood ketones, device heart rate, weight, image-based body-fat percentage and BMI.

It is a stateless JSON Streamable HTTP MCP server (path /mcp) protected by OAuth 2.1 Authorization Code + PKCE with Dynamic Client Registration (RFC 7591). End users connect an MCP-compatible client to the hosted service, sign in once in a browser, and grant the health:read:self scope. The server is read-only — there is no tool that creates, modifies or deletes data.

The public hosted service and the organization behind it: replace this paragraph with the official service URL and operator name before publishing.

Capabilities

A parallel set of admin_user_physiology_* tools exists for approved administrators (health:read:all scope plus a server-side double allow-list); they are invisible to ordinary users.

Fixed metric IDs

blood_glucose, blood_ketone, heart_rate_device, weight_record, weight_body_fat, body_bmi

Every raw record carries a quality flag (valid / excluded) with a reason, and statistics report raw counts, valid counts and per-reason exclusions.

Related MCP server: withings-mcp

Connecting as a user

Point any MCP client supporting Streamable HTTP + OAuth at the hosted endpoint (the URL always ends with /mcp):

{
  "mcpServers": {
    "metatwin-physiology": {
      "url": "https://mcp.metatwin.top/mcp",
      "transport": "streamable-http",
      "oauth": { "enabled": true, "scopes": ["health:read:self"] }
    }
  }
}

The client discovers the authorization server via standard .well-known metadata, performs DCR + PKCE, and the user completes one browser login (mobile/email verification code or password) and a consent screen. RFC 9068 JWT access tokens are short-lived; rotating refresh tokens enable silent renewal.

Security model

This server is the edge only; it holds no database and forwards no OAuth tokens to the data backend.

• Least privilege. Ordinary tokens carry only health:read:self; the accessible account is forced to the token subject — a caller can never name another account. Cross-account access requires the separate health:read:all scope and a double server-side allow-list (client ID and user ID).

• Tokens stay at the edge. Calls to the private data backend are authenticated with one-shot, HMAC-signed assertions (30–60 s lifetime, unique jti with Redis-backed replay protection) bound to method, path and the SHA-256 hash of the exact request body.

• Every request re-verified. JWT signature, issuer, audience and claims are checked, then RFC 7662 introspection confirms the token is still active with matching scopes — revocation is immediate. The backend independently re-checks identity, role, scope and live account state on every call. Any verification failure is rejected (fail-closed).

• Safe outputs. Error codes come from a fixed whitelist; backend responses are validated against JSON Schemas and malformed data yields a generic 502. Page cursors are HMAC-signed and cannot be forged.

• Minimal audit logs. Only actor type/ID, client ID, operation, target account and timestamps — never health values or token contents.

Self-hosting

The server requires a compatible OAuth 2.1 authorization server (issuing RS256 at+jwt tokens with RFC 9068 claims and an RFC 7662 introspection endpoint) and a private backend implementing the internal physiology HTTP contract. It is published primarily as the reference implementation behind the hosted service.

Configuration

All configuration is via environment variables; the server refuses to start on invalid or insecure values.

Terminate public HTTPS at a reverse proxy routing /mcp and /.well-known/oauth-protected-resource/mcp, and keep the backend URL private. Never commit real .env files.

Run locally

Requires Python 3.11+.

python3 -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e '.[test]'
cp .env.example .env          # then edit .env
set -a && . ./.env && set +a  # bash only
python -m metatwin_mcp

Container

docker build -t metatwin-physiology-mcp .
docker run --env-file .env -p 8000:8000 metatwin-physiology-mcp

Tests

pytest -q

License

Apache License 2.0