# Aidlab MCP

Connect your Aidlab wellness data to AI tools through the Model Context Protocol.

No invite or allowlist is required. The server is read-only and every request is limited to the Aidlab user who approved the connection.

## Endpoint

```text
https://my.aidlab.com/mcp
```

Transport: stateless Streamable HTTP. Stable MCP protocol: `2025-11-25`. Server version: `1.1.0`.

## Available tools

| Tool | Result |
| --- | --- |
| `aidlab_get_daily_summary` | One row per local day: steps, distance, calories, workout time, average and resting heart rate, HRV, respiration rate, SpO2, skin temperature, stress index, weight, and the night's sleep |
| `aidlab_list_measurements` | One metric as raw samples or hourly/daily aggregates |
| `aidlab_list_sleep` | Sleep-stage intervals |
| `aidlab_list_activities` | Recorded workout intervals |
| `aidlab_get_profile` | Language and timezone only |

Metrics: `steps`, `heart_rate`, `resting_heart_rate`, `hrv`, `respiration_rate`, `spo2`, `skin_temperature`, `stress`, `calories`, `distance`, `weight`, `vo2max`. New metrics extend this list; they don't add tools.

All tools are read-only and idempotent. Health-data tools require `data:read`; profile requires `profile:read`. The 1.0 tools `aidlab_list_steps`, `aidlab_list_heart_rate`, and `aidlab_list_hrv` still answer existing clients but are no longer listed; use `aidlab_list_measurements`.

See [`docs/tools.md`](docs/tools.md) for inputs, outputs, units, and missing-data behavior.

## Connect

Add this remote MCP URL in your AI client:

```text
https://my.aidlab.com/mcp
```

The client discovers Aidlab OAuth, opens Aidlab sign-in and consent, and stores the resulting credentials. Web clients identify themselves with a Client ID Metadata Document (CIMD); native and CLI clients with a loopback redirect can register dynamically (DCR). No API key, manually created OAuth client, or pasted token is required.

### Codex CLI

```bash
codex mcp add aidlab --url https://my.aidlab.com/mcp
```

Codex starts Aidlab OAuth automatically. If authentication was skipped or revoked, run `codex mcp login aidlab --scopes data:read,profile:read`. Open `/mcp` to verify the connection. See [`examples/codex-config.toml`](examples/codex-config.toml) for the equivalent configuration.

### Claude and Claude Code

Add the remote URL as a custom connector. For a project configuration, copy [`examples/claude-code.mcp.json`](examples/claude-code.mcp.json); authentication is completed interactively.

### ChatGPT

Create a custom MCP connection with `https://my.aidlab.com/mcp` and follow the Aidlab login and consent flow.

### OpenAI Responses API

[`examples/openai-responses.mjs`](examples/openai-responses.mjs) is for server-side integrations that already manage OAuth credentials. Install the SDK with `npm install openai`, then set `OPENAI_API_KEY` and a short-lived `AIDLAB_TOKEN`. The example requires approval before every tool call; keep secrets in server-side configuration, never in browser code.

## Try it

```bash
npm run smoke
```

The public smoke test verifies OAuth discovery and the unauthenticated challenge without credentials. Maintainers can also set a short-lived OAuth `AIDLAB_TOKEN` to verify the authenticated MCP lifecycle and the exact tool surface.

Then ask:

- "How did I sleep this week? Compare it with my resting heart rate and HRV."
- "Show my heart rate yesterday, hour by hour, and mark my workouts."
- "How have my weight and daily steps changed over the last six months?"

`aidlab_list_measurements` reads up to 366 days of daily values per call, and up to 31 days of raw or hourly values. The other tools accept up to 31 days. Pages hold at most 200 records; when `has_more` is true, pass the returned `next` as the next `end_date`.

## Privacy and safety

- Tool inputs do not contain `owner_id`, `user_id`, or a general-purpose query field.
- `/mcp` accepts only one-hour OAuth access tokens bound to the MCP resource; the approving user and scopes are enforced by Aidlab's authorization layer.
- Outputs omit identity, contact details, source metadata, billing fields, and raw physiological signals.
- The AI client or API provider you choose receives the requested wellness results and a resource-bound access token so it can call Aidlab; review that provider's data controls before use.
- Results are wellness data, not medical diagnosis or treatment advice.

See [`SECURITY.md`](SECURITY.md) for vulnerability reporting, the [user guide](https://www.aidlab.com/developer/docs/mcp), Aidlab's [Privacy Policy](https://www.aidlab.com/privacy_policy), and [Terms](https://www.aidlab.com/terms).

## License

The configuration examples and smoke client in this repository are MIT licensed. The hosted Aidlab service and its backend remain proprietary and are governed by Aidlab's terms.