Connect an MCP client

The hosted MCP server uses your existing owned Telegram Ads connection. It exposes 14 read-only tools, with input schemas, output schemas and structured results.

Connection settings

Setting	Value
Transport	Streamable HTTP
Server URL	https://tgads.tlmtr.dev/v1/connections/<connection-id>/mcp
Header	Authorization: Bearer <personal-token>
Required scopes	mcp:read and ads:read

Replace the placeholders with your own connection ID and personal API token. Use a client that supports custom Authorization headers. OAuth-only clients cannot complete an automatic login with this development endpoint.

This endpoint is stateless and uses POST JSON-RPC. A standalone GET is not the initialization flow and returns 405. Let an MCP SDK perform initialization and tool discovery.

TypeScript example

Install @modelcontextprotocol/sdk in your client project, then use:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const id = process.env.CONNECTION_ID!;
const transport = new StreamableHTTPClientTransport(
  new URL(
    `https://tgads.tlmtr.dev/v1/connections/${encodeURIComponent(id)}/mcp`,
  ),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.TGADS_TOKEN}`,
      },
    },
  },
);
const client = new Client({ name: "my-ads-client", version: "1.0.0" });
try {
  await client.connect(transport);
  const { tools } = await client.listTools();
  console.log(tools.map((tool) => tool.name));
  const result = await client.callTool({
    name: "list_accounts",
    arguments: {},
  });
  if (result.isError) throw new Error("Telegram Ads read failed");
  console.log(result.structuredContent);
} finally {
  await client.close();
}

Available tools

Tool	Result
list_accounts	Accounts available to this session
list_ads	One page of account ads
get_ad	Ad details and safe creative metadata
get_budget	Displayed account balance and visible history
get_account_stats	Account time series
get_ad_stats	Ad time series
get_account_report	Typed monthly account report
get_ad_report	Typed monthly ad report
search_target	Channel, bot or query target lookup
get_targeting_options	Languages, topics, countries and limits
get_similar_channels	Similar channel candidates
get_similar_bots	Similar bot candidates
search_locations	One page of location candidates
check_ad_post	Validate a text-only ad preview without saving an ad

Use tools/list to read the exact current arguments. list_accounts returns structured { accounts: [...] }; report tools return { report: ... }. Other shapes are declared by each tool's outputSchema.

Example requests to your assistant

• “List my Telegram Ads accounts, then show the ads in the account I select.”
• “Compare August ad reports by Telegram Ads starts and cost. Explain which ads had enough volume to compare.”
• “Show the text and targeting for my best-performing ads, and suggest experiments.”

MCP cannot create, edit, activate or delete campaigns, or allocate funds. Connection setup and cookie replacement happen through the extension or connection API. See coverage before relying on a metric or upstream operation.