Connect Telemetrio with MCP

Connect your AI assistant to Telegram channel analytics, catalog search and message search through Telemetrio's hosted MCP server. Tools use the same permissions, limits and billing rules as the Public API.

No local MCP server installation is needed.

Set up with your AI agent

Copy the setup prompt below into the AI client you want to connect. An agent with access to that client's settings can configure the server, guide you through browser authorization and verify the connection. If it cannot change your settings, it can give you the steps for your client.

Connect Telemetrio MCP using https://api.tlmtr.io/docs/guides/mcp/. Configure it for this client, guide me through authorization, and verify the connection with get_access.

Read Markdown

For AI agents: follow Instructions for AI agents. Select Read Markdown above for a plain-text version of the complete guide.

Connect an AI client

Use these connection settings in your client:

Connection setting	Value
Server name	telemetrio
Server URL	https://api.tlmtr.io/mcp
Transport	Streamable HTTP
Authentication	OAuth in your browser
Free connection check	get_access with empty arguments {}

Choose the client where you want Telemetrio tools to be available:

Client	Setup path
Codex Desktop	Settings → MCP servers
ChatGPT Desktop	Settings → MCP servers on the selected Codex host
ChatGPT on the web	Developer mode → Plugins
Claude and Claude Desktop	Customize → Connectors
Claude Code	claude mcp add
Codex CLI and IDE extension	codex mcp add or the extension's MCP settings

The examples use OAuth. Complete authorization using the options offered by Telemetrio, then run the free connection check.

Instructions reviewed October 1, 2026 against the linked client documentation. Menu labels and availability can vary by client version and workspace policy.

Codex Desktop

1. Open Settings → MCP servers → Add server.
2. Name the server telemetrio, select Streamable HTTP and enter https://api.tlmtr.io/mcp.
3. Select Save, then Restart.
4. Select Authenticate for Telemetrio and complete browser authorization.
5. Return to the app and verify the connection.

Check the existing server list first: desktop, CLI and IDE clients can share MCP configuration on the same Codex host. See OpenAI's desktop MCP instructions.

ChatGPT Desktop

In the desktop app's Settings → MCP servers, select Add server, enter telemetrio, choose Streamable HTTP and set the URL to https://api.tlmtr.io/mcp. Select Save → Restart, then Authenticate and complete browser authorization. Use /mcp to inspect connected servers before the free connection check.

This setup belongs to the selected Codex host. An existing entry on that host can also be used by Codex CLI and the IDE extension. ChatGPT on the web has a separate connection flow. See OpenAI's desktop MCP guide.

ChatGPT on the web

Manual MCP connections in ChatGPT use developer mode and can be restricted by account or workspace policy:

1. Open Settings → Security and login and turn on Developer mode.
2. Open Plugins, select the plus button and enter the name Telemetrio and a description such as Telegram analytics through the Telemetrio API.
3. Under Connection, enter https://api.tlmtr.io/mcp, select OAuth if prompted, and create the connection.
4. Complete the Telemetrio authorization page in the browser, then review the discovered tools.
5. Start a new conversation and enable Telemetrio from the tools menu.

ChatGPT on the web does not read local Codex configuration. This manual connection is separate from publication in the ChatGPT plugin directory. See OpenAI's connect and test guide for the current interface and workspace requirements.

Claude and Claude Desktop

For an individual Claude Free, Pro or Max account:

1. Open Customize → Connectors.
2. Select + → Add custom connector.
3. Enter the name Telemetrio and URL https://api.tlmtr.io/mcp, then add the connector.
4. Select Connect and complete authorization in the browser.
5. In a conversation, use + → Connectors to enable Telemetrio.

For Team and Enterprise, an Owner or Primary Owner must first add it under Organization settings → Connectors → Add → Custom → Web. Each member then connects under Customize → Connectors. Anthropic currently lists remote custom connectors for Free, Pro, Max, Team and Enterprise accounts, with one custom connector on Free; the exact controls depend on the plan. See Anthropic's remote connector guide.

Claude Code

Add the remote Streamable HTTP server:

claude mcp add --transport http telemetrio https://api.tlmtr.io/mcp

Start Claude Code, run /mcp, select telemetrio and complete browser authorization. claude mcp list and claude mcp get telemetrio show the connection status. This command configures the current project locally; add --scope user to make it available across projects. See the official Claude Code MCP guide.

Codex CLI and IDE extension

In Codex CLI, check for an existing entry first:

codex mcp list
codex mcp get telemetrio

If it is absent, add the server. Then start OAuth login:

codex mcp add telemetrio --url https://api.tlmtr.io/mcp
codex mcp login telemetrio

Complete authorization in the browser, then restart your Codex session and use /mcp to inspect the loaded server. See OpenAI's MCP CLI commands and Codex MCP guide.

