Webhook MCP Server for Model Context Notifications

Overview

This Webhook MCP (Model Context Protocol) server receives MCP-style notifications and immediately forwards them to configured webhooks. It acts as a lightweight relay that lets model orchestration systems or other services push contextual events (user state, metadata, or other model inputs) and have those events dispatched to downstream systems in real time.

The server is useful when you want to integrate model context events into existing services that accept webhooks (logging systems, feature stores, orchestration layers, or agent controllers). It supports simple registration of webhook endpoints, secure delivery via HMAC signatures, and a minimal HTTP API for pushing and managing notifications.

Features

• Receive MCP notifications via a simple HTTP API
• Forward notifications to one or more configured webhooks
• HMAC signature support for payload verification by receivers
• Basic webhook registration and management (add / remove / list)
• Health and status endpoints for monitoring
• Retry/backoff behavior and logging for failed deliveries
• Easy to run locally or inside a container

Installation / Configuration

Clone the repository and run with Docker or locally. The examples below show a generic startup pattern (adjust to the actual runtime in the repository).

Clone and run locally (example using Node/npm):

git clone https://github.com/noobnooc/webhook-mcp.git
cd webhook-mcp
npm install
# start with environment variables configured
PORT=8080 AUTH_TOKEN="secret-token" LOG_LEVEL=info npm start

Run with Docker:

# build
docker build -t webhook-mcp .

# run
docker run -e PORT=8080 \
  -e AUTH_TOKEN="secret-token" \
  -e HMAC_SECRET="supersecret" \
  -p 8080:8080 \
  webhook-mcp

Example docker-compose.yml:

version: '3.8'
services:
  webhook-mcp:
    image: webhook-mcp:latest
    ports:
      - "8080:8080"
    environment:
      PORT: 8080
      AUTH_TOKEN: "secret-token"
      HMAC_SECRET: "supersecret"
      LOG_LEVEL: "info"

Common environment variables

• PORT — port the server listens on (default 8080)
• AUTH_TOKEN — token required for management or push endpoints
• HMAC_SECRET — secret used to sign outgoing webhook payloads
• LOG_LEVEL — debug|info|warn|error

Available Resources

API Endpoints

Sample MCP notification payload:

{
  "id": "evt_12345",
  "timestamp": "2026-04-10T12:34:56Z",
  "type": "model.context.update",
  "context": {
    "user_id": "user_987",
    "conversation_id": "conv_123",
    "metadata": {
      "plan": "pro",
      "locale": "en-US"
    }
  }
}

Signature header

• The server signs outgoing payloads with HMAC-SHA256 and includes a header such as X-MCP-Signature: sha256=<hex> to let receivers verify authenticity.

Verification snippet (Node.js):

const crypto = require('crypto');

function verifySignature(body, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader || ''));
}

Use Cases

• Real-time personalization: when a user’s profile or context changes, push an MCP event to update feature stores and downstream model adapters (for next-token scoring or reranking).
• Agent orchestration: notify an agent controller with the latest conversation context so it can decide which tool or skill to invoke next.
• Audit and observability: forward model context events to logging or SIEM systems to maintain an audit trail of inputs sent to models.
• Notification fan-out: send a single MCP event to many services (recommendation engine, search re-ranker, analytics, and monitoring) without each producer needing to know every target endpoint.
• Training-data pipelines: capture contextual events as labeled metadata for offline model training or evaluation.

Example: Pushing a notification

Register a webhook:

curl -X POST "http://localhost:8080/webhooks/register" \
  -H "Authorization: Bearer secret-token" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/mcp-receiver","name":"example-receiver"}'

Send an MCP event:

curl -X POST "http://localhost:8080/mcp" \
  -H "Authorization: Bearer secret-token" \
  -H "Content-Type: application/json" \
  -d '{"id":"evt_123","type":"model.context.update","context":{"user_id":"u1"}}'

The server will forward the event to registered URLs and include X-MCP-Signature so receivers can verify integrity.

Where to find the code

Source code and issues are available on GitHub: https://github.com/noobnooc/webhook-mcp

For contribution guidelines, runtime details, and implementation-specific options consult the repository README and source files.