How to connect ActivitySmith MCP with Codex

List Push Notification history for the account, newest first. Use it to review what was sent, find a notification's public_id, or filter by Tags; for one known notification, use get_push_notification. Equal creation times use descending ID order. Equal creation times use descending ID order. Defaults: limit 50, offset 0; maximum limit 100. Continue with meta.next_offset and the same filters; stop when it is null. Results can change between requests.

Get one sent Push Notification from this account by its public ID, with its content, delivery status, number of devices notified, errors, Tags, metadata, and replacement count. Use it to inspect a specific notification, for example before calling replace_push_notification. To browse or filter history, use list_push_notifications. Returns a not found error for an unknown ID.

Set the number shown on the ActivitySmith App Icon Badge on the user's iPhone or iPad, such as a count of open incidents or pending reviews. It updates the badge silently, without showing a Push Notification; use send_push_notification when the user should be alerted, or its badge field to set both at once. Send 0 to clear the badge. The value replaces the current number rather than adding to it, so repeating a call is safe. Optionally target channel slugs. Describe the result only as setting or clearing the App Icon Badge.

Send an ActivitySmith Push Notification to this account. Optionally target channel slugs. Normal notification taps use redirection, which accepts HTTP/HTTPS URLs and installed apps' custom URL schemes, such as spotify:// or shortcuts://run-shortcut?name=Example. Expanded notification actions use actions, up to 4 items. open_url actions accept the same external URLs as redirection. Custom app schemes require iOS app 1.13.4 build 2 or later and the target app to be installed; no web fallback is provided. Unsafe schemes and ActivitySmith's internal scheme are blocked. webhook actions call an HTTPS endpoint with GET or POST and optional JSON body. media can be combined with redirection, but media cannot be combined with actions. The result includes notification_id. Pass it to replace_push_notification to update this notification later, for example when an incident you alerted on is resolved. icon shows an HTTPS image, such as a logo or avatar, next to a smaller ActivitySmith app icon; iOS may hide the subtitle. interruption_level is passive (quiet, no sound), active (default), or time-sensitive (can break through Focus when allowed); use time-sensitive only for things the user must see now. Both require iOS app 1.16.0 or later. Action examples: [ { "title": "Open Build", "type": "open_url", "url": "https://github.com/acme/web/actions/runs/123" }, { "title": "Chat with Jarvis", "type": "open_url", "url": "shortcuts://run-shortcut?name=Jarvis" }, { "title": "Create Incident", "type": "webhook", "url": "https://hooks.example.com/incidents/create", "method": "POST", "body": { "service": "payments-api", "severity": "high" } } ]

Replace a Push Notification that was already sent, using the notification_id returned by send_push_notification. The replacement takes the old notification's place on the Lock Screen and in Notification Center, so the user does not end up with two. It arrives silently: no sound and no screen wake. Use it to update a Push Notification you already sent, for example when an incident you alerted on is resolved. Replacement content fully replaces the old title, subtitle, message, redirection, media, icon, actions, and payload. Omitted metadata and tags keep their stored values. The notification goes to the same recipients as the original. History is updated in place.

List the people in this ActivitySmith account with their email, name, role, and how many active devices they have. Use it to choose users for set_channel_users, or device owners for set_channel_devices; pass their emails. Owners come first, then admins, then members, each sorted by email. Returns all users at once, without pagination.

List the iPhones and iPads paired to this account, with each device's device_id, owner email, name, and app and iOS versions. Use it to find device_id values for set_channel_devices. Ordered active first, then most recently updated and created, with stable device and owner tie-breakers. Defaults: limit 100, offset 0; maximum limit 100. Continue with meta.next_offset and the same filters; stop when it is null. Results can change between requests.

List the account's channels with each channel's slug, public_id, and the number of assigned users and devices. Channels are optional groups of recipients that Push Notifications, Live Activities, and the App Icon Badge can target with target_channel_slugs. Use this to find the slug or public_id that get_channel, update_channel, delete_channel, set_channel_users, and set_channel_devices need. Returns all channels at once, newest first, without pagination.

