OS integration internals

Desktop productivity tools (Calendar, Mail, Reminders, and Notes) interact exclusively with host operating system APIs. Because containerized environments cannot directly invoke Apple frameworks, Speedwave runs mcp-os as a native host-side process rather than a containerized worker. This document details communication pathways and security gating. For feature capabilities, see OS integrations.

Host process mediation architecture

Claude never establishes direct connections with mcp-os. Tool calls route from Claude Code to the Tool Gateway (MCP Hub), which forwards requests to the host process via host.docker.internal:

graph LR
  C["Claude Code (Sandbox Container)"] --> H["Tool Gateway (MCP Hub)"]
  H -->|"host.docker.internal:PORT"| OS["mcp-os (Host Process)"]
  OS -->|"posix_spawn"| CLI["Native Swift Helper"]
  CLI -->|"EventKit / Apple Events"| APP["Calendar, Reminders, Mail, Notes"]

Native platform implementations

macOS

On macOS, mcp-os executes four standalone Swift helper binaries using native Apple frameworks:

Helper binary	Apple framework	Capabilities
reminders-cli	EventKit	Inspect, create, and mark reminders completed.
calendar-cli	EventKit	Full calendar event management (CRUD).
mail-cli	AppleScript / Apple Events	Apple Mail and Outlook inspection, drafting, and verified sending.
notes-cli	AppleScript / Apple Events	Apple Notes inspection and authoring (CRUD).

Helper binaries execute out-of-process via posix_spawn, isolating framework crashes from the main process.

Windows

Windows native host integrations are currently under development, planned as a standalone Rust implementation utilizing WinRT and Outlook MAPI interfaces.

Network binding and security boundaries

• Dynamic ephemeral ports: The mcp-os daemon initializes with PORT=0, binding to an ephemeral loopback port allocated by the operating system kernel and registered dynamically with the Tool Gateway.
• Strict loopback isolation: On macOS, the socket binds strictly to 127.0.0.1 (or WSL adapter IP on Windows), never binding to 0.0.0.0.
• Session authentication: Every incoming request must provide a high-entropy bearer token generated during application startup.
• Apple Hardened Runtime: Swift helper binaries enforce Apple Hardened Runtime constraints, restricting entitlement access to declared Apple Events and EventKit APIs.

Transparency, Consent, and Control (TCC)

Native macOS API access is governed by Apple’s TCC subsystem. Swift helper binaries embed specific code-signing entitlements and bundle identifiers required for macOS consent dialogs. See OS integration permissions for permission lifecycle management.