Event System

mcp2cli delivers runtime events (progress, server logs, job updates, auth prompts) through configurable sinks — stderr, HTTP webhooks, Unix sockets, SSE, or custom commands.

Event Types

Sink Configuration

Configure event sinks in your config YAML. Multiple sinks can be active simultaneously:

events:
  enable_stdio_events: true                              # stderr (default: on)
  http_endpoint: "http://127.0.0.1:9090/events"         # HTTP webhook
  local_socket_path: "/tmp/mcp2cli-events.sock"         # Unix socket
  sse_endpoint: "127.0.0.1:9091"                        # SSE server
  command: "logger -t mcp2cli '${MCP_EVENT_MESSAGE}'"   # Shell command

Sink Types

Stderr (Default)

Human-readable event lines on stderr. Always on unless disabled.

events:
  enable_stdio_events: true    # true by default

Output:

[progress] Deploying: 45% complete
[server_log] INFO: Connection pool warmed up
[info] Discovery cache refreshed (14 capabilities)

HTTP Webhook

POST JSON events to an HTTP endpoint:

events:
  http_endpoint: "http://127.0.0.1:9090/events"

Payload:

{
  "type": "progress",
  "app_id": "work",
  "message": "Deploying: 45% complete",
  "data": {
    "progress": 0.45,
    "total": 1.0
  }
}

Use cases: monitoring dashboards, alerting systems, audit logs.

Unix Domain Socket

NDJSON events written to a Unix socket:

events:
  local_socket_path: "/tmp/mcp2cli-events.sock"

Each event is one JSON line:

{"type":"progress","app_id":"work","message":"Deploying: 45%","data":{}}
{"type":"info","app_id":"work","message":"Deploy complete","data":{}}

Use cases: local monitoring tools, IPC with other services, real-time dashboards.

SSE Server

Starts an SSE (Server-Sent Events) HTTP server that streams events:

events:
  sse_endpoint: "127.0.0.1:9091"

Connect from a browser or curl:

curl -N http://127.0.0.1:9091/events

data: {"type":"progress","app_id":"work","message":"45%"}

data: {"type":"info","app_id":"work","message":"Done"}

Use cases: web UIs, browser-based monitoring, real-time event feeds.

Command Execution

Run a shell command for each event with environment variables:

events:
  command: "notify-send 'mcp2cli' '${MCP_EVENT_MESSAGE}'"

Use cases: desktop notifications, custom logging, Slack/Teams integration.

# Slack webhook example
events:
  command: |
    curl -s -X POST "$SLACK_WEBHOOK" \
      -H 'Content-Type: application/json' \
      -d "{\"text\": \"[${MCP_EVENT_TYPE}] ${MCP_EVENT_MESSAGE}\"}"

Event Flow

graph TB
    subgraph "Sources"
        SERVER["MCP Server<br/>notifications/progress<br/>notifications/message<br/>notifications/tools/list_changed"]
        RUNTIME["mcp2cli Runtime<br/>job updates, auth prompts, info"]
    end

    subgraph "Event Broker"
        BROKER["EventBroker<br/>Dispatches to all sinks"]
    end

    subgraph "Sinks"
        STDERR["Stderr Sink<br/>Human-readable lines"]
        HTTP["HTTP Webhook<br/>POST JSON"]
        UNIX["Unix Socket<br/>NDJSON"]
        SSE["SSE Server<br/>text/event-stream"]
        CMD["Command Exec<br/>Shell + env vars"]
    end

    SERVER --> BROKER
    RUNTIME --> BROKER
    BROKER --> STDERR
    BROKER --> HTTP
    BROKER --> UNIX
    BROKER --> SSE
    BROKER --> CMD

Server Notification Mapping

MCP server notifications are automatically mapped to events:

Monitoring Recipe

Real-time terminal dashboard

# Start an SSE-based event monitor in one terminal
curl -sN http://127.0.0.1:9091/events | jq --unbuffered '.'

# Run commands in another terminal
work deploy --version 2.0 --background
work jobs watch --latest

Log to file

events:
  command: "echo \"$(date -Iseconds) [${MCP_EVENT_TYPE}] ${MCP_EVENT_MESSAGE}\" >> /var/log/mcp2cli.log"

See Also

• Background Jobs — job_update events
• Configuration Reference — full events config
• Shell Scripting with MCP — event-driven pipelines