Connect an AI agent

lil · Claude, Claude Code, ChatGPT and other agents

Connect an AI agent to your lil health account, then ask it about your Health data: how you slept this week, how your resting heart rate has changed this year, or what workouts you did last month. The agent reads your data from lil health's servers, so it works wherever the agent runs, without your Mac.

You need a lil health account with your Health data in it: set up lil health on your iPhone first. When the agent asks you to sign in, use the same Apple ID or Google account.

The URL

Add one of these URLs to your agent as a remote MCP server (some agents call it a connector):

Every lil app: https://mcp.lil.tech. One connector for all of your lil apps. Use this one unless your agent should only ever see lil health.
lil health only: https://mcp.lil.tech/health.

lil health is the only lil app agents can read for now, so both read the same data. Their tools are named differently (see Tools).

The agent then opens a page in your browser: lil's for https://mcp.lil.tech, which lists every app the agent will read, or lil health's. Sign in with Apple or Google, check which agent is asking, and click Allow.

Claude

On claude.ai, or in the Claude app on your Mac or PC:

Open Customize › Connectors (Settings › Connectors in some versions).
Click Add, then Add custom connector.
Name it lil, paste https://mcp.lil.tech, and add it. (Or name it lil health, with lil health's URL.)
Click Connect, then sign in and allow Claude.

On a Team or Enterprise plan, an owner adds the connector in Organization settings › Connectors first. Then you find it in Customize › Connectors and click Connect.

Claude Code

In a terminal:

claude mcp add --transport http lil https://mcp.lil.tech

Then, in Claude Code, run /mcp, choose lil, and authenticate. Your browser opens lil's page. If you already have a server named lil, such as lil mcp, give this one another name.

For lil health only:

claude mcp add --transport http lil-health https://mcp.lil.tech/health

ChatGPT

ChatGPT can add a custom MCP server on some plans and workspaces, sometimes only in developer mode, and its menus change often. Today, on chatgpt.com:

Open Plugins, click the plus button, then Add custom MCP server.
Name it lil, paste https://mcp.lil.tech as the Server URL (or lil health's URL), and choose OAuth.
Create it, sign in and allow ChatGPT, then install the plugin.
In a chat, type @ and choose it by the name you gave it.

If your ChatGPT looks different, see OpenAI's guide to adding a custom MCP server.

Other agents

Any agent that supports remote MCP servers over Streamable HTTP, with OAuth sign-in, can connect: give it one of the URLs above. lil registers it when it connects, so there's no client ID or secret to enter.

Tools

Through https://mcp.lil.tech, each tool's name starts with its app's: health.summary, health.metric and so on. Through lil health's URL, the same tools have just their own names: summary, metric. Some agents show them their own way: Claude Code, for example, as mcp__lil__health_summary.

lil health's tools:

summary: start here. What lil health's Summary shows.
list_types: the kinds of Health data you have.
metric: a statistic over a day, week, month, six months or a year, such as steps or resting heart rate.
samples: individual records, a page at a time.
workouts, sleep and medications.
health_details: date of birth, sex, blood type and so on.
search: finds kinds of data by name, such as “blood pressure”.
sync_status: how fresh the data is.

Its card tools (see Cards):

list_cards: your cards, in Summary's order.
get_card: a card and its chart's numbers for a period.
preview_card: tries a card out without saving it, so the agent can check what it would show first.
create_card, update_card, delete_card and reorder_cards: change your cards, if you allowed it to when you connected it (see Cards).

What an agent can read

All of your lil health data. There's no way to share only some kinds of data, and an agent can't change or delete your Health data. Through https://mcp.lil.tech, the same goes for every app its page listed.
Your cards, which it can also change if you allowed it to (see Cards).
Summaries first: today's numbers, totals and averages over a day, week, month, six months or a year, workouts, sleep, medications and your health details. It reads individual records only when it asks for them, a page at a time.
Days in UTC unless the agent asks for your time zone, since lil health's servers don't know where you are. Tell your agent where you are if its days look off.
Agents send what they read to their provider, such as Anthropic or OpenAI, under the provider's own privacy policy.

