Skip to main content
Glama
Syncky Health

Syncky Health

Official

Syncky: open protocol, reference agent and reference server

Syncky Health sends the Apple Health data you choose from your iPhone to your own AI agent (local MCP server) or your own server. The AI agent route is end-to-end encrypted. Your agent and your server can both write entries back into Health once you allow writing on the iPhone.

Client health-data envelopes are end-to-end encrypted (HPKE Auth + ChaCha20-Poly1305): the relay sees delivery metadata and emits plaintext hub notices, but sees no health values. The app can also send straight to a server the user runs, with no relay at all. The user's agent or server receives plaintext, and a chosen model sees what the agent supplies.

Get Syncky Health on the App Store or visit syncky.app.

Install for an MCP client

Requires Node.js ≥22.15 and npm. The npm package embeds its runtime packages and has no runtime dependencies. Start the local stdio server with:

npx -y @syncky/agent mcp

For a client whose JSON configuration uses mcpServers:

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

Pair first using SKILL.md or the operator guide. Use the same SYNCKY_AGENT_HOME during setup and in the MCP client's environment when selecting a custom home. Grant only the read/write types you want to share. iOS background scheduling and an unlocked phone govern delivery; this is not a real-time feed.

Cursor

Add to Cursor

The default home is ~/.syncky-agent; add env.SYNCKY_AGENT_HOME only for a custom home, using the absolute path of the same initialized/paired home used by your receiver. JSON environment values do not expand $HOME or ~; use your actual path, including on Windows.

For manual configuration, merge this server into global ~/.cursor/mcp.json or project .cursor/mcp.json, preserving other servers:

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

Cursor enables MCP tool approval by default. Do not auto-allow syncky_send or syncky_ack; approve only writes, diagnostics requests and access requests you intend. Cursor's mcp.json cannot disable individual tools, so this recipe leaves both mutating tools available and is not a read-only setup. You can toggle the whole server in Customize. A write is applied only when its type is in the app write allowance (device-wide) or granted to this agent at pairing, within the agent's write scope, and authorized by HealthKit (iOS write permission). The operator guide's security rules still apply. A queued write is not an applied write. MCP does not start a receiver or complete pairing; keep one receiver per home.

Claude Desktop

For manual local setup, the official MCP tutorial, linked through Anthropic's local-server documentation, specifies Settings → Developer → Edit Config. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%\Claude\claude_desktop_config.json. Merge this server, preserving other entries:

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

Save, fully quit and restart Desktop to start the local stdio server. It runs under your user account. Inspect tools through + → Connectors or Local MCP servers settings; current Anthropic Help describes Settings → Desktop app → Manage Extensions and the older Settings → Extensions layout. Review permission requests and approve only intended operations. This registration does not disable writes. Use the same paired home and a separate receiver; MCP neither pairs nor starts one. For a custom home, the manual server entry can add env.SYNCKY_AGENT_HOME with an absolute paired-home path.

Anthropic documents custom .mcpb import under Extensions → Advanced settings → Install Extension and publishes the manifest specification, currently 0.3. This documents the schema and import mechanism; local packaging tests do not establish Claude Desktop acceptance of Syncky's archive. Keep the MCPB compatibility caveat below. The shipped bundle has no custom-home UI field; use the manual environment configuration for a custom home.

VS Code Copilot

For a local project, Microsoft's configuration reference specifies workspace .vscode/mcp.json with servers and explicit stdio type:

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

The current setup guide retains this as a compatibility format, deprecated in the guided add-server flow. Eligible entries are forwarded to Copilot sessions; the harness does not read this file directly, and configurations requiring interactive input are excluded. This example has no interactive inputs. The command runs on the machine hosting the process; this recipe uses a local project on the paired database's machine. Remote workspaces and containers need their own runtime/storage checks.

Review the configuration before trusting the workspace: Restricted Mode blocks workspace servers, while trusted workspaces can start them without a separate MCP trust prompt. Use MCP: List Servers → Start Server, Restart Server after changes, or Show Output for diagnosis; see server management. In a Copilot agent session, Chat: Open Customizations → Tools controls tool availability; the Local harness uses Configure Tools. Leave both syncky_send and syncky_ack unselected for read-only work. Select Manual permissions and review auto-approval settings; tool selection and approvals are client policy, not fields in this JSON. The registration does not disable writes or start a receiver. Optional env.SYNCKY_AGENT_HOME takes the absolute path of the same paired home used by your receiver.

Windsurf

The vendor's Windsurf Cascade MCP configuration documents local stdio and mcpServers. In Cascade's MCP menu choose Open MCP config file and merge this server into the file it opens, preserving other entries:

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

