Bridges MCP
Connects Telegram conversations to a Codex chat, providing tools to send text, images, and files, download attachments, and maintain typing status.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Bridges MCP
Bridges is a shared MCP server that routes messaging connections into logical agent sessions. Connections can share a session, conversation history, and settings. Replies use explicit destinations and are never automatically broadcast.
Session routing, persistence, admin commands, and messaging tools are independent of the agent harness. Harness adapters implement conversation creation/loading, input delivery, model catalogs, and turn lifecycle. The bundled adapter supports Codex App Server over a protected local Unix WebSocket. Other harnesses need an adapter implementing the same interface.
Install
Requires Python 3.11+ on Linux or macOS.
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'See configuration, the example, admin commands, and validation.
Related MCP server: Telegram MCP Server
Configure
Give each backend a clients entry with an adapter, socket path, and token_env
naming a unique MCP bearer token of at least 32 characters. Keep credentials in
environment variables, never YAML or command arguments. MCP binds to loopback.
Define logical sessions, each selecting a client, absolute workspace cwd, and
optional model/effort defaults. Every messaging connection references a stable
session_id. Multiple connections can reference the same logical session.
clients:
assistant:
adapter: codex-app-server
token_env: ASSISTANT_MCP_TOKEN
socket_path: /run/assistant/harness.sock
sessions:
personal:
client: assistant
cwd: /srv/assistant
telegram:
bots:
main:
token_env: TELEGRAM_BOT_TOKEN
admin: true
connections:
personal_telegram:
bot: main
chat_id: "123456789"
session_id: personal
allow_admin: truebridges discover-telegram --config /absolute/path/config.yaml --bot main
bridges validate --config /absolute/path/config.yaml
bridges serve --config /absolute/path/config.yamlOne process polls each configured bot. Process locks prevent duplicate listeners sharing a state directory. Bridges never removes webhooks automatically. Group visibility depends on Telegram privacy settings and permissions.
Shared sessions
A logical session_id is a stable Bridges name. Its backend conversation pointer,
thread_id, is stored once in <state_dir>/sessions.json. Downloads always use
<state_dir>/downloads. Each process uses its own state_dir and HTTP port; no
instance identifier or download-directory override is required.
On incoming messages:
Null pointer: create a conversation, save the pointer, and deliver the message.
Existing loaded conversation: deliver normally.
Existing unloaded conversation: load that same conversation before delivery.
Confirmed deleted/missing conversation: create one replacement for the group.
Temporary or unclassified failure: preserve the pointer rather than replace history.
Creation sends no initialization prompt. The actual incoming message starts the first turn. Each logical session has a bounded queue and lock; shared connections cannot race creation/replacement, while independent sessions progress concurrently. There is no durable inbox or automatic retry of ambiguous submissions.
A durable pending marker prevents repeated automatic creation after a lost
acknowledgement or interrupted final save. Inspect backend state before explicitly
using /new_session to recover uncertain creation. Corrupt state fails startup.
Telegram is the implemented messaging transport. Additional transports can route through the same session manager. Scheduled prompts use the cron bridge below.
Admin commands
Both bot admin and connection allow_admin must be true; both default to false.
Recognized commands are handled by Bridges and never become model prompts.
/context: show the last reported context usage and observed compaction count./new_session: create an empty conversation and replace the shared pointer for every connection in the logical session. Previous history remains saved./model [model]: show choices/current model or save a model for the shared session./thinking [level]: show choices/current reasoning effort or save a supported level.
Settings persist and apply on the next idle turn, including new conversations in the same logical session. Availability comes from the backend's model catalog. At startup Bridges configures bot commands, permitted chat scopes, and private-chat menu buttons.
MCP tools and messages
With Telegram connections configured, the server exposes get_protocol_docs,
telegram_send_text, telegram_send_images, telegram_send_file,
telegram_download_images, and telegram_download_file, plus add_job,
list_jobs, get_job_prompt, delete_job, pause_job, and resume_job. There is no agent-controlled
focus or session-management MCP tool.
Bearer authentication selects the backend. Host metadata identifies the calling conversation; outbound tools verify it is loaded in that backend. Outbound destinations are explicit and do not change session mappings.
Incoming messages carry fenced YAML bridge_context metadata and unchanged body
text. Required fields are bridge, connection_id, message_id, and received_at.
Replies include reply_to_message_id. Attachments use bounded, connection-scoped,
ephemeral handles. Audio is not transcribed. File paths are local to the bridge host.
Ordinary assistant prose is not forwarded to Telegram: use send tools and select
the originating connection. Caller text/captions keep their MarkdownV2 formatting.
Escape literal punctuation according to Telegram's rules. Context usage appears only
when requested with /context. See context usage for
freshness, compaction counting, and length limits. Uncertain sends are not retried;
partial image batches report completed IDs and the failed index.
Typing starts automatically after accepted incoming delivery and stops when the owning turn completes, changes, disconnects, or its shared session is replaced. Slow typing requests do not block delivery. Bridges preserves backend approval/input policy and never answers approval requests on the user's behalf.
Scheduled prompts
APScheduler 3 runs persistent jobs using SQLite and five-field Unix cron expressions. Jobs belong to a connection and submit prompts to its current session, including normal automatic creation and stale-pointer recovery. They do not post the prompt to external chat or trigger typing indicators.
add_job(connection_id, name, pattern, prompt) returns an assigned id.
list_jobs(connection_id?) returns only id, name, pattern, and status
(active or paused). The remaining four scheduling tools accept only id.
Set cron.timezone to an IANA timezone; default UTC. Missed occurrences while
stopped or paused are skipped. See cron behavior.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Agent communication platform for agent to agent messaging via MCP. Messages, channels, skills.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to send messages and interact with Telegram chats through MCP tools, with support for user management, conversation history, and bot command handling.1-
- AlicenseNot gradedqualityDmaintenanceEnables sending and receiving Telegram messages through MCP clients like Claude Desktop and Gemini Spark.35 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables an AI agent to send Telegram chat messages, maintain per-chat memory, and schedule per-thread tasks through MCP.3-
- FlicenseNot gradedqualityCmaintenanceEnables LLM agents to control Telegram userbot operations through MCP, including chat and message management, media sending, search, contacts, moderation, dynamic raw Kurigram MTProto calls, and a persistent Codex app-server bridge via Telegram commands.7-