MCP Server

Notifly MCP Server — this is an implementation of the Model Context Protocol (MCP) that allows AI assistants (Claude, GitHub Copilot and others) to control Notifly via a set of ready-made tools.

With the MCP server an AI assistant can:

• send notifications to channels;
• read, filter and delete messages;
• create and manage channels and clients;
• administer server users.

---

Installation

Requirements

• Go 1.21 or newer

Build from source

git clone https://github.com/notifly/mcp.git
cd mcp
go mod tidy
go build -o notifly-mcp .

The resulting binary notifly-mcp runs over a stdio transport — the MCP client launches it as a child process.

---

Configuration

The server is configured exclusively via environment variables:

Переменная	Обязательная	Описание
NOTIFLY_URL	✓	Base URL of the Notifly server, e.g. https://your-domain.com
NOTIFLY_APP_TOKEN		App token (prefix A) — for the send_message tool
NOTIFLY_CLIENT_TOKEN		An MCP code (prefix M) or a client token (prefix C) — for managing resources
NOTIFLY_USER		Login for Basic Auth (alternative to MCP code)
NOTIFLY_PASS		Password for Basic Auth

MCP codes (recommended)

An MCP code has the prefix M (22 characters after M). Create codes in the admin panel on the MCP page. For each code you can specify:

• Access level: read-only (read) or read+write (write);
• List of channels the code has access to (or “all”).

Access level affects available tools:

• a code with read access can call only “reading” tools — list_*, get_*, search_*;
• a code with write access can additionally call create_*, update_*, delete_*, send_*, as well as pause_*/resume_*, accept_*/decline_*, etc.

A write attempt with a read-only code will result in HTTP 403.

Unlike a regular client token, MCP codes do not have admin rights and can be revoked independently. Provide the obtained code in NOTIFLY_CLIENT_TOKEN — this variable accepts either an MCP code (M…) or a client token (C…).

Which token to use

• NOTIFLY_APP_TOKEN is needed only for sending messages (send_message).
• NOTIFLY_CLIENT_TOKEN (or the pair NOTIFLY_USER/NOTIFLY_PASS) is needed for all other operations.

You can provide both tokens at the same time.

---

Connecting to Claude Desktop

Open the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a mcpServers section:

{
  "mcpServers": {
    "notifly": {
      "command": "/usr/local/bin/notifly-mcp",
      "env": {
        "NOTIFLY_URL": "https://your-notifly-domain.com",
        "NOTIFLY_APP_TOKEN": "AGdjfk_L.dKe8q",
        "NOTIFLY_CLIENT_TOKEN": "CaQw5lL_L.yiRbN"
      }
    }
  }
}

After restarting Claude Desktop, the Notifly tools will appear in the interface.

---

Connecting to VS Code (GitHub Copilot)

Add to .vscode/mcp.json in the project root or to your VS Code user settings:

{
  "servers": {
    "notifly": {
      "type": "stdio",
      "command": "/usr/local/bin/notifly-mcp",
      "env": {
        "NOTIFLY_URL": "https://your-notifly-domain.com",
        "NOTIFLY_APP_TOKEN": "AGdjfk_L.dKe8q",
        "NOTIFLY_CLIENT_TOKEN": "CaQw5lL_L.yiRbN"
      }
    }
  }
}

---

Connecting to Cursor

Add .cursor/mcp.json in the project root (project-scope) or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "notifly": {
      "command": "/usr/local/bin/notifly-mcp",
      "env": {
        "NOTIFLY_URL": "https://your-notifly-domain.com",
        "NOTIFLY_APP_TOKEN": "AGdjfk_L.dKe8q",
        "NOTIFLY_CLIENT_TOKEN": "CaQw5lL_L.yiRbN"
      }
    }
  }
}

After saving, Cursor will pick up the server automatically. Make sure notifly-mcp is available in PATH.

---

Connecting to Windsurf

Open or create ~/.codeium/windsurf/mcp_config.json and add a mcpServers section:

{
  "mcpServers": {
    "notifly": {
      "command": "/usr/local/bin/notifly-mcp",
      "env": {
        "NOTIFLY_URL": "https://your-notifly-domain.com",
        "NOTIFLY_APP_TOKEN": "AGdjfk_L.dKe8q",
        "NOTIFLY_CLIENT_TOKEN": "CaQw5lL_L.yiRbN"
      }
    }
  }
}

