Privacy

Privacy and data handling

What this service stores, for how long, who can access it, and how to remove it. See /security for the threat model.

Claude, ChatGPT and other MCP users

When you connect MCTL to Claude, ChatGPT, or another MCP client, the following data flows apply:

User-authorized account access: this service operates only on the Telegram account you explicitly connect. It is MCTL Assistant, an unofficial third-party connector using the Telegram API, and an independent project: it is not affiliated with, endorsed by, or operated by Telegram, Anthropic, or OpenAI.
Through your MCP client: your prompts, MCP tool arguments (for example peer identifiers or draft text), and tool results returned by this server. That traffic is also processed by the MCP client provider under its own privacy policy.
Stored by this server for ordinary MCP calls: an encrypted MTProto session blob, your Telegram user id and display name/username, and audit metadata (tool name, redacted peer reference, status). Message bodies returned by read tools are fetched for that request and are not copied into the audit log. Accounts onboarded through Local Bridge activate have no stored session blob here.
Stored when Communication Agent is enabled: relevant incoming Telegram events, agent-visible conversation messages, and proposed action payloads are durably stored so the queue, policy, approval, and recovery flow can operate. Sensitive body/payload fields are encrypted at rest with your derived key. Message/event bodies and terminal or inactive pre-send action content use the agent retention window below; executing action content remains until persisted-random-ID recovery reaches a terminal state.
Revoke access: disconnect_telegram_account (or POST /api/account/disconnect, or disconnect at /telegram/connect/manage after signing in with Telegram) ends the Telegram session but keeps your client's OAuth connection, so reconnecting Telegram does not require re-adding the connector. delete_telegram_account (or DELETE /api/account) also revokes every OAuth client's refresh tokens, every worker token issued for your Telegram id, and every Local Bridge device. Removing the app/connector from your client settings revokes its tokens only if that client calls /oauth/revoke; we cannot see the removal otherwise. These calls need a connection granted account:manage. Access tokens already issued expire within their lifetime (at most 1 hour in production).

AI use of your messages

Your chats contain messages written by other people, who have not agreed to anything with this service. Telegram's terms forbid using Telegram data to train AI models without consent, so the rules here are narrow:

Inference for your own requests only. Message content is read only to answer a request you make through your own AI assistant, and is returned to that assistant and nowhere else.
No training by this service. This service never uses message content, or anything derived from it, to train, fine-tune or evaluate any AI model, and never sells or shares it for that purpose.
Turn off training in your AI client. Your MCP client provider handles the tool results it receives under its own policy. Before connecting, switch off any setting that lets the provider use your conversations to improve its models.
No broadcast channel posts. Posts in broadcast channels are not read at all: reading tools refuse a channel, and unread and search results leave channels out. A channel's name and unread count still appear in your dialog list. Private chats and groups are not affected.
Kept no longer than the feature needs. Ordinary MCP calls fetch messages for that request and do not store them. Only Communication Agent stores message content, encrypted, for the retention window in the table below.

Data inventory

Where	Contents	Why	Retention
`users` table	Telegram user id, display name, and username	Resolves your identity for per-user storage isolation	Account deletion clears the display name, username and last-seen time and removes related user-scoped rows by database cascade where configured. The Telegram user id, access tier and the time of the delete are kept, so a later sign-in is matched to the same row and an authorization code issued before the delete cannot be redeemed after it.
`client_notification_prefs` table	One row per category you explicitly decided (`product_updates`, `maintenance`, `security`), with the state, the time you decided, and which surface you used. No row is written for a default you never changed.	Records consent per category, so operational notices are never counted as marketing consent	Removed by account deletion. A preference grants no Telegram or MCP access.
`client_bot_reachability` table	Whether the login bot may currently start a chat with you (`unknown`, `reachable`, `blocked`, `cannot_initiate`), when that was observed and from which delivery. No message content and no Telegram API response body.	Learned only from the outcome of a message actually sent to you; no message is ever sent merely to test reachability	Removed by account deletion
`telegram_accounts` table	AES-256-GCM ciphertext of your MTProto session blob using a per-user derived key, plus account metadata and feature/send flags	Required to make Telegram API calls on your behalf	Until disconnect/revocation or deletion; session TTLs and sweepers may revoke it earlier
`incoming_events` and `conversation_messages`	Communication Agent event metadata and third-party Telegram message bodies. Message bodies are AES-256-GCM encrypted before storage.	Durable ingestion, deduplication, queue recovery, conversation context, and owner takeover handling	Encrypted bodies/context: `AGENT_RETENTION_DAYS`, default 30 days. Event metadata remains as a deduplication tombstone until account deletion. Setting retention to 0 keeps content indefinitely.
`agent_actions`	Proposed reply/action payloads, policy decision and reasons, approval state, and execution metadata. Sensitive payload text is encrypted at rest.	Server-side policy enforcement, human approval, and exactly-once-oriented execution bookkeeping	Encrypted draft/send content and approval capabilities: `AGENT_RETENTION_DAYS`, default 30 days. Old inactive pre-send actions are denied before content is cleared; executing actions retain recovery data until terminal. Lifecycle metadata remains until account deletion.
`audit_logs` table	Tool/action name, redacted peer reference, status, and a redacted error string. No message body, phone number, bearer token, or session bytes.	Operational visibility, abuse detection, and user-visible audit history	Default 90 days via `AUDIT_RETENTION_DAYS`; 0 keeps rows indefinitely
Process memory	Plaintext Telegram messages, decrypted agent content, tool arguments, and tool results while a request, listener update, policy evaluation, or queue job is being processed	Required to fulfil the request or agent workflow	Released after processing; the running process/operator can access it while present
Process stdout (Loki)	Structured JSON log lines from `slog`, with message/body/payload and credential keys redacted	Operator debugging	Per the platform's Loki retention (typically 14–30 days)

