# MCP Server

> Alphorn MCP server: give Claude Code, Claude Desktop, Cursor, Codex, and other MCP clients a send_notification tool that reaches Slack, Telegram, email, or SMS.

Source: https://docs.alphorn.dev/ai-agents/mcp/

The Alphorn MCP server gives any [MCP](https://modelcontextprotocol.io) client a `send_notification` tool. Unlike [hooks](/ai-agents/claude-code), which fire on fixed events, the agent decides when a notification is worth sending: when a long task finishes, when it is blocked on a decision, or when you ask it to ping you.

The package is [`@alphorn/mcp`](https://www.npmjs.com/package/@alphorn/mcp) and runs locally with `npx` (Node.js 20 or later).

## Configuration

Create a webhook (see [Webhooks](/webhooks)) and pass its **Endpoint URL** (plus its API key, if you switched on **Require API key**) as environment variables:

| Variable | Value |
|---|---|
| `ALPHORN_WEBHOOK_URL` | Endpoint URL, for example `https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT`. Self-hosted instances use their own base URL. |
| `ALPHORN_API_KEY` | Webhook API key (`alp_...`). Leave it unset if the webhook does not require a key. |

## Claude Code

```bash
claude mcp add alphorn -s user \
  -e ALPHORN_WEBHOOK_URL=https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT \
  -e ALPHORN_API_KEY=alp_... \
  -- npx -y @alphorn/mcp
```

## Claude Desktop (one-click bundle)

Download `alphorn.mcpb` from the [latest release](https://github.com/alphorn-dev/mcp/releases/latest) and open it. Claude Desktop asks for the Endpoint URL and API key and installs the server.

## Claude Desktop, Cursor, and other clients

Add to `claude_desktop_config.json`, `~/.cursor/mcp.json`, or your client's MCP config:

```json
{
  "mcpServers": {
    "alphorn": {
      "command": "npx",
      "args": ["-y", "@alphorn/mcp"],
      "env": {
        "ALPHORN_WEBHOOK_URL": "https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT",
        "ALPHORN_API_KEY": "alp_..."
      }
    }
  }
}
```

## OpenAI Codex CLI

```toml
# ~/.codex/config.toml
[mcp_servers.alphorn]
command = "npx"
args = ["-y", "@alphorn/mcp"]
env = { ALPHORN_WEBHOOK_URL = "https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT", ALPHORN_API_KEY = "alp_..." }
```

## The `send_notification` tool

| Argument | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | What happened and what the agent needs from you (max 4,000 characters) |
| `title` | string | no | Short title, e.g. `my-app - tests passing` (max 200 characters) |
| `priority` | integer 1-5 | no | 2 = finished, 3 = needs input, 4 = blocked or failed, 5 = urgent |
| `tags` | string[] | no | Tags to filter and route on in Alphorn, e.g. `["ai-agent", "completed"]` |

Use Alphorn's [filters](https://docs.alphorn.dev/filtering/) to decide where each notification goes, for example SMS only for priority 4 and above.

The tool returns the `messageId` on success. On errors it tells the agent what went wrong in plain words (for example an invalid API key, a disabled webhook, or an exhausted [quota](/api-reference#quotas)), so the agent can report it instead of retrying.

Route notifications with [filters](/filtering), for example Priority **greater than** 3 to SMS and Tags **has any of** `completed` to Slack. See [AI Agent Notifications](/ai-agents) for the recommended priorities and tags.