# Aidlab MCP

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

Public preview: 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`.

## Available tools

| Tool | Result |
| --- | --- |
| `aidlab_get_daily_summary` | Daily steps, average heart rate, average HRV, sleep, and activity duration |
| `aidlab_list_steps` | Step measurements |
| `aidlab_list_heart_rate` | Heart rate measurements in BPM |
| `aidlab_list_hrv` | HRV measurements in milliseconds |
| `aidlab_list_sleep` | Sleep-stage intervals |
| `aidlab_list_activities` | Recorded workout intervals |
| `aidlab_get_profile` | Language and timezone only |

All tools are read-only and idempotent. Health-data tools require `data:read`; profile requires `profile:read`.

## Connect

Add this remote MCP URL in your AI client:

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

The client discovers Aidlab OAuth, identifies itself with a Client ID Metadata Document (CIMD) or registers a public client dynamically (DCR), opens Aidlab sign-in and consent, and stores the resulting credentials. No API key, manually created OAuth client, pasted token, invite, or allowlist 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.

### ChatGPT desktop and web

Create a custom MCP connection and enter `https://my.aidlab.com/mcp`. ChatGPT follows the same Aidlab login and consent flow.

### 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.

### OpenAI Responses API

The server-side example in [`examples/openai-responses.mjs`](examples/openai-responses.mjs) is for advanced integrations that already manage OAuth credentials. It requires approval before every health-data tool call; secrets belong in server-side configuration, never browser code.

## Try it

```bash
npm run smoke
```

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

Then ask:

- “Summarize my sleep and activity for the last seven days. Mention missing data.”
- “Compare my daily steps and average heart rate this week with the previous week.”
- “List yesterday's workouts and sleep stages. Do not give medical advice.”

Each date-range call accepts at most 31 days. Raw-list tools return at most 200 records per page; use the returned `next` cursor as the next `end_date` when `has_more` is true.

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

## 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, plus 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.