How to connect Apple Health to VS Code Copilot in agent mode

What do you get?

VS Code Copilot can read selected Apple Health data through your local Syncky agent and request permitted write-back with source and undo. This registration does not disable syncky_send or syncky_ack; review tool requests deliberately. Free during launch; plans are coming later. See launch access and pricing.

Client health-data envelopes are sealed end to end. Relay sees delivery metadata and plaintext hub notices, but no health values. The local agent keeps plaintext JSON in its inbox; your chosen model sees what the agent supplies. iOS decides background timing and Health reads need an unlocked iPhone. Data can be hours old and writes wait for sync; undelivered envelopes leave Relay on acknowledgment or expiry, at most 7 days.

What do you need before setup?

Use VS Code Copilot locally on the machine holding the agent home, Syncky Health on your iPhone, npm and Node.js 22.15 or newer available to the client process. The first npm run may download the agent. Choose your data and model deliberately. Package availability and acceptance by your installed client remain prerequisites.

Use a local project folder with Copilot available in VS Code. Microsoft's MCP configuration reference backs .vscode/mcp.json, the servers wrapper and local stdio fields. Its current setup guide describes this VS Code format as a compatibility destination, deprecated in the guided add-server flow. Eligible entries are forwarded to Copilot sessions; Copilot does not read this file directly, and entries requiring interactive input are excluded. This example has no interactive inputs. Sources were checked on November 3, 2026.

Setup, receiver and MCP must use the same paired SYNCKY_AGENT_HOME and matching saved relay; agent setup explains relay selection for each app build.

How do you set up VS Code Copilot?

1. Check the runtime and initialize only a fresh home:

   npx -y @syncky/agent selftest
   npx -y @syncky/agent init --name "My agent"
   

   Reuse an existing initialized home instead of initializing again.

2. Request a private QR and code:

   npx -y @syncky/agent pair
   

   Pair your iPhone: scan in Syncky Health and pick the code on the iPhone. Scanning alone does not confirm trust. Select read types, allowed write types and Health permissions deliberately. Keep pairing credentials, invites and home files out of chat and logs. Let an existing receiver collect the proof; otherwise wait for it after the code pick:

   npx -y @syncky/agent wait --timeout 600
   

3. For ongoing receipt, deliberately start:

   npx -y @syncky/agent receive
   

   Keep one receiver per home and reuse an existing receiver. For on-demand use, run npx -y @syncky/agent receive --once when you want updates. MCP reads the agent's inbox files and neither pairs nor starts a receiver. Services and schedules require a separate choice.

4. Review your local project and merge this server into workspace .vscode/mcp.json, preserving other servers:

   {"servers":{"syncky":{"type":"stdio","command":"npx","args":["-y","@syncky/agent","mcp"]}}}
   

   This file uses servers, not the portable configuration's mcpServers. Local stdio runs on the machine executing the command; with this local project it must have your paired agent home and runtime. The default home is ~/.syncky-agent. A custom home can use env.SYNCKY_AGENT_HOME in the server entry, with the absolute path of the same initialized/paired home used by the receiver.

5. Review the configuration before trusting the workspace. Microsoft's server management guide says Restricted Mode prevents workspace servers from starting; a trusted workspace can start them without a separate MCP trust prompt. Run MCP: List Servers, select syncky and use Start Server, or Restart Server after edits; stop and start if restart is unavailable. Show Output helps inspect startup errors.

6. Open a Copilot agent session. In current Copilot sessions, Chat: Open Customizations → Tools controls available tools; the Local harness uses Configure Tools in the chat input. Select the needed read tools and leave syncky_send and syncky_ack unselected for the first check. This is client tool selection, separate from the JSON registration. Select Manual permissions and review approval settings; approval behavior depends on policy and auto-approval choices. Run the scope-only prompt below.

   The canonical npm command is npx -y @syncky/agent mcp. A generic alternative for compatible clients is the matching release's checksum-verified syncky-health.mcpb; verify its .sha256 sidecar and SHA256SUMS from releases before importing. Node.js is still required. Checksums detect damage, not a compromised release; local packaging tests do not establish client acceptance. This guide uses JSON and makes no VS Code MCPB import claim.