Get one channel with the users and individual devices assigned to it. A delivery sent to the channel reaches every active device of each assigned user, plus each individually assigned device. Call this before set_channel_users or set_channel_devices, which replace the whole list, so you can keep existing assignments. Returns the channel's slug and public_id, users (public_id, email, name), and devices (user public_id, email, device_id).

Create a channel: a named group of recipients that Push Notifications, Live Activities, and App Icon Badge updates can target with target_channel_slugs, and that API keys can be scoped to. Channels are optional; without them, deliveries go to every device in the account. Only create one when the user wants to route deliveries to some people or devices. The new channel is empty, so add recipients with set_channel_users or set_channel_devices. Fails if the slug already exists. Returns the channel's public_id and slug.

Rename a channel by changing its slug. Assigned users, devices, and API key scopes stay attached. Senders that target the old slug, such as scripts, SDK calls, and agents using target_channel_slugs, stop reaching this channel until they switch to the new slug, so confirm with the user first. Identify the channel with public_id or current_slug and pass the new name as slug. Alternatively, pass the current slug as slug and the new name as new_slug. Fails if the new slug is already used. Returns the updated channel.

Delete a channel. It disappears from list_channels, its slug no longer works for targeting, and its user and device assignments stop applying. Users and devices themselves are not affected, and API keys scoped to this channel no longer deliver through it. This cannot be undone through MCP, so confirm with the user first. Returns success with the deleted channel's public_id and slug.

Replace the full list of users assigned to a channel. Every active device of each listed user receives deliveries sent to the channel. Users left out are removed, and sending no users removes them all; individually assigned devices from set_channel_devices are kept. To add one user, call get_channel first and send the existing users plus the new one. Users must belong to the account (see list_account_users). Returns the channel and the resulting list of user emails.

Replace the full list of individually assigned devices in a channel. Use it to include specific devices, such as one person's iPad, without adding all of that person's devices through set_channel_users. Devices left out are removed, and sending no devices removes them all; user assignments are kept. To add one device, call get_channel first and send the existing devices plus the new one. Each device must belong to the given account user (see list_account_devices). Returns the channel and the resulting device assignments.

List the account's Tags with how many Push Notifications and Live Activities use each one. Use it to find Tag slugs for the tags filter of list_push_notifications and list_live_activities, or to reuse existing Tags when sending. Sorted alphabetically by slug, then ID. Defaults: limit 50, offset 0; maximum limit 100. Continue with meta.next_offset and the same filters; stop when it is null. Results can change between requests.

List every Lock Screen Widget metric in the account, newest first, with each metric's key, label, format, and latest value. Use it to find a metric's public_id (for update_widget_metric and delete_widget_metric) or key (for set_widget_metric_value), or to check the current value before changing it. Deleted metrics are excluded. Returns all metrics at once, without pagination.

Create a Lock Screen Widget metric: a named value, such as monthly revenue or deploy success rate, that the user can show in an ActivitySmith widget on their iPhone or iPad Lock Screen. Create each metric once, then send values with set_widget_metric_value using the same key. To change the label or format later, use update_widget_metric. The new metric has no value yet, and nothing changes on the Lock Screen until the user adds a widget for it. Fails if the key already exists in the account. Returns the created metric, including its public_id.

Change an existing Lock Screen Widget metric's definition: key, label, format, currency, or unit. All definition fields are replaced, so send the current values (from list_widget_metrics) for anything you want to keep. To record a new value, use set_widget_metric_value instead. Side effects: a new key breaks scripts, SDK calls, and agents that still send values with the old key, and switching between the string format and a numeric format clears the latest value. Widgets show the change on their next refresh, about every 15 minutes. Fails if another metric already uses the key. Returns the updated metric.

Delete a Lock Screen Widget metric. It disappears from list_widget_metrics, set_widget_metric_value calls with its key fail with Metric not found, and widgets showing it stop receiving new values. This cannot be undone through MCP; to rename a metric or change its format, use update_widget_metric instead. Returns success and the deleted metric's public_id.

