← All posts

MCP notifications background agent wake without polling

MCP notifications can help a background coding-agent runtime wake without application-level polling, but they do not wake the model by themselves. The useful design is simpler and stricter: keep durable task or resource state outside the agent loop, subscribe to MCP change notifications, treat each notification as a hint, refetch state, then let the host decide whether to start or resume an agent turn.

That distinction matters. MCP defines client and server protocol behavior. It does not define autonomous scheduling, replay, idempotency, approval policy, or a standard meaning for "wake this coding agent now." In production, the host owns that decision.

The short answer for runtime designers

If you are designing an event-driven background agent runtime, the pattern is:

  1. An external webhook, queue, or event bus receives an event.
  2. A control-plane service records the event as durable task or resource state.
  3. An MCP server exposes that state to the host.
  4. The host keeps an active subscriptions/listen stream open.
  5. The host receives a server-to-client notification.
  6. The host refetches the task or resource, checks policy and idempotency, and only then starts or resumes an agent turn.

That is MCP notifications background agent wake without polling in practice. It removes tight loops that repeatedly ask, "is there work yet?" It does not remove the need for connection management, replay, duplicate suppression, rate limits, and fallback checks.

Related reading: long-running background AI agents.

What MCP notifications actually provide

MCP notifications are JSON-RPC one-way messages without an id, so receivers do not send a response for the notification itself, according to the Model Context Protocol overview for the 2026-07-28 specification. That makes them useful for state-change signals, not for confirmed job handoff.

The 2026-07-28 MCP subscriptions pattern introduces subscriptions/listen for long-lived server-to-client notification streams. The brief notes that this replaces legacy resources/subscribe and HTTP GET notification delivery. In Streamable HTTP, change notifications arrive on the SSE response stream from a subscriptions/listen POST, based on the MCP Streamable HTTP specification.

The subscription model is explicit. A client requests notification types in a filter, and the server must not send notification types the client did not request. Core filter fields include toolsListChanged, promptsListChanged, resourcesListChanged, and resourceSubscriptions, according to the MCP subscriptions specification.

There are also protocol details a runtime cannot skip. The first message on a subscription must be notifications/subscriptions/acknowledged. Subscription notifications include _meta.io.modelcontextprotocol/subscriptionId, matching the subscriptions/listen JSON-RPC id. That gives the host a way to tie notifications back to a subscription, but it is still not a durable queue.

Wake the host first, then decide about the agent

The practical split is between waking the MCP client process and waking the autonomous coding agent. MCP can deliver data to the host over an active stream. Only host logic can translate that delivery into a model turn.

That translation should be policy-driven. A resource update might mean "refresh cached context," "enqueue a low-priority job," "ask for human approval," or "resume the agent now." Treating every notification as an agent turn is expensive, noisy, and risky.

A safer host loop looks like this:

onMcpNotification(notification):
  assertSubscription(notification)
  eventRef = extractResourceOrTaskReference(notification)
  state = refetchAuthoritativeState(eventRef)
  if alreadyHandled(state.eventId):
    return
  if not policyAllowsAgentResume(state):
    recordDeferredWake(state)
    return
  enqueueAgentTurn(state.scopedContext, state.idempotencyKey)

The important move is the refetch. The notification says something changed. The durable resource or task state tells the runtime what changed, whether the agent should act, and whether this event has already been handled.

Tasks are close, but do not remove host responsibility

The MCP Tasks extension is relevant for long-running background work. The brief says it supports asynchronous work through CreateTaskResult, tasks/get, tasks/update, tasks/cancel, and optional notifications/tasks, based on the MCP Tasks Extension 2026-07-28 specification.

Tasks define polling as a baseline through tasks/get and pollIntervalMs. Task notifications can remove the need for continued polling when a client is subscribed. But the host still needs to manage the state machine around those notifications: active, waiting, completed, failed, canceled, expired, and any local retry or approval states your runtime adds.

There is also an implementation caveat. A TypeScript SDK issue opened on 2026-07-28 reports that subscriptions/listen cannot currently express extension notification filters such as Tasks because the filter object is closed to core keys. Treat that as an implementation parity warning, not as a conclusion about the specification itself.

Related reading: agent harness design for coding agents.

No polling still needs a fallback path

"No polling" should mean no hot application loop and no repeated LLM turns checking for work. It should not mean no recovery mechanism.