After saving, restart Windsurf — the Notifly tools will appear in Cascade.

---

Connecting to Claude Code (CLI)

Use the claude mcp add command to register the server:

claude mcp add notifly /usr/local/bin/notifly-mcp \
  -e NOTIFLY_URL=https://your-notifly-domain.com \
  -e NOTIFLY_CLIENT_TOKEN=CaQw5lL_L.yiRbN

The --scope user flag adds the server globally for all projects (by default — project-scope). To list added servers: claude mcp list.

---

Connecting to Codex CLI

Open or create ~/.codex/config.toml and add the section:

[[mcp_servers]]
name = "notifly"
command = "/usr/local/bin/notifly-mcp"
env = { NOTIFLY_URL = "https://your-notifly-domain.com", NOTIFLY_CLIENT_TOKEN = "CaQw5lL_L.yiRbN" }

After saving, Codex will pick up the server on next start. Make sure notifly-mcp is available in PATH.

---

Connecting to Zed

Open the Zed settings file (~/.config/zed/settings.json) and add a context_servers section:

{
  "context_servers": {
    "notifly": {
      "command": {
        "path": "/usr/local/bin/notifly-mcp",
        "args": [],
        "env": {
          "NOTIFLY_URL": "https://your-notifly-domain.com",
          "NOTIFLY_CLIENT_TOKEN": "CaQw5lL_L.yiRbN"
        }
      }
    }
  }
}

Zed will pick up the server without a restart.

---

Connecting to Continue

Add a mcpServers section to the Continue config (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "notifly",
      "command": "/usr/local/bin/notifly-mcp",
      "env": {
        "NOTIFLY_URL": "https://your-notifly-domain.com",
        "NOTIFLY_CLIENT_TOKEN": "CaQw5lL_L.yiRbN"
      }
    }
  ]
}

Continue is supported as an extension for VS Code and JetBrains IDEs.

---

Available tools

Server information

Tool	Description
get_health	Check server and database health
get_version	Get version, commit and build date
get_server_info	Get server flags (registration, OIDC)

Messages

Tool	Parameters	Description
send_message	message*, title, priority	Send a notification (requires NOTIFLY_APP_TOKEN)
list_messages	limit, since	List all messages with pagination
list_application_messages	app_id*, limit, since	Messages of a specific channel
delete_message	id*	Delete a message by ID
delete_all_messages	—	Delete all messages
delete_application_messages	app_id*	Delete all messages of a channel
search_messages	q*, app_id, limit, since	Search messages by text (min. 2 characters); across all channels or in one
mark_messages_read	ids*	Mark messages as read (JSON array of IDs, e.g. [1,2,3])

Questions (ask) — human-in-the-loop

Tool	Parameters	Description
ask_question	question*, options, title, timeout_sec, default_answer, allow_multi, json_format, client_message_id	Ask a human a question (push/Telegram/email with buttons); returns the question id. Requires NOTIFLY_APP_TOKEN. See Questions (Ask)
get_ask_answer	id*, wait_sec	Fetch the answer; with wait_sec > 0 — wait for it (polls every 3 s, up to 300 s). Returns answered+answer, pending, expired or cancelled. Requires NOTIFLY_APP_TOKEN
cancel_ask_question	id*	Cancel a pending question

The ask_question → get_ask_answer(wait_sec) pair is a ready-made approval gate for an AI agent: ask a human for permission and continue based on the answer.

Channels

Tool	Parameters	Description
list_applications	—	List all channels
create_application	name*, description, default_priority	Create a channel
update_application	id*, name, description, default_priority	Update a channel
delete_application	id*	Delete a channel

Clients

Tool	Parameters	Description
list_clients	—	List all clients (devices/tokens)
create_client	name*	Create a client and obtain a client token
update_client	id, name	Rename a client
delete_client	id*	Delete a client (revoke token)

Users

Tool	Parameters	Description
get_current_user	—	Information about the current user
list_users	—	List all users (requires admin)
get_user	id*	Get a user by ID (admin)
create_user	name, pass, admin	Create a user (admin)
delete_user	id*	Delete a user (admin)
request_password_reset	email*	Request a password reset — a link with a token will be sent to the email (public, no auth)
confirm_password_reset	token, new_password	Confirm reset: set a new password using the token from the email

Heartbeats (control signals)

More about heartbeats — see the Heartbeat page.