Record the latest value of a Lock Screen Widget metric, identified by its key. Use it whenever the tracked number or text changes, such as new revenue, signups, or uptime. The value replaces the previous one. Widgets on the user's Lock Screen pick it up on their next refresh, about every 15 minutes, so it is not instant; for an immediate alert, use send_push_notification. The metric must already exist (see list_widget_metrics and create_widget_metric). Each successful call counts as a billable metric update and returns a billing error when the account's trial or plan does not allow more. Returns the metric with its new latest value.

Ask the ActivitySmith account owner for a decision. Sends an actionable Live Activity when available, falls back to an actionable Push Notification, and waits up to 45 seconds. If the result is pending, call wait_for_approval repeatedly with the returned approval ID. The approval ID stays valid across client timeouts and reconnects. Choose action-specific approve_label and reject_label values when they make the decision clearer, such as Send/Cancel or Deploy/Hold. When approving a concrete command or tool call, include execution_context and the most relevant scope so the user can evaluate the actual operation.

Wait up to 45 seconds for a pending approval without polling the database. The wait wakes immediately through Redis when the user acts. If the result remains pending, call this tool again with the same ID.

Get the current state of an approval request without waiting: pending, approved, rejected, timed_out, or cancelled, with the decision time when there is one. Use it for status checks or to recover after losing track of a request. To block until the user decides, use wait_for_approval instead. Returns Approval not found for an unknown ID.

Cancel a pending approval request that is no longer needed, for example because the agent changed plans or the operation already happened. The approval Live Activity on the user's iPhone updates to show it was cancelled, the user can no longer approve or reject it, and any wait_for_approval call returns the cancelled state. Only pending requests change; for an approval that is already decided, timed out, or cancelled, this returns its current state unchanged. Do not cancel to retry; use wait_for_approval to keep waiting. Returns the approval's resulting state.

List API keys for the authorized ActivitySmith account, newest first. Returns names, key prefixes, channel scope, and whether a key was created by an AI agent. Secret key values are never returned. Requires the "Manage API keys" permission, which the user grants on the ActivitySmith approval screen.

Create an ActivitySmith API key for code that calls the ActivitySmith API, such as a CI job, server, or script. The secret is returned once. Store it directly in the user's secret manager or a git-ignored environment file, never commit it or print it in chat, and tell the user where you saved it. Keys keep working after this MCP connection is disconnected; the user can delete them in the ActivitySmith web app. Use scope_mode "channels" with channel_slugs only when the key should reach a subset of recipients. Requires the "Manage API keys" permission, which the user grants on the ActivitySmith approval screen.

Rename an ActivitySmith API key. The key secret and its access do not change. Requires the "Manage API keys" permission, which the user grants on the ActivitySmith approval screen.

Permanently delete an ActivitySmith API key. Anything still using it starts failing immediately, and this cannot be undone. Confirm the key name with the user before deleting a key you did not create in this session. Requires the "Manage API keys" permission, which the user grants on the ActivitySmith approval screen.