In the IDE extension, open the gear menu and select MCP servers → Add server. Enter telemetrio, choose Streamable HTTP and provide the same URL. Save, restart the extension and select Authenticate.

Desktop, CLI and IDE clients share configuration only when they use the same Codex host. The default user configuration is ~/.codex/config.toml; a trusted project can also have .codex/config.toml. Inspect the configuration your client actually uses before adding another entry.

Authorize the connection

OAuth opens Telemetrio's authorization page in your browser. Use the account sign-in or API-key entry offered on that page. You approve access yourself; never paste an API key into a model conversation, system prompt, tool argument or MCP URL.

Enter an API key

If the authorization page asks for an API key, check that it is on https://api.tlmtr.io. Enter the key only on that HTTPS page. The MCP service exchanges it for an MCP access token; the client does not receive or store the API key.

Get an API key

If you need a key for the authorization page or header authentication, open @telemetrio_api_bot with your Telemetr.io-linked Telegram account and send /api_key. Select the key for the billing model you intend to use and keep it private. If account sign-in lets you select an existing key, you do not need to copy its secret.

Sign in and choose a key

If the authorization page offers account sign-in, the browser opens Connect Telemetrio:

1. Sign in to your Telemetrio account if prompted.
2. Check the displayed account. Use Switch if you need a different account.
3. Review the app's name, return address and requested access, then choose the key for this connection.
4. Select Connect to return to the client, or Cancel to deny access.

You select an existing key by its type and masked identifier; you do not need to copy or paste its secret.

Keys on the account	What to do
One active key	It is selected automatically. Review its billing details before connecting.
Both a Credits key and an API subscription key	Choose which key this app will use. No key is selected automatically.
No API key	Select Create a credits key, then review the new key and connect. Creating a key does not grant access to the app by itself.
An expired or revoked key	Choose an active key or restore access before connecting. An inactive key cannot authorize the connection.

Connecting is free. An empty credit balance can still allow a connection, but paid requests require sufficient credits. Finish authorization within five minutes; if it expires, restart the connection from your client.

Clients with custom headers

For a headless client or an IDE/SDK that cannot complete browser OAuth, use x-api-key with the same URL. Keep the key in the client's secure credential settings or an environment variable, outside source control.

Codex can read the header value from the environment of the process running it:

[mcp_servers.telemetrio_header]
url = "https://api.tlmtr.io/mcp"
env_http_headers = { "x-api-key" = "TELEMETRIO_API_KEY" }

Set TELEMETRIO_API_KEY securely on the host running the client, then restart it so the process receives the variable. A desktop app may not inherit variables from your terminal. See OpenAI's HTTP MCP configuration.

Use one active Telemetrio connection for the selected authentication method. If switching an existing entry to headers, clear its saved OAuth credentials first; if using the separate entry above, disable the old OAuth entry. Combining x-api-key with an OAuth Authorization header in one request is rejected. Do not run OAuth login for the header-only entry.

Manage connected apps

Sign in to Telemetrio. If Connected apps appears in your account menu, open it to manage your authorizations.

Each connection shows the app name, key type, masked key, connection date and last activity when known. Select Disconnect for the app you want to remove. This revokes that connection's access without deleting the API key or disconnecting other apps. A request already authorized may still finish.

To use a different billing key, disconnect the existing connection and start a new OAuth connection from the client. Removing Telemetrio from a client's tools menu alone does not revoke its Telemetrio authorization.

Make the first check

After browser authorization, reload the client or start a new conversation if needed so it can discover Telemetrio's tools. If your client exposes MCP discovery, use tools/list and check that get_access is available. Then ask:

Call Telemetrio's get_access tool with empty arguments {} and summarize the key status, available tools and effective limits. Do not call any other Telemetrio tool.

A successful get_access response verifies the connection without consuming request quota or credits. A saved server entry or completed browser consent alone does not verify that the current conversation can call tools.

If get_access reports an inactive subscription or unavailable capabilities, the connection works but the account needs the action described in the response. An empty credit balance can prevent paid calls even after setup succeeds. Report these access conditions separately from connection failures.

Stop the setup check here. Data reads, searches, snapshots and diffs can consume quota or credits and require a separate user request.

Connection troubleshooting

