Skip to main content
The Telegram Account Proxy provides independent, persistent MCP and REST interfaces for your personally owned Telegram account. Each instance serves only one account; the container does not contain AI, and the login session is stored in the instance’s separate persistent volume.
This is not a Telegram Bot API bot. Do not use it for spam messages, bulk cold messaging, or bypassing Telegram restrictions. Before sending, editing, or deleting content to third parties, your Agent should obtain explicit confirmation.

​
Deployment and Login

  1. Create a Telegram Account Proxy in Console → Applications, activate the subscription, and click deploy. Instance resources are automatically configured by the platform.
  2. After the instance is ready, click “Generate Login QR Code”. The QR code is valid for a short period and can be regenerated after it expires.
  3. In Telegram, open Settings → Devices → Link Desktop Device and scan the QR code.
  4. If the status becomes password_required, enter the Telegram two-step verification password in the console. The password is submitted only to your tenant instance and will not be written to platform configuration.
  5. After the status becomes authenticated, the console displays the current account, MCP address, and Bearer access token.
The authorization session is stored in the persistent volume and will be reused during normal restarts and upgrades. “Log Out Account” in the console calls /api/auth/logout to revoke the Telegram session; “Destroy Instance” also deletes the workload and persistent volume.

​
Authentication and Health Checks

Except for /health and /readyz, login, REST, and MCP interfaces all require:
The service only accepts header authentication and does not support appending the token to the URL. Protect it as you would protect your account password.
/health only indicates that the HTTP process is alive:
/readyz indicates whether the MTProto connection is available. When connected, it returns HTTP 200, even if the account is still scanning the code or waiting for two-step verification:
When disconnected, Kubernetes direct probes to the Pod return HTTP 503, and the instance automatically reconnects in the background. At this time, the Pod is temporarily removed from the public Service, and reading diagnostic JSON through the instance domain is not guaranteed; please wait in the console for the Deployment to recover to Ready. Common login_state values include login_required, waiting_scan, password_required, and authenticated; authenticated must still be reached before performing account message operations.

​
Connecting MCP Clients

​
Claude Code

​
Clients Such as Cursor That Support Static Request Headers

Configure the Streamable HTTP address according to the client’s current documentation, and add the Authorization request header. For example, clients supporting the following structure can use:
This is not a universal configuration format for all MCP clients. Remote connectors for Claude Desktop / Claude.ai are established from the cloud and do not read any HTTP request headers in the local claude_desktop_config.json; if static Bearer request headers are currently required, please use Claude Code or a client that explicitly supports this capability.

​
MCP Tools

target can be a chat ID, username, or exact chat name; when names are ambiguous, prefer using an ID or username.

​
REST API

All successful responses use {"data": ...}, and failed responses use {"error": "..."}.

​
Examples

​
Complete Interfaces

​
Frequently Asked Questions

  • 401: Bearer token missing or incorrect. Confirm the token is placed in the request header, not in the URL query parameters.
  • 503: The proxy access token is not configured, or the Telegram client is not ready yet. Check /readyz first; if the proxy access token is not configured, protected endpoints will also return 503.
  • 400: Invalid parameters or JSON; search must provide q, and limit must be an integer greater than or equal to 1.
  • 403 / 404: The current account does not have permission, or the target / message ID does not exist.
  • 429: Telegram rate limiting has been triggered. Read retry_after and wait; do not retry concurrently.
  • QR code never completes: Generate the QR code again, and confirm that you are using Telegram’s “Link Desktop Device” QR code scanning entry point.
  • Login required again after restart: Check whether the instance persistent volume is functioning properly; you need to scan again after actively logging out, revoking the session in the Telegram device list, or when the session expires.

​
Verification Scope

The source code and automated tests cover login status, Bearer fail-close, REST parameter validation, error mapping, and session persistence implementation. In production use, you should still first complete read-only and message creation/editing/deletion smoke tests with target=me (Saved Messages) before allowing the Agent to operate third-party sessions.