lil health logs every time an agent reads your data or changes a card: what it asked for or which card it changed, and when, never the answers. You can see the log in lil health: on your Mac, Remote Access Log in Settings › Agents; on your iPhone, Recent Access in Settings › Connected Agents. It's kept for 90 days. The privacy policy has the details.

Cards

Cards are the charts on lil health's Summary. An agent can create cards for you, change what they show, their names, icons and colors, reorder them, and delete them, so you can ask it for a chart in your own words, such as “add a card with my heart rate while I sleep”. It can't change your Health data. Its changes sync to your Mac and iPhone, and you can edit or delete its cards yourself.

Some cards to ask for:

“Add a card with my body temperature as a line, over a month.”
“Add a card with my average heart rate while I'm asleep, each night.”
“Add a card with my HRV as dots over a month, with a moving average line.”
“Add a card with my heart rate in the 5 minutes before I fall asleep, each night.”
“Add a Morning Weight card: my first weigh-in before noon each day as dots, and a 7-day rolling average as a line.”

Agents are asked to try a card out before adding it, and new cards go at the end of your Summary. Ask for changes the same way, such as “show my sleeping heart rate over six months”.

When an agent connects, its page tells you whether it will be able to manage your cards as well as read your data. Agents usually ask for both, and you allow all of it or nothing. An agent you connected before, whose page didn't mention cards, can read them but not change them: to let it, remove it and connect it again.

Stop an agent

On your Mac: in lil health, open Settings › Agents. Click Revoke… next to an agent, or Turn Off Agent Access… to disconnect them all.
On your iPhone: in lil health, open Settings › Connected Agents. Swipe left on an agent to revoke it, or tap Turn Off Agent Access.

An agent connected through https://mcp.lil.tech is listed in every lil app it reads, marked All lil apps. Revoking it in any of them disconnects it from all of them. Turning off agent access in one app stops every agent reading that app, these included.

The agent is cut off at its next request. You can also remove it in the agent itself: in Claude, Customize › Connectors; in Claude Code, claude mcp remove with the name you gave it (such as lil or lil-health). Connecting again asks you to sign in and allow it again.

Agents on your Mac only

lil health for Mac can also let agents read the copy of your Health data on your Mac, through a local MCP server that the agent starts itself. It works offline, and nothing leaves your Mac except what the agent sends to its provider. It can manage your cards there too: lil health makes its changes, which sync to your other devices.

Install the lil command with lil health › Install Command Line Tool… (until it's installed, Settings › Agents has the same button, under Connect an Agent).
Signed in to lil health for Mac, open Settings › Agents and turn on “Allow access on this Mac” (“Allow command-line and agent access” in earlier versions). It's off until you do. It also lets the lil command, Shortcuts, Siri and Spotlight read your Health data and export it. The Access Log under it shows what read your data, and when.
Connect your agent to lil mcp: one local server for every lil app, with lil health's tools among them. Under Connect an Agent, Settings › Agents copies the commands with lil's full path, which works even when the agent is started from an app rather than a terminal.

In Claude Code:

claude mcp add --scope user lil -- lil mcp

Other agents take a local (stdio) server, with the argument mcp. Its command is lil's full path: /usr/local/bin/lil, or .local/bin/lil in your home folder, depending on where you installed it. Use the full path in Claude Code too if it can't find lil.

For lil health only, connect an agent to lil health mcp instead. Settings › Agents doesn't show this one. In Claude Code:

claude mcp add --scope user lil-health -- lil health mcp

Other agents take the same command, with the arguments health mcp. Its tools have just their own names, such as summary, as through lil health's URL (see Tools).

If something doesn't work

“No lil health account uses this Apple ID” (or Google account): sign in with the account you use in lil health on your iPhone. Accounts can't be created on the web.
The agent finds no data: open lil health on your iPhone and check that it has uploaded your Health data.

Anything else: hello@851.sh.

lil.tech · Privacy Policy