What is NOT stored in logs or audit history

Plaintext Telegram message bodies or proposed reply payloads in audit_logs or process stdout
Your phone number after interactive login
Your Telegram cloud password / 2FA digits
Raw MTProto session bytes (hosted mode stores only AES-GCM ciphertext)
The contents of Authorization: Bearer headers
Your IP address in the service database (the platform ingress may keep normal L4/L7 access logs)

Important: when Communication Agent is enabled, message content is stored in encrypted agent tables as described above. The previous “message text is never written to disk” guarantee applies only to ordinary read-tool responses and audit/logging paths, not to the durable agent workflow.

Website analytics

To learn how many people visit tg.mctl.ai and where they come from, the public content pages (home, docs, demo, security, privacy, terms, Local Bridge docs and product updates) load Umami, an open-source analytics tool that we host ourselves at stats.mctl.ai. No analytics data is sent to a third party. Umami sets no cookies. For each page view it records the page address (including campaign parameters such as utm_source), the referring site, browser, operating system, device type, screen size, language, and country, region and city derived from your IP address. Your IP address and user agent are used to compute an anonymous visitor identifier; the IP address itself is not stored.

The sign-in, consent, connect and account-management pages under /oauth, /telegram/connect and /local-bridge/activate do not load Umami, and no Telegram data, tool call, token or account identifier is ever sent to it. Page-view records are deleted automatically 2 years after they were recorded.

Communication Agent controls

The listener is active only for profiles explicitly marked as listener-enabled.
Only explicit /mctl ... commands from Saved Messages are retained as control commands; ordinary personal notes are ignored.
Disabling the listener removes the runtime account and immediately stops its pinned Telegram client.
A human reply marks the conversation as taken_over, preventing autonomous continuation under the server-side policy. This is sticky and only reversible via an explicit /mctl continue <conversation id> command from the owner.
observe mode requires approval for replies; guarded mode remains subject to server-side policy, limits, blocked senders, disclosure checks, and the global kill switch.

Self-service controls

You can remove account access and inspect what was recorded without operator involvement. Disconnect and delete require a connection granted account:manage; read-only connections, worker tokens and Local Bridge device credentials are refused with 403, and the refusal is recorded in your audit log. On tg.mctl.ai, you can still disconnect from the manage page after signing in with Telegram.

POST   /api/account/disconnect   # end Telegram session; OAuth grant kept
DELETE /api/account              # delete account/session row and user-scoped data; revoke OAuth refresh tokens, worker tokens and Local Bridge devices
GET    /api/account              # connection status + feature/send flags
GET    /api/account/audit        # newest-first audit rows (limit, before)
GET    /api/account/audit/verify # recompute the audit hash chain

Notification preferences are part of the same self-service surface:

GET    /api/account/notifications   # resolved preference per category
PUT    /api/account/notifications   # change one or more categories

They can also be changed in the browser at /telegram/connect/manage after signing in with Telegram, which submits a plain HTML form and needs no JavaScript. Reading or changing them through the API, and turning one on in the browser, requires a connection granted account:manage; after signing in with Telegram you can always turn notifications off there. Product updates stay off until you turn them on; maintenance and security are classified as operational notices and are never treated as marketing consent.

Equivalent MCP tools include disconnect_telegram_account, delete_telegram_account, get_my_audit_log, get_my_notification_preferences, and set_my_notification_preferences. All of them except get_my_audit_log require account:manage and are listed only to connections granted it. Disconnect/delete also tear down the in-memory MTProto client so a concurrent request cannot continue using a revoked session.

Who can access your data

You, through authenticated MCP tools and account endpoints.
Your MCP client provider, for prompts, tool arguments, and tool results that pass through that client.
The deployment operator, who has infrastructure and database access. Sensitive database columns are encrypted, but an operator who also controls the running service and encryption key can decrypt them.
Anyone who compromises the running pod could read sessions and message content in memory or use the service's decryption capabilities. Hosted mode is not zero-knowledge.

Third parties

Telegram (transport and identity) — the connected account uses Telegram MTProto, and sign-in uses Telegram OIDC.
Your MCP client provider — for example Anthropic or OpenAI — processes the conversation and tool traffic you send through that product.
No advertising or third-party analytics is injected by this service. Public content pages count visits with Umami, which we host ourselves (see Website analytics). OAuth/session-management pages use strict CSP and load no analytics; public content pages load the mctl design stylesheet and web fonts for presentation.

Contact

General support: [email protected]. Privacy inquiries: [email protected]. For security or vulnerability reports, see /security. Code is open source at github.com/mctlhq/mctl-telegram.