OS integration internals
Calendar, Mail, Reminders, and Notes live on the host operating system, and their APIs are host-only: a container cannot reach them. So Speedwave runs mcp-os as a host process instead of inside a container like every other MCP worker (the hub, Slack, Redmine, and the rest). This page covers how a request reaches a native host app and back, and how macOS gates it along the way. For what these integrations do day to day, see OS integrations.
Why this worker runs on the host
Section titled “Why this worker runs on the host”Claude never talks to mcp-os directly. The MCP Hub proxies every request through the gateway alias host.docker.internal, keeping the same single entry point as every containerized worker, just reached over local HTTP instead of a container network.
Request flow
Section titled “Request flow”A request crosses the container boundary to reach mcp-os, which then shells out to a native helper that drives the target app:
graph LR C["Claude (in container)"] --> H["MCP Hub (container)"] H -->|"host.docker.internal"| OS["mcp-os (host process)"] OS -->|"posix_spawn"| CLI["native helper CLI"] CLI -->|"EventKit / Apple Events"| APP["Calendar, Reminders, Mail, Notes"]
macOS implementation
Section titled “macOS implementation”On macOS, four standalone Swift CLI binaries each own one service, using whichever framework is stable:
| Binary | Framework | Purpose |
|---|---|---|
reminders-cli | EventKit | Reminders create/read, plus marking complete (no update or delete) |
calendar-cli | EventKit | Calendar events CRUD |
mail-cli | AppleScript / Apple Events | Apple Mail and Outlook: read, send, and reply (send gated by a confirmation flag) |
notes-cli | AppleScript / Apple Events | Apple Notes CRUD |
mcp-os calls these helpers at runtime rather than linking the frameworks itself.
Windows OS integration is not available yet. The planned design is a single Rust binary using WinRT and Outlook’s MAPI interface.
Network model
Section titled “Network model”mcp-os has no fixed port: it starts with PORT=0, the OS picks a free one, and the process manager records it for the Hub. It binds 127.0.0.1 on macOS and the WSL virtual adapter IP on Windows, where mirrored-mode loopback does not work. Unlike the containerized workers, it never binds 0.0.0.0.
Security
Section titled “Security”Every request to mcp-os carries a per-session bearer token, generated at startup, so no other process on your machine can reach the endpoint. See How credentials are handled for the wider picture of what Claude can and cannot reach.
The four macOS binaries also run under Apple’s Hardened Runtime, which restricts platform APIs by default: Apple Events for mail-cli and notes-cli, calendars and EventKit for calendar-cli and reminders-cli.
macOS permissions (TCC)
Section titled “macOS permissions (TCC)”On macOS, access to Calendar, Reminders, Mail, and Notes is gated by Transparency, Consent and Control (TCC), the system behind the “allow access” dialogs. A spawned CLI helper needs extra details to satisfy TCC where a plain command would silently fail. See OS integration permissions for how each helper identifies itself and how Speedwave reconciles permission state at startup.