What can VS Code Copilot read and write?

The MCP server offers five tools. syncky_status shows pairing, scope and relay progress from local state. syncky_inbox returns what the iPhone sent, as raw JSON kept 30 days on your computer. syncky_skill returns the signed instructions that describe every message format. syncky_send sends a message to the iPhone: a Health write, applied at the next sync when the owner has allowed writing for that type and iOS Health permits it, or a sync report or access request, which the owner approves on the phone. syncky_ack marks inbox entries as handled. Status, inbox and skill only read; send and ack change things. An empty result is not a measured zero. This registration does not disable syncky_send or syncky_ack.

The agent keeps what the iPhone sent as daily JSON files in its home (inbox/), prunes them after 30 days, and keeps the last 100 send receipts. There is no database and no built-in summaries: your AI agent reads the files it needs.

Every write to Apple Health, every sync report request and every request for more Health types is a message the agent sends to the iPhone. Writes apply only to the types the owner allowed for writing in the app; a sync report or more Health types need the owner's tap on the phone. The signed skill (syncky_skill) carries the exact formats and limits. A report arrives only after you Review and Confirm on the iPhone; you can decline instead.

Write only owner-requested entries or entries covered by explicit standing approval. A write is applied only when its type is in the app's write allowance, within the agent's write scope, and authorized by HealthKit (iOS write permission). Entries identify the requesting agent as their source. A queued or sent write is not an applied write: read the phone's result in the inbox after the next sync. To undo, use the iPhone's remove-written-entries control or have the agent send a delete command for its own entry. Follow the operator security rules.

How do you test the connection?

Ask VS Code Copilot: Use syncky_status to check the paired iPhone and its read/write scope. Do not read sample values or write anything. Expect a confirmed iPhone and its last reported scope. This reads local state without contacting Relay; it does not establish fresh delivery or complete data.

How do you troubleshoot this setup?

• Server cannot start: check Node.js, npm, command/args and the selected configuration scope, then use MCP: List Servers → Show Output. Use setup's selftest and restart the server after fixing the cause.
• Workspace trust blocks startup: review the repository and its MCP configuration before deciding whether to trust it. Do not bypass Restricted Mode for an unreviewed project.
• Server runs but tools are absent: check the selected harness, tool selection and whether the server is enabled. The compatibility format is forwarded only for eligible entries; interactive-input configurations need the vendor's separate guidance.
• Wrong or empty inbox: match the paired home and saved relay across setup, receiver and the process running MCP. This guide covers a local project; remote workspaces and browser sessions require their own execution/runtime/storage checks.
• Phone unconfirmed or data old: pick the phone's code and receive its proof. Check the receiver, selected categories, unlocked iPhone and Health permissions, then use Sync now. iOS decides later background timing.

What are the frequently asked questions?

Why does this file use servers instead of mcpServers?

Microsoft's workspace .vscode/mcp.json uses servers and explicit type:stdio. Its portable configuration uses a different wrapper. Use the schema for the file you actually edit.

Does this also connect a remote workspace to my local agent home?

This recipe targets a local project on the agent home's machine. Remote or container execution can place the server on a different host; copying a configuration does not transfer the agent home or install a runtime there.

Does the JSON make Copilot read-only?

No. Keep syncky_send and syncky_ack unselected for read-only work and review the active permissions policy. Client tool selection does not replace iPhone permissions.

Review Privacy and the public security policy before sharing data with a model.

Agent setup · MCP comparison · All guides.

How do I approve writes and requests for access or reports?

This registration is not a read-only setup. Keep tool approval enabled and never auto-allow syncky_send or syncky_ack; approve only intended writes, sync report requests and access requests. For read-only work, disable or deselect syncky_send and syncky_ack using the client's supported tool controls; the model then cannot write to Health, request a report or more access, or mark inbox entries as handled. The registration itself disables neither. A report request sends a report only after Review and Confirm on the phone. An access request is queued, then the owner confirms individual read/write choices on the phone; the reply arrives in the inbox and the next ordinary sync delivers effective scope. Request approval is separate from permission to write Health values. See access request guidance.