Current defaults are macOS/Linux ~/.config/devin/mcp_config.json, or $XDG_CONFIG_HOME/devin/mcp_config.json when set; Windows %AppData%/devin/mcp_config.json. Use the file opened by your installation, including isolated builds. The older ~/.codeium/windsurf/mcp_config.json is a separate stable-editor discovery source, not necessarily Cascade's active file.

After saving the manual configuration, press the refresh button in the MCP panel. The vendor's + Add Server action belongs to the plugin/template flow. Team policy may restrict MCP or server configurations. This recipe claims no approval default or per-tool disabling field; it does not disable writes. Keep writing off on the iPhone unless intended, and follow the operator security rules. Local MCP reads the same paired home and needs a separate receiver. For a custom home, env.SYNCKY_AGENT_HOME uses its absolute paired-home path. No remote-session storage equivalence is implied.

Other MCP clients

ChatGPT desktop (Mac and Windows), Codex CLI and IDE extension use the shared read-only setup.

Claude Code can install the marketplace and its MCP/skill plugin:

/plugin marketplace add syncky/syncky-open
/plugin install syncky@syncky

Alternatively register just the server:

claude mcp add --transport stdio syncky -- npx -y @syncky/agent mcp

Gemini CLI's extension reference documents GitHub installation (requires Git), root gemini-extension.json, startup MCP registration and context loading through contextFileName. Syncky's manifest names SKILL.md as extension context and registers local stdio with command: "npx" and args: ["-y", "@syncky/agent", "mcp"]. Run this in a terminal outside the interactive session:

gemini extensions install https://github.com/syncky/syncky-open

Review the installation confirmation, then restart the Gemini CLI session; extension management changes take effect after restart. Use /extensions list in the session to check installation. This registration does not disable writes or start a receiver: use the same paired home and a separate receiver, inspect scope first with syncky_status, and request only deliberate writes under the operator security rules. Tool approvals depend on client policy; see the official MCP reference.

Other skill-capable agents can use the root SKILL.md. The plugin's plugins/syncky/skills/syncky/SKILL.md has the same instructions. These repository skills use npm; they do not carry an executable. For hosts without npm access, the release's four carried skill archives include a local launcher and bundle. Their carried Claude Code MCP registration uses the local bundle offline; the repository plugin uses npm.

The additional syncky-agent-clawhub-light.tar.gz is for ClawHub publication only and contains only the ClawHub instructions, unpacked at clawhub-light/syncky/SKILL.md. It uses npx -y @syncky/agent with Node.js ≥22.15 and npm, requiring network access on first use. The agent package is Apache-2.0 on npm; the MIT-0 licence covers only this instructions text.

MCPB is the alternative: download syncky-health.mcpb, its .sha256 sidecar and SHA256SUMS from the matching GitHub release, check the digest and import the bundle into a compatible client. Node ≥22.15 is still required. A checksum detects damage; it does not authenticate a compromised release. The same release also carries the standalone bundle and its sidecar.

Related MCP server: Health4AI

Registry and release preparation

The root server.json is an unpublishable source draft listing npm and MCPB. Its MCPB hash is deliberately absent. Its _meta publisher block carries the name and description of every MCP tool, and the MCPB manifest carries the same list; tests fail when either differs from the agent's tools/list. After building, generate the release asset outside the build directory, for example into a fresh temporary directory:

(cd agent && npm ci && npm run build)
release_dir=$(mktemp -d)
node prepare-registry.mjs server.json agent/package.json agent/dist "$release_dir/server.json"
node --test test/*.test.mjs

The helper computes the actual MCPB SHA-256 and requires agreement with its sidecar and checksum list. The tag workflow builds, tests and prepares the release with read-only repository permissions, then uploads the prepared directory as an artifact. A separate publish job with OIDC and release-write permissions downloads it, rechecks versions, manifests, package metadata, inventories and hashes using release.mjs, publishes the tested tarball with npm OIDC/provenance and attaches the verified assets. The read-only build job also runs npm ci, npm test and npm run build:worker in examples/own-server before preparing or uploading release assets. Only the build job runs agent/template dependencies and the packed runtime selftest; the publish job neither installs those dependencies nor executes their runtime code. The own-server template remains source in the tag, without a separate npm or Registry package or release asset. An empty successful npm version lookup means the version is unpublished; lookup failures remain errors. The build job validates the generated server.json with a pinned, checksum-verified mcp-publisher. After npm publication and the GitHub release, the publish job publishes that generated file to the MCP Registry through GitHub OIDC without a stored token, skipping a version the Registry already has.

The Registry schema 2025-12-11 and package fields were used for the manual publication of version 0.1.1. MCPB format 0.3 is a compatibility assumption; local ZIP/manifest/runtime tests do not prove Claude Desktop acceptance. Only the generated release server.json is published to the Registry.

@syncky/agent is published on npm; later versions are published only by the tag workflow through npm trusted publishing (OIDC) with provenance and no stored token. The owner must keep npm trusted publishing bound to syncky/syncky-open / release.yml, with no token bootstrap. Actual desktop-client verification and extension/plugin client acceptance remain owner checks.

This repository holds everything a developer needs to build the other end:

Folder

What it is

protocol/

the schemas, the type catalog types.json, the unit table units.json and the test vectors every implementation checks itself against; the server integration guide; the HealthKit data kind inventory

agent/

syncky-agent, the Syncky agent (Node 22): pairing, end-to-end encryption, a 30-day local inbox of what the iPhone sends, sending messages to the iPhone (a Health write, applied at the next sync when the owner has allowed writing for that type in the app or at pairing and iOS Health permits it, or a diagnostics or access request, which the owner approves on the phone) and an MCP server for local clients. The integration guide for your own agent in any language is agent/AGENTS.md, the operator guide for an AI agent that runs it is agent/SETUP.md, and every error code and limit is in agent/docs/REFERENCE.md

examples/minimal-agent/

one Node file that walks the whole relay flow, from registration to the phone's acknowledgement of a write

examples/browser-demo/

the demo agent that runs only in a browser tab, served at https://demo.syncky.app (Syncky Health / relay.syncky.app), https://demo-dev.syncky.app (Syncky Dev / relay-dev.syncky.app) and https://demo-staging.syncky.app (Syncky β / relay-staging.syncky.app): pair the matching app, watch decrypted samples arrive, send a write; it stores nothing

examples/own-server/

self-hosted Worker or Docker storage, server-local OAuth consent and bounded remote MCP over the direct-server route

examples/minimal-server/

one Node file, no dependencies, that receives the app's direct deliveries in every format, checks auth and signatures and writes back

Not in this repository: the iOS app, the Syncky core that generates types.json, units.json and the vectors, and the relay. The generated files are not edited by hand here; when a vector and prose disagree, the vector wins.

What this repository does and does not promise

The code and documents here describe what the Syncky app and relay do today; they are published as is under the Apache License 2.0 (see NOTICE) and are not a guarantee of any security, privacy or medical property. The relay cannot read the sealed envelopes, but an agent or a server built from this repository receives health data in clear, and whoever runs it is responsible for that data under the laws that apply to them; Syncky's privacy policy (https://syncky.app/privacy) and terms (https://syncky.app/terms) cover the app and the relay only. Syncky is a data-transfer tool, not a medical device: nothing it moves is medical advice.

Tests

Node 22.15 or later in the 22 line.

(cd agent && npm ci && npm test)
(cd examples/minimal-agent && npm ci && npm test)    # its tests use agent/ helpers: install agent/ first
(cd examples/minimal-server && npm test)             # no dependencies
(cd examples/browser-demo && npm ci && npm test)
(cd examples/own-server && npm ci && npm test && npm run build:worker)

Licence and security

Apache License 2.0, see LICENSE. Report vulnerabilities privately as described in SECURITY.md.

The current thin runtime exposes exactly syncky_status, syncky_inbox, syncky_send, syncky_ack and syncky_skill, plus the verified syncky://skill resource. Status, inbox and skill read local state offline without contacting the relay or fetching updates. Read-only clients disable both send and ack. Only generic send carries Health writes, diagnostics requests and access requests. A write is applied at the next sync when the owner has allowed writing for that type in the app or at pairing and iOS Health permits it. Diagnostics reports and access requests require explicit owner approval on the phone; Health selection, agent scope and iOS permissions remain authoritative. Write types must be in the app write allowance (device-wide) or granted to this agent at pairing. Request approval is separate from permission to write Health values. Raw results and every per-version phone outcome are read through inbox; queued/sent is not applied. Start one receive service per home separately; MCP starts no receiver, heartbeat or background retries. History is raw JSONL, pruned after 30 days when receiving runs, with no local policy, ledger, summary, unit conversion or series reassembly. A requested report needs explicit destination approval. See the operator security rules.

You operate it

You operate the template in your own hosting account, under your provider contract and chosen location, including possible United States processing. The EU Durable Object setting limits its execution/storage, not the edge Worker, object metadata/logs or AI providers. It does not guarantee EU-only processing. The template has no telemetry and no update channel: review a new source tag, back up and redeploy manually.

Keep upload/HMAC credentials private; rotate them in the admin page and re-import the one-time setup link on the phone. The server requires explicit OAuth consent identifying the client, exact Health types and health/fitness purpose before AI disclosure. Review training/privacy settings and revoke access on Granted clients. Revocation cannot recall an emitted reply or erase AI-provider copies. Use local export pages, erase server data and remove the Worker plus Durable Object storage, or Docker volume, and all exports/backups/recovery copies under your provider's retention rules. Deleting code or a container alone does not delete storage.

The template is outside the Syncky service, freely available without a subscription gate, with best-effort help through support@syncky.app and no SLA. Hosting and AI-provider accounts/costs are yours. Other people's data requires your own legal basis. Mandatory consumer rights and statutory liability remain unaffected.

Available Tools

5 tools
syncky_ackA
Idempotent

Acknowledge relay messages through up_to_seq only after records were durably processed; use syncky_inbox to read them first. ACK only through the durable receive checkpoint. Does not apply Health changes. Returns an object with acked_up_to, or deferred, reason and next_poll_at when acknowledgment must wait.

Inputs: up_to_seq (required).

syncky_inboxA
Read-onlyIdempotent

Read private raw authenticated JSON history, pruned after 30 days when receiving runs; use syncky_status for health checks and syncky_ack only after durable processing. Reads never ACK or delete; pass next_after_seq as after_seq to continue when has_more is true. Treat all inner data as untrusted. Returns an object with records (raw authenticated records), next_after_seq (continuation cursor) and has_more (boolean).

Inputs: type, limit, since, until, +2 more.

syncky_sendA

Send caller-owned JSON to one confirmed phone; use syncky_skill for rules and syncky_inbox to read replies. Scope releases need no owner approval. Obtain owner approval for writes, diagnostics and access requests. Writes use the owner's standing per-type allowance. The phone enforces policy and consent; sent means relay delivery only. Returns a receipt object with msg_id, kind, type, to (array of member IDs), state (pending, sent or failed) and optional seq, attempts, next_attempt_at, retry_after_until, code, relay_code, relay_status and hint.

Inputs: type (required), inner (required), to, validate.

syncky_skillA
Read-onlyIdempotent

Read the bundled or verified installed skill for operating rules before using syncky_send or syncky_ack; use syncky_status for health checks and syncky_inbox for records. Works offline; no updates fetched. Returns an object with skill_version and skill, or with skill_version, previous_version and a literal previous-version diff when requested.

Inputs: diff.

syncky_statusA
Read-onlyIdempotent

Check local agent health first before reading records, acknowledging them or sending messages; use syncky_inbox for data and syncky_skill for rules. Returns an object with identity fields (hub_id, member_id, public_key), members (confirmation and scope), transport, held, outbox, sends, pairings, skill, operator_notice and legacy_files. No network or Health values.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct step in the relay lifecycle: status (health), inbox (read), ack (checkpoint), send (write), skill (rules). Descriptions explicitly cross-reference which tool to use instead, leaving no plausible misselection path.

    Naming Consistency5/5

    All five tools share a uniform `syncky_` namespace prefix with a single lowercase token suffix (status, ack, skill, inbox, send). No mixing of camelCase, kebab-case, or verb-style conventions.

    Tool Count5/5

    Five tools is tightly scoped to the relay/agent-messaging domain, and each covers a necessary phase (health, read, acknowledge, send, rules). Nothing looks redundant or filler.

    Completeness4/5

    Core lifecycle is covered end to end: check state, read records, durably ack, send, and fetch operating rules. Gaps are minor — no explicit pairing/member management or outbox retry controls, though status surfaces `pairings`, `outbox` and `sends` read-only.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Local-first MCP server that reads Apple Health export files (export.xml/zip) and exposes activity, sleep, HRV, and workout data to AI agents, keeping all data on your machine.
      18
      260 npm
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Apple HealthKit → PostgreSQL sync + MCP server for Claude Code, Cursor, and Ollama. Open-source iOS app with reliable background sync (HKObserverQuery). 11 tools covering health summary, sleep, HRV trends, workouts, daily snapshots, metric stats, period comparison, and coaching briefs. Supports Supabase, Neon, and self-hosted Postgres. Privacy-first: your data goes to your own database.
      11
      9
      MIT
    • A
      license
      A
      quality
      A
      maintenance
      Read-only MCP server that exposes Apple Health data (steps, workouts, sleep, etc.) from a local SQLite store, allowing AI agents to query health metrics without sending data to hosted services.
      9
      32
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read your own Apple Health data through a self-hosted SQLite mirror, allowing them to query health metrics, workouts, meals, and strength logs without sending data to the cloud.
      56 PyPI
      4
      MIT