Create or update a managed Live Activity stream by stable stream_key. This is the preferred Live Activity MCP workflow. Do not use legacy start/update/end ids. The stream_key is the handle. REMOTE DELIVERY BUDGET: Each non-noop operation can send a remote ActivityKit push. iOS applies device-dependent push-to-start and update budgets and may throttle delivery even after APNs accepts the request. Use one stable stream_key for each real-world activity and send updates when its user-visible state meaningfully changes. Event-driven transitions may be seconds apart—for example, successive steps in a short deployment—and should be sent promptly; do not delay them to satisfy a fixed minimum interval. Short bursts of genuine progress are expected. Avoid sustained polling, heartbeat updates, per-second timer ticks, unchanged values, and high-frequency churn that does not communicate a meaningful transition. Coalesce only redundant or excessively granular changes. Do not retry a successful call to force display: success means APNs accepted the push, not that the device displayed it. First call starts the Live Activity. Later calls with the same stream_key, same content_state.type, and same target channels update it. Repeating the same payload returns operation "noop". Changing the type or target channels rotates to a new underlying Live Activity. Keep content_state.type and target channels stable to avoid consuming another push-to-start operation. For countdowns, send timer fields once and let the device render elapsed time locally instead of sending frequent updates. Supported content_state.type values: segmented_progress, progress, metrics, stats, alert, timer, value. Icons work with stats, metrics, progress, segmented_progress, alert, timer, and value. Use Apple SF Symbol names for icons. Badges work with alert, progress, segmented_progress, and value. A top-level action adds the Live Activity tap/action button and can open an HTTP/HTTPS URL, run an iPhone Shortcut with shortcuts://run-shortcut?name=..., or trigger a backend webhook. A top-level secondary_action adds a second button for alert, progress, segmented_progress, and value Live Activities. Examples: { "value": { "title": "Current revenue", "subtitle": "Today", "type": "value", "value": "$1,240", "color": "cyan", "icon": "dollarsign.circle", "badge": { "title": "Live", "color": "green" } }, "segmented_progress": { "title": "Deploying API", "subtitle": "Step 2 of 4", "type": "segmented_progress", "current_step": 2, "number_of_steps": 4 }, "progress": { "title": "Uploading build", "subtitle": "42% complete", "type": "progress", "percentage": 42 }, "metrics": { "title": "Server load", "subtitle": "Current usage", "type": "metrics", "metrics": [ { "label": "CPU", "value": 27, "unit": "%" } ] }, "stats": { "title": "Sales", "subtitle": "Last 15 minutes", "type": "stats", "metrics": [ { "label": "Revenue", "value": 12.8, "unit": "k" }, { "label": "Orders", "value": 37 }, { "label": "Avg Order", "value": "$346" } ] }, "alert": { "title": "Alert", "message": "Incident response started. Primary API is degraded across regions.", "type": "alert", "color": "magenta", "icon": { "symbol": "exclamationmark.circle", "color": "yellow" }, "badge": { "title": "Escalated", "color": "gray" } }, "timer": { "title": "Benchmark Run", "subtitle": "sampling performance", "type": "timer", "duration_seconds": 300, "color": "cyan", "counts_down": true } } Action examples: { "open_url": { "title": "Open Runbook", "type": "open_url", "url": "https://example.com/runbook" }, "shortcut": { "title": "Chat with Jarvis", "type": "open_url", "url": "shortcuts://run-shortcut?name=Jarvis" }, "webhook": { "title": "Acknowledge", "type": "webhook", "url": "https://example.com/hooks/ack", "method": "POST", "body": { "incident_id": "inc_123" } } }

End the current Live Activity for a managed stream and remove the stream key. Use it when the tracked work is finished; to stop updates temporarily and keep the key, use pause_live_activity_stream instead. A later set_live_activity_stream call with the same key starts a new Live Activity. Ending remotely also uses the device's ActivityKit push budget, so end once for a genuine lifecycle completion and do not repeatedly end and recreate a stream to refresh it.

List Live Activities sent from this account, newest first, with their status, Tags, and latest content. Use it to review recent activity or find an activity_id; for one known activity, use get_live_activity. To change a running activity, use the stream tools such as set_live_activity_stream. Equal creation times use descending ID order. Equal creation times use descending ID order. Defaults: limit 50, offset 0; maximum limit 100. Continue with meta.next_offset and the same filters; stop when it is null. Results can change between requests.

Get one Live Activity from this account by its ID returned by list_live_activities, including metadata, tags, channels, and action payloads. Read-only; to update or end it, use the stream tools. Returns a not found error for an unknown ID.

Pause a managed Live Activity stream and end its current activity if needed. Pausing can send a remote end and use the device's ActivityKit push budget; use it only for a genuine pause, not as update-rate control. Future set_live_activity_stream calls for the same key are ignored until resume_live_activity_stream is called.

Resume a genuinely paused managed Live Activity stream. The next set_live_activity_stream call can remotely start the stream again and consume push-to-start budget.