MCP for agents
Core includes a Model Context Protocol (MCP) server. Any MCP host, such as Claude Desktop, Claude Code, Codex, Cursor, or a Home Assistant agent, can connect to it and read or control the Pod in plain language. “How did I sleep?”, “Set my side to 68 for an hour”, and “Is everything OK?” each map to one tool call.
Connect a host
The endpoint is a stateless Streamable HTTP server on the same port as the web app. Replace POD_IP with your Pod’s address or sleepypod.local.
http://POD_IP:3000/api/mcpClaude Code
claude mcp add --transport http sleepypod http://POD_IP:3000/api/mcpRun claude mcp list to confirm the server is connected, then ask Claude Code about the Pod.
There is no authentication. Like the REST API, the MCP endpoint trusts the local network. Do not port-forward it or expose it through a public reverse proxy. Browsers cannot reach it cross-origin: a request with an Origin header that does not match the Pod’s host is rejected, which blocks DNS-rebinding pages.
What the assistant can do
The server is intent-shaped, not endpoint-shaped. Each tool describes something a person would ask for, using the shared Core procedures. Every tool calls the same procedures the web app uses, so validation, side locks, the pump-stall guard, and live updates all apply.
| You say | Tool |
|---|---|
| “What’s the bed set to?” / “Is it priming?” | get_pod_status |
| “Who’s in bed?” | get_bed_occupancy |
| “How warm is the room?” | get_environment |
| “How did I sleep?” / “How much deep sleep?” | get_sleep_summary |
| “Bedtime this week?” | get_sleep_history |
| “Is my HRV trending down?” | get_vitals_trend |
| “Set my side to 68” / “Warm it up for an hour” | set_temperature |
| “Turn my side off” | set_power |
| “Go back to the schedule” | resume_schedule |
| “68 now, 72 at 3 am, wake at 7” (tonight only) | run_once_curve |
| “Buzz my side” / “Snooze 10 minutes” | manage_alarm |
| “Prime the pod” | prime_pod |
| “What’s my schedule?” | get_schedules |
| “Every weekday cool to 66 at 10 pm” / “Delete Monday’s alarm” | manage_schedule |
| “What unit is it on?” | get_settings |
| “I’m away until Friday” / “Rename my side” | set_side_settings |
| “Switch to Celsius” / “Dim the LED at night” | set_device_settings |
| “What’s controlling the bed tonight?” | get_automations |
| “Pause all automations” / “Make a rule that cools when HR > 60” | manage_automation |
| “Something’s wrong” / “Is the bed actually cooling?” | diagnose_pod |
| “Why are my biometrics empty?” / “Is sensor data arriving?” | get_sensor_source |
| “Show me the logs” | get_logs |
| “Clear the pump alert” / “Restart the piezo service” / “Update” | pod_maintenance |
Temperatures accept your unit (F or C, defaulting to the device setting) and are converted to the 55–110°F hardware setpoint. Errors come back as readable text with the Core error code, so the assistant can explain “pump stall guard tripped” instead of retrying.
Sensor data source
get_sensor_source reports where Core reads raw sensor frames from. It returns three blocks:
firmware: the firmware generation.stream: whether Core reads .RAW files or NATS, and the age of the last frame.nats: only while Core is reading NATS, on builds that include core#918 :mode(autoorpinned) andconfiguredPrefixsubscribedSubjectssources, the prefix feeding each reading type, for example{ "sens.piezo": "rawmem" }- message counters
observedPrefixes: the prefixes seen publishing<prefix>.sens.*(up to 16), withsubscribed: falsefor one Core does not read
This is how an agent fixes a firmware that moves its data to a new prefix, without anyone patching code:
- Biometrics are empty, or the stream shows no frames.
get_sensor_sourceshows no frames arriving, andobservedPrefixeslists a prefix withsubscribed: false.set_device_settingswithnatsSubjectPrefixset to that prefix.nullreturns to auto.- The live stream re-subscribes at once. The biometrics modules read the prefix at startup, so the reply tells the agent to restart them with
pod_maintenance restart_service. The agent must get your confirmation before each restart: the tool does not ask by itself, although it is marked destructive, so most hosts show an approval prompt. get_sensor_sourceagain to confirm frames are arriving.
The server tells agents to check get_sensor_source before changing anything when live data or biometrics are empty. See sensor data by firmware for the prefixes known so far.
Sleep-stage rules
| Request | Tool |
|---|---|
| Inspect saved rules, recent changes, and Watch reference coverage | get_sleep_stage_rules |
| Compare a preset or edited rules with recent nights without saving | preview_sleep_stage_rules |
| Save a reviewed candidate or reset to defaults | set_sleep_stage_rules |
| Import extracted Watch heart-rate samples or stage segments for a side | import_apple_watch_data |
Preview accepts a preset, a complete ruleset, or indexed condition overrides, for up to 14 nights. Compare reference coverage, stage minutes, Cohen’s kappa, and per-stage recall. Missing Watch overlap cannot establish agreement.
To apply exactly what was previewed, pass the returned candidateRuleset as ruleset to the save tool. Overrides are resolved again against the saved rules at save time. On CONFLICT, inspect the current rules before retrying. Saving requests a change; processor adoption is a separate state. See Sleep stages for the UI and video.
Watch import accepts up to 2,000 records per array, with Unix-second timestamps and an explicit side. Repeated records are skipped. Check stageError for partial success. For a full Health export, use Upload Apple Watch data instead of putting the archive in model context.
Biometric calibration
| Tool | Purpose |
|---|---|
inspect_biometric_calibration | Inspect metric definitions, profiles, runtime state, references, sessions, and replay admission. |
import_biometric_reference | Preview normalized reference records, then commit with the exact preview hash. |
propose_biometric_profile | Save an immutable candidate without activating it. |
manage_biometric_experiment | Freeze datasets, retain selected waveform sources, and manage experiments with pinned protocols. |
backtest_biometrics | Queue, inspect, list, or cancel replay jobs; read reports and bounded trace pages. |
apply_biometric_profile | Request explicitly authorized validated or manual activation, reset, or rollback. |
release_biometric_artifacts | Delete references or release datasets and reports; report release requires its content hash. |
A candidate is not an active profile, and a replay is not proof of processor adoption. Validated activation pins the evaluation and report identity and requires matching qualification policies and evidence. Manual activation requires explicit acknowledgment that the revision is unvalidated. See Biometric calibration for review and recovery.
Reports return compact summaries with omitted-detail indicators and a local REST path. Trace requests use the exact report hash and return at most 500 original intervals per page. Report resources are available at sleepypod://biometrics/reports/{id}; discover IDs through the backtest list. Released reports remain unavailable.
Processing stays on the Pod, but a connected MCP host may send returned data to its model provider. These tools do not authorize off-pod waveform transfer or executable algorithm installation.
Saved curves
get_saved_curves lists templates. manage_saved_curve saves or deletes one; saving the same name replaces that template. Templates have no assigned side or days and do not run by themselves.
apply_sleep_curve accepts points or a saved curveName, a side, and days. Start with mode: "preview" to inspect replaced rows, preserved alarms, warnings, and the final temperature action. mode: "apply" with the reviewed arguments writes the curve. Optional notes replace the selected days’ previous notes. See Saved curves and notes.
Resources and prompts
sleepypod://status and sleepypod://settings provide compact device context. sleepypod://biometrics/algorithms describes metric definitions, while sleepypod://biometrics/profiles/left and sleepypod://biometrics/profiles/right report profile and runtime state.
The built-in prompts are morning_report, bedtime, design_sleep_curve, calibrate_biometrics, explain_biometric_difference, and develop_biometric_algorithm. They guide host workflows; they do not bypass server validation or grant permission to apply changes. The algorithm-development prompt adds no execution or installation tool.
Approvals and safety
Tool annotations tell the host which calls are read-only and which change or delete something. Reads such as get_pod_status and get_sleep_summary are marked read-only. Anything that deletes, restarts, re-energizes, or replaces an active curve is marked destructive, so a well-behaved host asks before running it. The server’s own instructions also tell the model to confirm before priming, maintenance actions, and schedule deletion.
Temperature precedence is the same as everywhere else in Core, highest first: manual hold, run-once curve, automation, schedule. See Temperature and power.
Tool output is untrusted input for the model. Logs, sleep records, and settings can contain text written by anything on the LAN or by firmware. Annotations are hints to the host, not a security boundary.
Deliberately not exposed
Developer and installer surfaces stay REST-only: raw hardware opcodes, raw sensor files, database row browsing, sensor calibration triggers, MQTT, HomeKit, and archive-push configuration, automation backtests, cap-zone replays, and canonical vitals ingestion. They are either dangerous without context or useless to a sleeper. Use the API reference for those.
Source reference: MCP server README and intent catalogue · Server and prompts · HTTP endpoint and origin check · Sensor source tool and subject prefix setting (core#918)