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

```text
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 the guide](https://api.tlmtr.io/docs/guides/mcp/) · [Read Markdown](https://api.tlmtr.io/docs/guides/mcp/setup.md)

**For AI agents:** follow [Instructions for AI agents](#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](#codex-desktop) | Settings → MCP servers |
| [ChatGPT Desktop](#chatgpt-desktop) | Settings → MCP servers on the selected Codex host |
| [ChatGPT on the web](#chatgpt-on-the-web) | Developer mode → Plugins |
| [Claude and Claude Desktop](#claude-and-claude-desktop) | Customize → Connectors |
| [Claude Code](#claude-code) | `claude mcp add` |
| [Codex CLI and IDE extension](#codex-cli-and-ide-extension) | `codex mcp add` or the extension's MCP settings |

The examples use OAuth. Complete [authorization](#authorize-the-connection) using the options offered by Telemetrio, then run the [free connection check](#make-the-first-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](#make-the-first-check).

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](https://learn.chatgpt.com/docs/extend/mcp?surface=app).

### 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](#make-the-first-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](#chatgpt-on-the-web). See OpenAI's [desktop MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=app).

### 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](https://developers.openai.com/plugins/deploy/connect-chatgpt) 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Claude Code

Add the remote Streamable HTTP server:

```bash
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](https://code.claude.com/docs/en/mcp).

### Codex CLI and IDE extension

In Codex CLI, check for an existing entry first:

```bash
codex mcp list
codex mcp get telemetrio
```

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

```bash
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](https://learn.chatgpt.com/docs/developer-commands) and [Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

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](https://t.me/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:

```toml
[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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

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](#clients-with-custom-headers), 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](https://t.me/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](#why-the-tool-list-can-differ-between-keys) 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](#result-schemas-and-context-size). |

## 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](#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](https://api.tlmtr.io/docs/intro/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](https://api.tlmtr.io/docs/guides/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](https://developers.openai.com/plugins/reference#tool-descriptor-parameters).

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.