Add a Notification Tool to Any MCP Agent in 5 Minutes

Your agent ran for 25 minutes, hit a question at minute four, and then sat there. Waiting. You found out when you tabbed back, 40 minutes of nothing, because it had the whole toolset at its disposal and no way to tap you on the shoulder.

That's the gap. Agents run async now (you start a job and switch tasks), but almost none of them can reach past the terminal they're running in. They'll call APIs, edit files, open PRs, and still have no way to say "hey, I'm stuck" to the one device you actually check. The missing tool is a push notification to your phone.

There are two ways to add that, and which one you want depends on how your agent is built. If it's an MCP client you didn't write (Claude, Cursor, OpenClaw, Hermes), you plug in a hosted MCP notification server and you're done. If you're building the agent yourself, you write a tiny tool that wraps a single HTTP call. Both take about five minutes. Here's both.

Test it in one line first

Before you wire anything into an agent, prove the notification actually lands. Sign in with Apple at thenotification.app, create an app, copy its app_key, and fire one request:

curl -X POST https://thenotification.app/api/sendNotification \
  -H "app_key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Agent test", "body": "If you got this, the tool works."}'

A 200 with {"success": true, ...} and a buzz in your pocket means the plumbing is good. Now you're just deciding how the agent calls it.

Path 1: plug in the hosted MCP server

If your agent already speaks MCP, you don't write any code at all. TheNotificationApp runs a hosted MCP server, and connecting it hands your agent a send_notification tool it can call on its own.

In a GUI client like Claude or Cursor: open Settings → Connectors → Add custom connector, then fill in:

Name:        thenotification.app
Server URL:  https://thenotification.app/mcp

OAuth Client ID:     (leave blank)
OAuth Client Secret: (leave blank)

Click Connect, then Sign in with Apple. No API key to paste, no secret to leak into a config file, auth is short-lived tokens through Apple. The full walkthrough with screenshots lives in the MCP docs, and there's a Claude-specific version if that's your client.

For a config-file client, it's the same server URL in your mcpServers block:

{
  "mcpServers": {
    "thenotification": {
      "url": "https://thenotification.app/mcp"
    }
  }
}

Reload, run the sign-in flow your client prompts, and the tool appears. Now "notify me when the migration finishes" is something your agent can actually do, on its own, without you babysitting the run.

Path 2: building the agent yourself? Write the tool

If you're rolling your own agent (a plain Python loop, the Claude Agent SDK, the OpenAI Agents SDK, LangChain, whatever), you don't need MCP transport at all. A tool is just a function, and this one wraps a single POST:

import os
import requests

def send_notification(title: str, body: str, link: str | None = None) -> str:
    """Send a push notification to the user's iPhone. Call this the moment a
    long task finishes, fails, or needs a human decision - don't wait to be asked."""
    payload = {"title": title, "body": body}
    if link:
        payload["link"] = link

    resp = requests.post(
        "https://thenotification.app/api/sendNotification",
        headers={
            "app_key": os.environ["NOTIFICATION_API_KEY"],
            "Content-Type": "application/json",
        },
        json=payload,
    )
    resp.raise_for_status()
    return resp.json()["message"]

Register that as a tool in your framework and you're done. The endpoint, headers, and body are the same ones in the API reference and the Python quickstart: there's nothing agent-specific about the call itself.

One small upgrade worth making: pass a link. When your agent opens a pull request or finishes a deploy, put that URL in the field and the notification becomes tappable: one tap from your lock screen straight to the thing that needs you. For an agent, that's the difference between "something happened" and "here's exactly where."

The description is the real work

Here's the part people skip. The model never reads your function body. It reads the docstring. That description is the only thing telling the agent when to reach for the tool. "Sends a notification" gets you an agent that never fires it. "Call this the moment a long task finishes, fails, or needs a human decision" gets you one that actually pings you.

Treat the description like a prompt, because that's what it is. Spell out the trigger conditions, and (if you want fewer interruptions), the ones to skip: "don't notify on progress updates, only on terminal states." That one sentence is the difference between a useful tool and a chatty one.

Sharing it across agents? Wrap it in your own MCP server

If you run several agents and want the same tool everywhere, put it behind your own MCP server. It's about fifteen lines with FastMCP:

from mcp.server.fastmcp import FastMCP
import os, requests

mcp = FastMCP("notifications")

@mcp.tool()
def send_notification(title: str, body: str, link: str = "") -> str:
    """Send a push notification to the user's iPhone when a task is done or blocked."""
    payload = {"title": title, "body": body}
    if link:
        payload["link"] = link
    r = requests.post(
        "https://thenotification.app/api/sendNotification",
        headers={"app_key": os.environ["NOTIFICATION_API_KEY"],
                 "Content-Type": "application/json"},
        json=payload,
    )
    r.raise_for_status()
    return r.json()["message"]

if __name__ == "__main__":
    mcp.run()

Point any MCP client at it and every agent you run gets the same notification tool. This is the DIY version of the hosted server from Path 1: worth it when you want your own key, your own logging, or a tool description tuned to one specific workflow.

The honest part

One caveat worth knowing up front: the free tier is 100 notifications total: lifetime, not per month. An agent that fires on every retry inside a loop can burn through that before lunch. So guard the call: only notify on terminal states, or add a counter so a runaway loop can't spam you. If you're running agents daily, Pro is $2.99/month for 1,000 notifications a month, which is a saner fit for anything automated.

If you do go over, the API doesn't fail silently. It returns a 429 with the limit and how many you've sent, so a well-behaved agent can read that back and stop hammering instead of looping forever. Handle it the same way you'd handle any rate limit: catch it, back off, move on.

That's the whole thing: one tool, one endpoint, and your agent can finally tell you when it's done instead of waiting in silence. Grab a free key at thenotification.app and wire it into your next run.

New to this? Start with what an MCP server is.