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.

ChatGPT Apps and MCP users

When you connect mctl-telegram to ChatGPT, Claude, 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 an independent project and is not affiliated with, endorsed by, or operated by Telegram, OpenAI, or Anthropic.
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.
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: call disconnect_telegram_account or delete_telegram_account via MCP, use the HTTP endpoints below, or remove the app/connector from your client settings.

Data inventory

Where	Contents	Why	Retention
`users` table	Telegram user id, display name, and username	Resolves your identity for per-user storage isolation	Until account deletion; related user-scoped rows are removed by database cascade where configured
`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.

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.
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:

POST   /api/account/disconnect   # mark session revoked and stop Telegram access
DELETE /api/account              # delete the account/session row and related user-scoped data
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

Equivalent MCP tools include disconnect_telegram_account, delete_telegram_account, and get_my_audit_log. 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 OpenAI or Anthropic — processes the conversation and tool traffic you send through that product.
No advertising or third-party analytics is injected by this service. OAuth/session-management pages use strict CSP; 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.