Long-lived streams fail. Connections drop. Proxies buffer or close SSE streams. Hosts restart. A subscription can be acknowledged and still become stale later. The production control plane needs slow fallback polling or reconciliation outside the model loop so missed events do not disappear.

That fallback can be boring by design:

  • Run reconciliation in the host or control plane, not inside an agent turn.
  • Store event ids, cursors, or idempotency keys with the durable task state.
  • Make notification handlers safe to run more than once.
  • Track subscription health, reconnects, duplicate notifications, and wake decisions.
  • Back off when the event source is noisy or the agent is already busy.

This keeps the expensive part, the model loop, out of infrastructure babysitting. The agent sees scoped work when there is work worth doing.

Progress notifications are not a wake channel

Do not confuse MCP progress notifications with a general-purpose wake mechanism. The brief notes that notifications/progress and notifications/message are request-scoped. In Streamable HTTP, they flow only on the response stream for the request they relate to. The older MCP progress utility also frames progress notifications around active requests with a progressToken. They are useful during active work, not for waking an idle background agent later.

The older 2025-11-25 MCP model also matters because examples and libraries may still refer to optional resources/subscribe and notifications/resources/updated, as described in the older MCP resources specification. For a new runtime, check which MCP version your host, server, and SDK actually support before you design around a specific subscription shape.

Security concerns start at the event boundary

An event-triggered coding agent expands the input surface of the system. The wake path might start with a GitHub webhook, issue comment, CI signal, chat message, file change, or internal ticket update. Any of those can carry attacker-controlled text.

The brief points to GitHub webhooks as the canonical push analogy: a system subscribes to events and receives HTTP deliveries when they occur. It also points to GitHub Actions repository_dispatch as an external-event wake pattern. Those analogies are helpful, but an agent runtime needs stricter controls because the downstream actor can read code, propose changes, run tools, and ask for approvals.

At minimum, put these controls before agent resume:

  • Authenticate the upstream event source.
  • Bind events to a narrow repository, workspace, tenant, or task scope.
  • Separate event metadata from untrusted content that may enter the prompt.
  • Require approval for high-impact tool calls and code changes.
  • Log the event id, source, subscription id, policy decision, and agent turn id.
  • Cap retries and chained resumes so hooks or stop conditions cannot loop forever.

CloudEvents-style metadata is a good shape even when MCP payloads are simpler: id, source, type, subject, time, and an idempotency key. The specific envelope can vary. The need for stable identity and auditability does not.

Related reading: coding agent sandbox choices for Docker, microVMs, and devcontainers.

Claude Code hooks are adjacent, not the same thing

Claude Code hooks can run local shell commands on lifecycle events such as Stop, Notification, SessionStart, and UserPromptSubmit, according to Anthropic's hook documentation cited in the brief. They are useful for local automation and human alerts, but they are not MCP protocol notifications.

The distinction matters because hook-driven loops can look like background wake behavior while still being polling in disguise. The brief cites a community example that used a Stop hook to poll an inbox file. That can keep a session active, but it creates turn churn and fragile control flow.

The brief also cites an anecdotal Claude Code data point where one user saw 5,436 notification events out of 12,809 hook events, with 2,334 notification events, or 43 percent, being 60-second idle prompts. The exact numbers are community-reported and should be treated as anecdotal, but the lesson is practical: raw notification streams need filtering before they reach humans or agents.

A useful production checklist

Before calling a runtime "event-driven," check whether the wake path answers these questions:

  • What is the durable source of truth for work?
  • Which MCP notification types does the host request?
  • How does the host know a subscription was acknowledged?
  • What happens after reconnect?
  • How are duplicate events suppressed?
  • Which events are allowed to create an agent turn?
  • Which events require human approval?
  • How are missed notifications reconciled without burning model turns?
  • What is logged for audit and debugging?

The core idea is straightforward: MCP notifications are a transport-level signal that state changed. A background coding-agent runtime still needs a control plane that can decide whether that state change deserves agent work.

Build the wake path as an event system first and an agent feature second. Use subscriptions/listen to avoid tight polling, keep durable state outside the model loop, refetch before acting, and make every resume decision explicit. That is the difference between an event-driven runtime and a clever loop that happens to be quiet most of the time.

Get started

Deploy your fleet.

Put a fleet of sandboxed agents to work on your own infrastructure, provisioned in seconds and watched live from one console.

Get started →

Admin-provisioned · Self-host in one command · Your data never leaves your VM