# Connect Agent Alerts through remote MCP

Remote MCP endpoint: https://www.andreas.ink/api/agent/mcp
Setup page: https://andreas.ink/agent/mcp

If agentalerts_* tools are already connected, call agentalerts_status. Use
that connection if it is ready; otherwise report the missing setup or scope.
Do not request a token in chat.

For an interactive client, add the endpoint above and sign in through the
browser with the same account used by the Agent Alerts iPhone app.

For a headless server that supports a custom HTTP Authorization header:

1. Have the human create a connection token at https://andreas.ink/agent
   and approve it on iPhone. Choose publish-only access for updates, or Full
   access if the server must poll responses or send requested alarms.
2. The human stores the one-time token as AGENTALERTS_AGENT_TOKEN in the
   server's secret manager, outside the AI conversation.
3. Configure the remote MCP endpoint above. Send
   Authorization: Bearer <token from secret manager> on every MCP request.
4. Call agentalerts_status to verify the connection. Never print or log the
   token, or put it in a prompt or URL.

## Agree on alert behavior once

Before setting up ongoing or scheduled updates, ask the user: "Should I refresh
the same card after every completed check, only when the result changes, or at
specific milestones? Which findings should send a notification or an alarm,
and how soon may I repeat one? Where should a tap take you: this agent task or
a report in your preferred document editor?" Reuse an existing answer; do
not ask again on each run. Record the policy in the agent task or schedule.
Agent Alerts stores the card, not the check schedule or these preferences.
A one-time test that the user requested can be sent without this setup step.

## Make the first Live Activity useful

Agent Alerts has two common jobs: keep one task's state visible while an agent
works, or show the result of a check scheduled in the agent's own runtime.
The MCP connection does not start either job. Publish when the user asked for
updates or a scheduled run has a useful result. Reuse one stable activityKey
for the same subject so later results update its card.

Use agentalerts_publish_live_activity for ordinary sends. Pick content.kind
from the evidence; the tool chooses the layout. For example payloads and images,
read agentalerts://live-activity/examples, then the matching exampleUri for
its JSON and PNG together. If your client does not expose MCP resources, call
agentalerts_live_activity_examples with the chosen kind. Use exampleRequest
as the publish tool arguments; renderedState is the exact iOS preview fixture,
not a publish request. Replace all sample facts with observed evidence.
The preview illustrates layout, not evidence for a live claim. Every content
object needs kind, title, summary,
status (good, warning, or critical), and sourceName. Keep each workflow
recognizable through stable title wording, sourceName, and sourceIcon. Color
shows the evaluated state, not the workflow category.

- health: checked state or recovery. Put the strongest observed result in
  stateLabel/stateValue, not a generic "Good" or "Resolved" headline.
- incident: actionable fault or blocked work. Show the failed count or state,
  and set nextAction. Do not show 100% progress when execution never started.
- progress or checklist: measured percentage or real completed/total steps.
- trend: ordered values over time. State the period and metric in text because
  the compact chart has no visible time axis. Use comparison for matched
  periods or categories, and funnel for stages from one cohort and window.
- For operations, security, or delivery, use health or incident according to
  the finding. For verification, use checklist only while real steps run;
  blocked work is an incident. Growth and creator charts need comparable
  values. Research cards need a verified report. Handoffs show one first step;
  briefings show one primary result or action, with secondary watches behind
  the link.
- document or launch: a real report/release review with the required fields.
  Use approval only for an explicit yes/no question; it requires Pro and a
  notification. Poll its interactionId for the response.

Make the title identify the subject and its state or period. sourceName is the
information source, or the agent when it produced the result. The largest
value should be the result; summary should name the measured scope and window.
Use nextAction for one concrete move or "No action needed". Keep detailed
evidence and caveats in a current-run report or task. For a card the user can
act on, include action (20 characters or fewer) and deepLink together. Use
the actual current Codex or Claude Code remote task URL, or a verified report link
in the user's chosen document editor. If the destination supports a draft
prompt, prefill a short unsent follow-up; never auto-submit it or include
secrets in the URL. Do not invent a destination or treat unavailable data as
zero or an unreported day as observed.

Follow the agreed cadence: send the requested periodic refresh even when its
state is unchanged, or send at milestones when that is what the user chose.
Do not send for every tool call. Always report a qualifying blocker, recovery,
deadline, or final result when the policy calls for it. Keep routine refreshes
quiet with importance: "persistent". Use "attention" only for a user-authorized
actionable transition; respect the repeat interval for unchanged conditions.
If the policy is changes-only, routine success, unchanged warning, weak
movement, and source gaps below their threshold can stay in the run record.
End a finished activity with agentalerts_end_live_activity and the same
activityKey. Use
agentalerts_send for explicit multi-surface or exact-device control. Read the
receipt's target counts, delivery stage, and device acknowledgement separately.
Server or APNs acceptance does not prove the card appeared on the iPhone.

Agent Alerts receives updates; it does not run checks or connect data sources.
For a recurring report, configure source access and a durable schedule in the
agent runtime, then publish results grounded in that run. Alarms are for an
explicit reminder or an escalation rule the user has authorized.