Telegram Adapter

Overview

The Telegram adapter maps the Telegram WebApp SDK to MCP Apps protocol, providing:

Theme synchronization (light/dark)
Viewport and safe area insets
Authentication via initData (HMAC-SHA256)
Lifecycle events (activation, deactivation)
Native link opening

Setup

import { TelegramPlatformAdapter } from "@casys/mcp-bridge";

// Client-side: runs inside the Telegram Mini App WebView
const adapter = new TelegramPlatformAdapter();
const hostContext = await adapter.initialize();

Theme Mapping

Telegram themes are automatically mapped to MCP host context:

Telegram	MCP Host Context
`colorScheme: "dark"`	`{ theme: "dark" }`
`colorScheme: "light"`	`{ theme: "light" }`
`themeParams.bg_color`	`backgroundColor`
`themeParams.text_color`	`textColor`

Authentication

The adapter validates Telegram initData using HMAC-SHA256:

Telegram sends initData query string with user info
The adapter verifies the signature using your bot token
Valid sessions receive a crypto-secure session token
Invalid requests are rejected with 401

Viewport & Safe Areas

The adapter reports Telegram’s viewport dimensions and safe area insets, which your MCP App receives via host-context-changed notifications.