# 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](/docs/integrations/os-integrations/).

## 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

A request crosses the container boundary to reach `mcp-os`, which then shells out to a native helper that drives the target app:

```mermaid
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

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

`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

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](/docs/security/credentials/) 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)

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](/docs/under-the-hood/os-integration-permissions/) for how each helper identifies itself and how Speedwave reconciles permission state at startup.