How to Connect HealthOS to Claude Code

How do I connect HealthOS to Claude Code?

Connect HealthOS to Claude Code by creating a personal token in the iPhone app, then adding an MCP server with one command. The endpoint is https://api.healthosx.com/api/mcp and the only extra piece is an Authorization: Bearer ***… header. That token carries the read and write scopes you picked, so Claude Code sees and writes only what you allowed. This is not the claude.ai OAuth connector.

The MCP endpoint accepts the same personal token you create in Settings → Account → API access. It needs one URL and one bearer header. No OAuth step.

Create the token in the iPhone app

Tokens are not created on the web yet. Open the iPhone app, go to Settings → Account → API access, and create a token. The token starts hos_…. That screen lets you pick scopes. Read access is separate from write access per family, so you can allow reading blood tests without allowing DNA writes. Keep the token private. It is a bearer header, not a username and password. Do not put it in a git repository or a team config file.

The exact Claude Code command

Run this command and replace ***… with the full token:

claude mcp add --transport http healthos https://api.healthosx.com/api/mcp --header "Authorization: Bearer ***…"

For clients configured with an mcp.json, use the header form:

{"mcpServers":{"healthos":{"url":"https://api.healthosx.com/api/mcp","headers":{"Authorization":"Bearer hos_…"}}}}

The name healthos is the local server name. You can call it anything. After adding, run claude mcp list to confirm it is present. Cursor and similar MCP clients that accept a URL with headers can use the same JSON. The domain is healthosx.com, not healthos.com.

What the token can read and write

The token scopes cover Apple Health activity, vitals, sleep, workouts, the raw archive, glucose, meals, blood tests, scores, manual logs, goals, profile and DNA. Write scopes exist per family. If the token lacks a scope, the tool call fails rather than quietly doing less. The live MCP server returns its tool list; at the moment that is 225 tools. You do not need to add them by hand.

• Rate limit: 60 calls per minute per token.
• Daily limit: 2,000 tool calls per day UTC per connection/token.
• Destructive, payment and sharing tools refuse to run without confirm: true, so the agent has to ask first.

A read-only setup is valid. Tick the read scopes only and leave the write scopes off. Analysis tools still work, but logging tools are unavailable.

Claude Code is not the claude.ai connector

If you meant the Claude app, not Claude Code, this is a different route. Claude Code does not use the OAuth sign-in flow. It needs the bearer header above. The claude.ai route uses the custom connector URL https://mcp.healthosx.com/mcp, where you sign in, tick what Claude may see, and approve. Use that inside claude.ai, the desktop app or the mobile app. Do not go looking for a tile in the Claude connector directory. Add it as a custom connector.

Why your data looks stale

Apple Health and glucose data come from the iPhone app. The API response includes meta.phone_last_sync_at for health data. If Claude Code answers with a number that looks old, check that field first. Open the iPhone app and let it sync before you ask again. The assistant is reading your data, not population averages. Wellness information is not a medical device, and an assistant can be wrong. Check anything important with a doctor.

After it connects, ask something specific like "Compare my last two blood tests" or "Which meal this week sent my glucose highest?" Then when you want the claude.ai custom connector instead, or a step-by-step setup with what you can ask, go to HealthOS connectors. For Claude Code itself, the token you made in the iPhone app is the whole setup.