What you see	What to do
Telemetrio is saved, but its tools are missing	Complete Authenticate, reload the client and start a new conversation. Check that the server is enabled on the host and in the configuration scope used by this client.
The agent cannot edit your MCP settings	Follow the steps for your client above. A chat agent may have no access to your desktop configuration.
MCP servers, Plugins or Developer mode is missing	Check the linked client documentation and workspace policy. Use the setup path for the client you are actually running.
OAuth finishes in the browser, but the client keeps waiting	If the client runs over SSH or on another host, the browser's loopback callback may reach the wrong machine. Complete login where the client can receive its callback, or use the client's supported callback forwarding.
A headless client cannot open or receive browser authorization	Use custom-header authentication, with the API key supplied through the client's environment or secure settings.
A browser Username / Password dialog before the Telemetrio consent page	Cancel it. This is not the API key form.
An old ChatGPT entry offers only Install, cannot be deleted, or blocks reusing its name	Leave it in place and create a new connection with an unused name and the current URL.
A Reconnect Telemetrio page before the API key form	The saved OAuth client is unavailable. Create a new connection; this does not mean the API key is invalid.
Authorization rejects the API key	Check that the key was copied completely and has not been revoked. Retrieve your key through @telemetrio_api_bot and reconnect.
The authorization page shows Connection request expired	Restart the OAuth connection from the client and complete authorization within five minutes.
get_access succeeds but a needed tool is unavailable	Read its reason and required_capability. Resolve the account access condition instead of reinstalling the connection.
A request sends both x-api-key and OAuth credentials	Clear saved OAuth credentials for a header-only entry and send one authentication method per request.
The tool inspector recommends outputSchema	This is a recommendation about describing results, not an authorization error. See result schemas.

Instructions for AI agents

Use this runbook when a user asks you to set up Telemetrio MCP. The hosted server is https://api.tlmtr.io/mcp, its transport is Streamable HTTP, and the default authentication method is OAuth. The connection check is get_access with {} and consumes no quota or credits.

1. Identify the target. Default to the AI client the user is currently using unless they name another one. Determine its operating system, the host running its MCP connections, and the configuration scope (user or project). Use available client and workspace information; ask only when an ambiguity changes where you would configure the server. A shell on a remote host does not necessarily control the user's desktop app.
2. Inspect before changing settings. Check the target client's existing entries for telemetrio and for the endpoint above. Reuse a matching entry; preserve unrelated servers and settings. Resolve an existing entry with a different URL before replacing it. Do not create duplicate active Telemetrio entries. On Codex, inspect the effective user/project configuration; on Claude Code, inspect the server and its scope.
3. Use the native remote connection. For Codex user settings, add a missing entry with codex mcp add telemetrio --url https://api.tlmtr.io/mcp; for project scope, add [mcp_servers.telemetrio] with url = "https://api.tlmtr.io/mcp" to the trusted project's .codex/config.toml. For Claude Code, use claude mcp add --transport http telemetrio https://api.tlmtr.io/mcp in the intended project; use --scope user only when cross-project access is intended. Use the client's supported configuration or GUI for other targets. Do not install a local MCP wrapper, proxy or server when the client supports Streamable HTTP directly.
4. Let the user authorize. Start codex mcp login telemetrio, Claude Code's /mcp authorization, or the client's Authenticate/Connect action. The user completes Telemetrio's browser consent and selects or enters their key there. Never request the key in chat, print credentials, copy tokens into prompts or approve browser consent on the user's behalf. For a remote host, confirm that the OAuth callback can reach the client; opening a remote loopback URL on another machine may not complete login.
5. Handle headless access only when needed. If browser OAuth is unavailable, configure x-api-key from secure settings or an environment variable. For Codex, an HTTP server table uses url = "https://api.tlmtr.io/mcp" and env_http_headers = { "x-api-key" = "TELEMETRIO_API_KEY" }. Have the user provide the variable securely to the client process. Clear saved OAuth credentials before switching an entry to headers; do not combine authentication methods. Keep secrets out of configuration files and source control.
6. Reload and verify. Restart or reload the target client when required. Discover tools with tools/list if exposed, or use the client's available tool discovery. Call only get_access with empty arguments {}. Do not call data reads, searches, usage tools, snapshots, diffs or any other tool as a setup test. Inspect the response for account access conditions separately from transport or authentication errors.
7. Report the actual state. Use configured when the entry is saved; authorization required while consent is incomplete; restart required when the current session has not loaded the change; and verified only after a successful get_access response. Include the target client/host/scope, what changed, the check performed and the exact next action. If you cannot discover or call the tool, say that verification is pending.

If you cannot inspect or modify the target configuration, give the exact GUI steps for that client rather than claiming installation. For Codex Desktop or ChatGPT Desktop, use Settings → MCP servers → Add server → Streamable HTTP, enter telemetrio and https://api.tlmtr.io/mcp, then Save → Restart → Authenticate. For ChatGPT on the web, use Settings → Security and login → Developer mode, then Plugins → plus button, enter the URL and choose OAuth if prompted. For Claude, use Customize → Connectors → + → Add custom connector, enter the URL and select Connect. Workspace policy can restrict these controls. After the user completes setup, verify with get_access if your session can access it; otherwise leave the check pending with the prompt from Make the first check.

Explore Telemetrio tools

