Channels MCP

Channels MCP is a remote Model Context Protocol server that lets agents send structured notifications without learning delivery credentials or recipient addresses. It runs independently in Docker and is designed primarily for OpenCode.

The initial provider is SMTP. Multiple configured channels can use the same SMTP provider, allowing separate outgoing accounts such as work and private email.

MCP Tools

• list_recipients returns public recipient IDs, names, and available channel IDs.

• list_channels returns configured channel instances and can filter them by recipient.

• send_notification accepts a recipient, concrete channel, and structured message.

The server never returns delivery addresses, SMTP settings, credential names, or credentials through MCP.

Related MCP server: agent-notify

Message Format

Agents send structured content rather than raw HTML:

{
  "recipientId": "max",
  "channelId": "work-email",
  "message": {
    "title": "Task is taking longer",
    "summary": "The analysis is still running.",
    "details": ["Current step: test execution", "No errors have occurred"],
    "actions": [
      {
        "label": "Open logs",
        "url": "https://example.org/logs/123"
      }
    ],
    "attachments": [
      {
        "filename": "report.txt",
        "contentType": "text/plain",
        "contentBase64": "cmVwb3J0IGNvbnRlbnRz"
      }
    ]
  }
}

The server escapes all content and renders both HTML and plain text. Action URLs are restricted to HTTP and HTTPS. Attachments contain raw file bytes encoded as Base64, without a data: URL prefix. Filenames must not contain paths or control characters. A message may contain up to 5 attachments, with a maximum decoded size of 5 MiB per file and 10 MiB in total.

Configuration

Every .yaml or .yml file directly inside config/ is loaded at startup. Files are classified by kind. Missing or unknown kinds, invalid schemas, missing credentials, duplicate IDs, and invalid channel references stop startup with an error.

Channels

Each channel declares its stable id in YAML. Filenames are used only for discovery and error messages, so files may be renamed without changing recipient mappings. Provider type and channel ID are deliberately different concepts: any number of channel files can use type: smtp.

config/work-email.yaml:

kind: channel
id: work-email
type: smtp
displayName: Work Email
from: "Agent Work <agent@company.example>"
host: smtp.company.example
port: 587
secure: false
auth:
  userEnv: WORK_SMTP_USER
  passEnv: WORK_SMTP_PASS

Credentials stay in environment variables. userEnv and passEnv contain variable names, not credential values.

Recipients

Recipient delivery details are keyed by concrete channel ID:

config/max.yaml:

kind: recipient
id: max
displayName: Max Mustermann
channels:
  work-email:
    email: max@company.example
  private-email:
    email: max@example.org

Restart the container after changing configuration. Hot reload is not implemented.

Docker Deployment

1. Copy the environment template and replace every placeholder:

   cp .env.example .env

2. Replace the example YAML files in config/ with your channel and recipient definitions.

3. Start the long-running service:

   docker compose up -d --build

4. Check its health:

   curl http://127.0.0.1:3000/health

The Compose service publishes port 3000 by default. Set CHANNELS_PORT to change the host-side port. CHANNELS_ALLOWED_HOSTS should list every hostname or IP address clients use to reach the server, plus localhost and 127.0.0.1 for local health checks.

OpenCode

Set CHANNELS_MCP_TOKEN in the environment that starts OpenCode. It must equal the server token. Then add the remote server to the appropriate opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "channels": {
      "type": "remote",
      "url": "http://192.168.1.50:3000/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:CHANNELS_MCP_TOKEN}"
      }
    }
  }
}

Use the actual hostname or LAN IP of the Docker host. Do not put the token directly in opencode.json. Quit and restart OpenCode after changing its configuration because OpenCode does not hot-reload MCP settings.

Bearer authentication does not encrypt traffic. Plain HTTP is appropriate only on a trusted network. Use HTTPS through a reverse proxy when traffic can cross an untrusted network.

Development

Requires Node.js 20 or newer.

npm ci
npm run verify

Tests use injected transports and never contact a real SMTP server.

Endpoints

• POST /mcp serves MCP Streamable HTTP. Legacy stateless requests used by current OpenCode releases are supported by the SDK.

• GET /mcp and DELETE /mcp are handled according to the negotiated MCP protocol and require authentication.

• GET /health returns public process health for Docker and operators.