Tool	Parameters	Description
list_heartbeats	—	List heartbeat notifications (dead-man switch)
create_heartbeat	appid, name, intervalSec, alertMessage, graceSec, alertTitle, alertPriority, recoveryTitle, recoveryMessage	Create a heartbeat. intervalSec ≥ 30; an alert is sent if a ping hasn’t arrived within intervalSec+graceSec seconds; alertPriority defaults to 8
update_heartbeat	id, name, intervalSec, alertMessage, graceSec, alertTitle, alertPriority, recoveryTitle, recoveryMessage	Update heartbeat settings
delete_heartbeat	id*	Delete a heartbeat
pause_heartbeat	id*	Pause (alerts will not be sent until resume_heartbeat)
resume_heartbeat	id*	Resume a paused heartbeat
ping_heartbeat	ping_token*	Send a ping using a public ping token (as an app would from cron)

Monitors

More about active checks — see the Monitors page.

Tool	Parameters	Description
list_monitors	—	List active monitors (HTTP URLs and TCP ports)
create_monitor	appid, name, kind, target, intervalSec, alertMessage, timeoutSec, expectedStatus, consecutiveFails, alertTitle, alertPriority, recoveryTitle, recoveryMessage	Create a monitor. kind = http (then target is a URL) or tcp (target is host:port). intervalSec 30–86400; timeoutSec defaults to 10; expectedStatus 0 = “any 2xx”; consecutiveFails defaults to 1 (max. 20); alertPriority defaults to 8
update_monitor	id, name, kind, target, intervalSec, alertMessage, timeoutSec, expectedStatus, consecutiveFails, alertTitle, alertPriority, recoveryTitle, recoveryMessage	Update monitor settings
delete_monitor	id*	Delete a monitor
pause_monitor	id*	Pause (checks will not run until resume_monitor)
resume_monitor	id*	Resume a paused monitor

Channel sharing (shares)

More — see the Channel sharing page.

Tool	Parameters	Description
list_channel_shares	app_id*	List share tokens (delegations) for a channel; available to the owner or a user with send permission
create_channel_share	app_id, permission, recipient_email, note	Create a delegation. permission = view (read) or send (read + send); an empty recipient_email = an open token
update_channel_share	id, permission, recipient_email, note	Change recipient email, access level or note (owner only)
delete_channel_share	id*	Revoke a share token (delete the delegation)
list_incoming_shares	—	Channels the current user has been granted access to (incoming shares by email)
accept_share	id*	Accept an incoming delegation (status → active)
decline_share	id*	Decline an incoming delegation
join_share_by_token	token*	Join a channel by share token (prefix S)

Device subscriptions

Tool	Parameters	Description
get_client_subscriptions	client_id*	Channels the device is subscribed to by client ID
set_client_subscriptions	client_id, app_ids	Set the full list of device subscriptions; app_ids is a JSON array of IDs, e.g. [1,2,3] (replaces current)
get_my_subscriptions	—	Subscriptions of the current device (authorize with device token via NOTIFLY_CLIENT_TOKEN)
subscribe_to_channel	app_id*	Subscribe the current device to a channel
unsubscribe_from_channel	channel_id*	Unsubscribe the current device from a channel

Account and billing

Tool	Parameters	Description
get_quota_breakdown	day	Detailed breakdown of event quota usage for a day (YYYY-MM-DD, default — today in MSK)
topup_balance	amount_rubles*	Top up balance (integer ≥ 1; admin only, others will receive payment details)

* — required parameter

---

Examples

Send a notification via Claude

Отправь уведомление в Notifly с заголовком "Деплой завершён"
и текстом "Версия 2.1.0 успешно развёрнута на prod" с приоритетом 7.

Claude will call the send_message tool automatically.

Channel management

Покажи список всех каналов в Notifly и последние 10 сообщений
из канала с ID 3.

Claude will call list_applications and then list_application_messages sequentially.

Administration

Создай нового пользователя в Notifly с именем "devops"
и паролем "securepass", без прав администратора.

Claude will call create_user with the required parameters.

---

Security

Token storage

Do not include tokens or passwords in the text of requests to the AI assistant. Always use environment variables in the MCP client’s configuration file.

• The MCP server runs locally over stdio — no network port is opened.
• Tokens are stored only in the process environment variables.
• The delete_all_messages and delete_user tools perform irreversible operations — the AI assistant should request confirmation before calling them.