After setup, request the data you need. These calls use the selected key's normal API permissions, quota and credit billing.

Ask your assistant	Tool
Show my API usage and when my limits renew.	get_usage_info
Retrieve information for this channel using its internal ID.	get_channel_info
Find up to 10 verified channels matching “technology”.	catalog_search
Search Telegram posts for “solar energy” from the last 7 days.	search_messages

Why the tool list can differ between keys

MCP discovery returns get_access plus the Public API operations currently allowed for the authenticated key. A Free or Pro key therefore receives a smaller catalog than a key with catalog or message-search access. Filtering keeps unavailable tools out of the model context and avoids calls that are certain to fail.

Call get_access to inspect:

• whether the key is active;
• its credits or subscription key type;
• available_tools and unavailable_tools;
• reason and required_capability for unavailable tools;
• effective history, page-size, catalog and snapshot limits.

get_access does not consume request quota or credits. It remains available for a valid but inactive key so the client can explain the next action.

An unavailable operation uses one of these reasons:

Reason	Meaning	Safe next step
inactive_subscription	The key is valid, but its subscription is inactive.	Restore the subscription or use another active key before retrying.
capability_disabled	This key does not have the named capability.	Inspect required_capability. A credits key may require a different API plan; a subscription key owner may need to change that key's configured access.
feature_unavailable	The operation is disabled for the current service rollout.	Try later or check release/support information. Funding or upgrading alone may not enable it.

The server rechecks access when listing and calling tools. Calling a remembered tool name directly does not bypass the permission check.

Usage, quotas and credits

Each connection uses the key you authorized. A Subscription key uses its configured API allowances; a Credits key uses the applicable plan limits and charges billable requests to its funding wallet. MCP adds no separate quota or unlimited allowance.

The connection does not automatically switch from a Subscription key to a Credits key when a quota runs out, or to another key when credits are exhausted. Change the billing key by authorizing a new connection explicitly.

Use get_usage_info for billing-period dates and request, channel and search counters while the key is active. Tool discovery and get_access do not remove the limits that apply when a data tool runs.

Credit amounts use integer milli-credits: 1 credit = 1,000 mc. A successful credits-key call can report billing.cost_mc and billing.remaining_mc, derived from the API credit headers. See keys, credits and limits for how usage counters and credit billing interact.

Treat failures according to their cause:

• invalid_credentials: reconnect or replace the stored credential; repeating the same key will not help.
• inactive_subscription or capability_disabled: use get_access and resolve the stated account condition.
• quota exhaustion: use get_usage_info; wait for the returned billing period to renew or change the applicable allowance.
• insufficient credits: add at least the reported shortfall_mc, while remembering that balance does not unlock a missing capability.
• rate_limited or operation_in_progress: honor retry_after_seconds when present and use bounded backoff only when the error is retryable.
• resource_limit_reached: reuse a snapshot or diff, wait for expiry, or increase the applicable capacity; repeating the request does not free capacity.
• verified_channels_only: this API key permits only verified channels for the request. Use a verified channel or ask the key owner to review access to other channels; adding credits alone does not remove this restriction.
• upstream_unavailable: the result can be ambiguous; check whether a paid or state-changing operation completed before retrying.
• invalid arguments: correct the field identified by the tool schema; do not retry unchanged input.

The MCP server does not automatically repeat paid or state-changing requests after an ambiguous failure. Narrow a page size or filters when a response exceeds the server's safe size bound.

Mutating catalog tools

Catalog snapshot and diff tools preserve MCP behavior annotations:

Action	Behavior
Create a snapshot or diff	Changes server state, is additive and is not idempotent.
Delete a snapshot or diff	Changes server state, is destructive and is idempotent.
List or read resources	Read-only and idempotent.

Clients may use these annotations when asking for confirmation, but they remain hints. Review snapshot filters, IDs and cascade before approving a mutation. If a creation response is lost, list recent resources before deciding whether to repeat it. See snapshots and diffs for retention, pagination and conflict handling.

Result schemas and context size

The current tools do not declare outputSchema. Successful results include structuredContent and JSON text. An output schema would describe and allow validation of that structure. OpenAI recommends declaring it for structured results; this warning is separate from OAuth authorization. See OpenAI's tool descriptor reference.

The empty inputSchema.properties object on get_access is expected: that tool takes no arguments. Input and output schemas describe different parts of the call.

The current full catalog contains 34 tools; a representative Free/Pro catalog contains 23. Measurements of compact MCP Tool JSON with tiktoken 0.14.0:

Catalog	Tools	cl100k_base tokens	o200k_base tokens
Full	34	5,161	5,245
Representative Free/Pro	23	2,445	2,477

These figures measure tool definitions only. A client can add wrappers, cache definitions or load tools lazily, so they are not total prompt billing estimates.