MCP Token Scoping: What a Read-Only Apple Health Token Should and Should Not Reach

Handing an agent your health data is a permissions question, not a features question. Get the scope right and a read-only grant stays read-only no matter what the agent hallucinates. Get it wrong and your "read-only" token quietly unlocks more than you think.

By MetricBridge · Published 28 October 2026 · ~8 min read

AI-assisted, human reviewed. How we use AI

The quick answer

A read-only Apple Health token should reach exactly one destination, one data folder, and a set of tools that can only read. It should return daily summaries, not individual raw samples. It should be revocable in one step. And it should never reach the write path back into Apple Health, workout GPS routes, medication records, a network, or anyone else's data. If your token is a single long-lived string shared across your phone, your laptop and a hosted agent, it is not scoped, it is just unrevocable.

This matters more for health data than for most APIs. The export is not a stream you rotate like an API key; it is a durable file in a folder that syncs to every device you own. The token is the lock. The interesting question is what is behind it.

Two different secrets people both call "the token"

Most confusion starts here. In a health-data agent setup there are two separate credentials doing two separate jobs, and they fail in different ways.

• The pairing secret gates the server. In MetricBridge you turn on Agent pairing in the app and set PAIRING_SECRET in the server config. Without a match, every data tool answers "Locked" rather than returning an empty result. That distinction is deliberate: an empty result looks like "no data today", while "Locked" tells you the credential is the problem.
• The delivery token authenticates the export. If you point the app at a webhook you run, the request carries your ingest token and, when you set one, an HMAC-SHA256 signature over the request id, timestamp and raw body. Every configured destination keeps a send history, so you can see what actually left the phone.

One gates the reading, the other gates the sending. Scope both, or the tighter one is decoration.

What a read-only health token should reach

Four things, and you can hold any implementation to all four.

1. One destination. The folder or endpoint you chose. Not your whole iCloud account, not your whole home directory. The server takes a HEALTH_DATA_DIR and reads that path, nothing wider.
2. Read-only tools, and only read-only tools. MetricBridge ships 16 tools and 22 prompts over 194 metrics, and every one of the 16 is read-only. Useful examples: get_mcp_status to prove the connection, list_metrics to see what is available, get_health_metrics for values over a date range, get_trends and compare_periods for week-over-week math, and get_freshness to learn how current the export is.
3. Daily values and summaries, not raw samples. This is a scoping decision disguised as a data-shape decision. An agent reasoning about your sleep trend does not need every heartbeat sample; it needs one value per day plus a summary per sleep session, and that is what the export contains. Granularity is a permission too.
4. One step to revoke. If rotation is a support ticket, the scope is theoretical.

What it must never reach

A read-only token has no business touching any of these, and a system that offers them under the same credential has not scoped anything.

• The write path into Apple Health. The iOS app requests read-only HealthKit permission and never writes back. No tool can log a meal, a workout or a dose. If an agent could write, a prompt injection becomes a data-integrity problem, not just a privacy one.
• GPS routes and workout locations. A route leaves the phone only as a GPX file you share yourself. It is never written to an export destination, and the server reads no route file.
• Medication records from Apple Health. The app does not read them, so no token can leak them. A medication reaches an agent only if you typed it into an event or your profile.
• Individual raw samples. Agents get daily values, one summary per workout and per sleep session, and the current hourly window.
• Any network hop you did not choose. The MCP server is zero-dependency and makes zero network requests. Your data does not pass through a vendor, and there is no account to compromise.
• Anyone else's data. One export folder, one person. There is no multi-tenant view to escalate into.

Sensitive families follow the same rule. Reproductive health, sexual activity and alcohol are off by default in the app and appear in the export only if you switch on sensitive categories yourself. A token you hand an agent should never be the thing that decides whether those are included.

The five-question scope test

Before you paste a config, run the token through this. It works for any health-data agent, not just ours.

