Telegram MCP Troubleshooting: Connected, but No Tools or Chats?

If Telegram MCP says it is connected but your assistant cannot find tools or chats, check the connection in order: installation → browser authorization → identity → one bounded read. A server connection indicator alone does not prove that the assistant can retrieve messages from the intended Telegram account.
Chiho supplies authorized existing Telegram account conversations to an AI client such as Codex, Claude, or ChatGPT. A Telegram bot or Claude Channel that delivers instructions to a running agent serves a different purpose; that connection alone does not establish access to your personal conversation archive. Actual access depends on the account identity, granted permissions, any Telegram Business permissions, history coverage, and available tools. The architecture guide explains how to choose the right access path.
Published by Chiho. This guide is based on Chiho source and current client documentation checked on 6 October 2026. It is a diagnostic procedure, not a report of successful tests in a customer account. Examples are synthetic; tool availability depends on the connected product and resource version. The existing header image shows general Chiho interface context, not a troubleshooting result.
Start with the first missing piece of evidence
Work down this list and stop at the first failed check:
- No Chiho connection in this client: verify installation in this exact application and workspace.
- Connection exists, but sign-in is required: finish browser authorization for that connection.
- Tools are unavailable: inspect the client’s discovered tool set, selected resource, and restrictions.
- Identity is wrong or no healthy Telegram account appears: verify the Chiho connection and the Telegram account inside it.
- A read succeeds but returns nothing useful: check the selected chat, time window, pagination, and coverage.
- A read reports a wait or error: handle that result before retrying or expanding the request.
Do not solve every symptom by deleting and reinstalling every connection. Preserve working connections while you identify which layer failed.
Check installation in the client you are actually using
Start from the maintained Chiho MCP setup page. Record the application, selected connection label, and configured resource URL without credentials. Chiho CRM and the separate Telegram-client product do not promise identical tools; versioned resources also preserve different contracts. Compare against the setup instructions for the installed product, not a remembered tool count.
For Codex, verify that this running surface can see the intended MCP configuration. For a manually configured OAuth server, codex mcp login <server-name> starts its browser sign-in; use the existing configured name. Installing a plugin in another application does not prove it is available here. See the Codex MCP reference and the Chiho ChatGPT/Codex guide.
For Claude Code, use /mcp to inspect the connection and authenticate a remote OAuth server when prompted. A connector configured in another Claude surface still needs to be available in the surface you are using. Follow the Claude Code MCP reference and the Chiho Claude guide.
For ChatGPT, inspect the installed plugin and its connected account in the current workspace. Availability can depend on the supported surface and workspace policy. Follow OpenAI’s account-connection instructions, then check the connection selected for this conversation.
A Claude Channel that lets you message an agent through Telegram is not evidence that the agent has an account-history connector. Identify the integration before changing its settings.
Separate browser authorization from Telegram account health
Complete the Chiho browser consent flow and return to the same client. Check the intended Chiho account, personal or team scope, and requested permissions. Interactive setup does not require copying a service token into a prompt or support ticket.
Where the connected tool set exposes them, run auth_status and then account_whoami:
auth_statusreports authenticated scope, capability scopes, approval mode, and the count of healthy accessible Telegram accounts.account_whoamireports accessible Telegram accounts and connection or reauthorization flags. Review identifying details privately.
An authenticated Chiho connection with no healthy Telegram account is a different result from failed MCP authorization. Reconnect Telegram through Chiho when its account status requires reauthorization; repeating the AI client’s OAuth login alone does not demonstrate that the Telegram session has recovered.
On CRM connections that expose get_profile, use it to verify the Chiho identity and scope before selecting a Telegram account. Older resources and the separate Telegram-client product retain their own contracts, so absence of this tool alone is not a failure. get_profile does not read Telegram messages. An accountId selects a Telegram account inside an authorized connection; it cannot switch to a different Chiho connection.
If two named connections exist, ask the assistant to use only the intended one and stop on an identity mismatch. Check a scheduled task separately from an interactive chat: a successful selection in one conversation does not prove the task will use the same connection.
When the connection exists but tools are missing
Ask the assistant to inspect the tools actually available in this conversation. Do not let it invent a call from a tool name found in an old guide. Clients may discover tools on demand, and names can be presented differently across product surfaces.
Compare three things: the configured resource and version, the authenticated account/team scope, and the client’s allowed tools. Chiho filters its authenticated tool list by scope and capabilities. A personal connection and a team-scoped connection therefore need not expose identical operations.
If authorization expired or the grant was revoked, use the client’s reconnect flow and repeat the identity check. Tokens are bound to their resource and environment; copying a production credential to a staging endpoint, or changing a resource URL while keeping its old grant, is not a repair. A new resource requires its own authorization. Do not weaken workspace controls or enable writes simply to diagnose a missing read tool.
After correcting the configuration, refresh the connection using the client’s supported controls. Confirm discovery again before trying a history request. If discovery still fails, capture the sanitized error and stop cycling through logins.
Diagnose a resource or grant mismatch before reconnecting
A resource is the protected MCP endpoint, not a Telegram chat or an MCP file attachment. Record the exact host and path privately: the stable production resource is https://api.chiho.ai/mcp; /mcp/v9 is a separate versioned resource, and stagingapi.chiho.ai is a different environment. A version label in an old setup guide does not establish which resource this client actually uses. Follow the maintained setup guide for your product; do not replace a working versioned connection merely to match a newer tool list.
The MCP authorization specification binds authorization to the intended resource and requires the server to validate the token audience. Chiho's current implementation also checks the active grant's resource. Changing a URL while retaining its credential cannot establish authorization for the replacement endpoint. Let the client's browser flow obtain the correct authorization; never copy tokens between connections.
Use this decision tree, based on Chiho's source reviewed on 22 October 2026:
- Wrong host or resource path: stop before a history request. Confirm the intended product and environment. If a change is needed, authorize that exact resource through the supported client flow, then recheck identity. Do not test production credentials against staging.
- Right resource, failed authentication: use the safe error code and connection status to distinguish an expired or revoked grant from a Telegram session problem. Reconnect the affected client connection when required. A changed permission set needs consent; repeated token refreshes are not evidence of expanded access.
- Identity succeeds, but an expected tool is absent: compare the authenticated grant with the tools this client actually discovers. The stable endpoint's additional capabilities require explicit
chiho.crm.extendedconsent and the relevant domain scopes. Old grants and refreshed tokens do not acquire that scope automatically. Client policy or discovery can also hide a tool; absence alone does not identify the cause. - Personal and team lists differ: check the authorized binding rather than widening it. Personal workflow tools are unavailable to team grants; newer team tools also require the relevant team scopes and live membership. An
accountIdcannot switch the Chiho connection or evade its team boundary. - A media reference or action preview came from another connection: stop reusing it. Current stable references and message-action previews are resource- and connection-bound; they cannot be carried to
/mcp/v9or another connection. Original and expanded write tools have distinct preview/execution contracts. Re-establish evidence in the intended context; do not execute an action to test authentication.
Synthetic diagnostic exercise, not an observed result: connection A uses /mcp/v9; connection B uses /mcp. Both may be authorized, yet their advertised tools need not match. First record the resource, personal/team binding, identity-check outcome and needed read tool for each. If B lacks a newer capability, inspect its consent and discovery before concluding that Telegram is disconnected. Never merge results from A and B under one assumed identity.
A compact, sanitized receipt can say: “Production; stable /mcp; personal binding; identity verified; expected read tool absent from current discovery; consent coverage not yet confirmed; no history retrieved and no writes attempted.” This is a template, not fabricated tool output. Keep tokens, callback URLs, grant identifiers and account details out of it.
After a deliberate resource or consent change, rediscover tools, verify identity again and request one small source-backed search or read. An authenticated status establishes authorization, not nonempty retrieval. Record actual message coverage separately. If the expected operation remains unavailable, stop and send the receipt to support instead of broadening permissions speculatively.
When tools work but chats or messages appear to be missing
Choose one known, authorized conversation and a short period with a message you can independently recognize. Keep this first test small. A suggested diagnostic request is:
Use only the intended Chiho connection. Verify its identity and the Telegram account first. Read up to five messages from the one authorized chat I specify. Return the actual covered period, message references and a short factual summary. State any partial coverage or error. Do not send messages, import chats, change records, or create tasks. Stop if identity is ambiguous.
Treat the resulting evidence carefully:
- Telegram history and CRM inventory differ. A missing saved CRM row is not proof that the conversation does not exist in Telegram. A listed row is not proof that its complete message history was retrieved. See contacts, dialogs, and CRM counts.
- Scope matters. Team reads require team-visible conversations. Do not switch to a broader personal context just to bypass a team restriction.
- Search inputs matter. The hosted CRM message-search implementation supports Telegram search; local, tag, and company filters are not supported there. Team-scoped message search requires a selected chat. Use the current tool schema rather than copying unsupported filters.
- A page is not the archive. State the account, conversation, returned period and any continuation or partial result. Follow only the pagination supported by the tool.
- Empty is a bounded observation. No matches for one phrase or period does not establish that a commitment never existed. Recheck the scope and a known message before making a broader claim.
For example, a synthetic test might return five recent messages while the known decision is a month old. That proves a recent page was read; it does not prove search is broken or that the decision is absent. A second bounded request for the appropriate period can distinguish those cases without requesting the entire account archive.
Continue an older history page without skipping messages
When the connected resource exposes chat_read with date and message ID offsets, copy nextOffsetDate and nextOffsetMessageId from the same response into offsetDate and offsetMessageId for the next call. Keep the same verified account, chat, and filters. The timestamp alone cannot distinguish messages sent in the same second. Use the tool's actual schema; don't translate these fields into guessed parameters for another tool.
In a fictional support chat, the last two returned messages share a timestamp and the approval you're looking for might be on the next page. Ask the assistant to continue once with the returned pair and check whether it can cite the approval. If the pair is missing or doesn't advance, or the read is interrupted, record the last verified message and report that older history remains unchecked. A continuation tells you where to resume; it doesn't prove what the next page contains.
Before you start, set a stopping point: the target message, the oldest time you need, or a small page budget. If the budget runs out first, report the verified interval and what remains unknown. Keep message references and offsets in the private working context; a support ticket only needs the outcome, such as “first page returned; second page could not be verified.”
Respect wait responses and separate reads from repairs that write
If chat_read returns rate_limited, wait the returned retryAfterSeconds before reading that account again. Do not launch parallel reads against the same account or keep retrying during the wait. Chiho’s source applies account-level Telegram backoff; static request-rate guesses are not a substitute for the runtime response.
If you are already inspecting an inventory sync, waiting_for_telegram and resumeAt describe a wait in that job. They do not mean the job completed. Starting a new sync is a separate action that can update stored inventory; it is not required just to prove MCP authorization.
HTTP success also does not prove tool success. Check the tool’s error indicator and result, then check whether the requested messages were actually returned. On a timeout, preserve the narrow request and reported state; do not immediately expand it into multiple reads.
Review tool permissions before trying a repair that changes anything. Chiho enforces scope, capabilities and execution safeguards, but not every agent write waits for a separate Chiho approval. Some sends and CRM/task changes can execute after client-side controls. Keep this diagnostic read-only; use the security checklist before deliberately enabling a broader workflow.
Send a small, sanitized support record if the check still fails
A useful record identifies the failed layer without exposing the conversation:
- UTC time, client name/version, and whether this was an interactive chat or scheduled task.
- Product/resource URL without tokens or query credentials; replace private connection labels with neutral labels.
- Last successful step: installed, authorized, identity verified, tools discovered, or bounded read completed.
- Failing tool name, safe error code, request ID if exposed, and returned wait duration.
- Expected versus observed behavior, using a fictional chat label and stating whether the result was empty, partial, or an error.
Do not attach bearer tokens, OAuth callback URLs, Telegram login codes, session strings, raw tool payloads, message history, or screenshots containing account details. You can say “expected connection A, observed connection B” without sending profile identifiers or account names.
A synthetic support summary could read: “Claude Code; interactive chat; identity verified; one-chat read returned a rate-limit code and a wait duration; no parallel retries attempted.” It gives support a concrete boundary without copying customer content.
Finish with one verified source-backed read
Recovery is complete for this test when the intended connection and Telegram account are confirmed, the needed tool is available, and one bounded request returns the expected source messages with clear coverage. A green connection badge or a fluent answer without retrieved evidence is insufficient.
Return to the Chiho setup guide, complete installation and browser authorization, verify identity, and read one authorized conversation. Once that works, use the inbox briefing workflow to expand deliberately. Keep the first successful read as your acceptance check before enabling scheduled reviews or writes.