1. What does it unlock? Name the exact folder or endpoint. If the answer is a platform, it is too wide.
2. Can it change anything? Read-only means no writes anywhere, including the source health store.
3. How granular is what it returns? Daily summaries and session summaries are the right shape. Raw samples are not.
4. How do I revoke it? One action, and it must cut off every consumer of the old credential, not just new ones.
5. What happens without it? A good system fails closed with an explicit "Locked", never by quietly serving stale or empty data.

How this works in practice

Configuring the MCP server takes two values, and the pairing line is the scoping one.

{
  "mcpServers": {
    "health-export": {
      "command": "node",
      "args": ["/Users/you/.health-export-mcp/server.mjs"],
      "env": {
        "HEALTH_DATA_DIR": "/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents",
        "PAIRING_SECRET": "the-code-from-the-app"
      }
    }
  }
}

Three details do the real scoping work:

• The app writes only a SHA-256 hash of the pairing code beside your data, never the code itself. Your export folder never contains the secret that unlocks it.
• Regenerating the code cuts off every agent still using the old one as soon as the new pairing file reaches your computer. That is the one-step revocation, and it is why you should not reuse one code across unrelated agents.
• Pairing covers the iCloud Drive and folder exports. It does not cover a copy saved by the local-network receiver, so if you use that route, treat the files as the boundary and turn on encryption.

One more habit: check freshness before you trust an answer. get_freshness reports how current the export is. A stale read that looks live is the failure mode that leads people to draw conclusions from last week's numbers.

Provenance answers the question a token cannot

A token says what can be read. It says nothing about whether a number was real. Every computed answer in the app renders as a provenance card, so you check the working instead of taking the prose on faith.

That strip is the shape to insist on: the number, the samples, the date range, the computation and the source. If an agent hands you a health number with none of those, the token scope is the least of your problems.

Write-back is a separate product decision

Some agents can log a meal or a workout back into Apple Health. That is a different tool with a different risk class: once an agent can write, a prompt injection stops being a privacy incident and becomes a data-integrity one. Keep your read grant read-only, and make any write path a separately-scoped thing you opt into.

Frequently asked questions

Can a read-only Apple Health token write to Apple Health?

It should not be able to, and it should not need to. A read-only token exists to let an agent ask questions about data already recorded. The MetricBridge iOS app requests read-only HealthKit permission and never writes back, and all 16 MCP tools are read-only, so there is no write path for a token to unlock.

What is the difference between the pairing secret and the delivery token?

They guard different legs of the trip. The pairing secret gates the MCP server, so a local agent cannot read your export folder without the current code. A delivery token authenticates what the iOS app sends to a destination you configured, such as a webhook, and each destination keeps a send history.

How do I revoke an agent's access?

Regenerate the pairing code in the app. The app writes only a SHA-256 hash of the code beside your data, never the code itself, and every agent still using the old code is cut off as soon as the new pairing file reaches your computer. Rotate a webhook token the same way, from the destination's settings.

Does pairing protect the exported files themselves?

No, and this is the part most people get wrong. Pairing protects the server, not the files. Anyone who can open your export folder can read the JSON directly, unless you turn on export encryption in the app.

Should one token cover every agent and every destination?

No. Scope one token per destination and per agent, so revoking one does not touch the others. A single long-lived token shared across a phone, a laptop and a hosted agent is the most common way a read-only grant turns into an unbounded one.

Related reading

• → Connect Apple Health to Claude (and any MCP agent): step by step
• → Apple Health data privacy with AI agents: what stays local, what leaves
• → The MCP server: all 16 tools, 22 prompts and every client config
• → The webhook contract: token, signature and the send history
• → Where your data goes when you ask in the app (on-device AI, no cloud)

MetricBridge is a general-wellness app, not a regulated medical device. It describes and computes from your own data; it does not diagnose, detect, treat or monitor any condition. Wellness information, not medical advice.