TG Validator
01

What is MCP?

The Model Context Protocol lets AI applications call external tools during a conversation. Ask your assistant to check a number or review a batch without writing a separate API integration.

MCP is a protocol adapter. It uses the same products, balance, billing, rate limits, concurrency limits, and result semantics as the REST API.
02

Authentication

Use the exact same API key as the REST API and add it as a Bearer token in your MCP client configuration.

Authorization header
Authorization: Bearer YOUR_API_KEY
Keep your API key private

Only add the key to your own trusted client configuration. Never expose it in browser code or public prompts.

03

Server URL

Point your client to the official Streamable HTTP endpoint. No local MCP process is required.

MCP endpointhttp://localhost:14004/mcp

Requests use JSON-RPC over Streamable HTTP and the same API-key middleware as REST.

04

Connect your client

Replace YOUR_API_KEY with the key from Settings.

Claude Code

Add the remote server from your terminal.

claude mcp add --transport http tgvalidator https://tgvalidator.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Cursor / Claude Desktop

Add this server entry to the client's MCP configuration.

{
  "mcpServers": {
    "tgvalidator": {
      "url": "https://tgvalidator.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Other MCP clients

Use Streamable HTTP with the endpoint and Bearer header above.

URL: https://tgvalidator.com/mcp
Authorization: Bearer YOUR_API_KEY
05

Available tools

The tools are scoped to the app that owns your API key. Call list_products first when you need to discover valid product codes.

list_products

Lists products, prices, billing multipliers, and response fields.

No parameters
check_number

Checks one E.164 phone number synchronously. registered is the primary result.

service_type · string · required
identifier · string · required
check_numbers

Checks 1–100 numbers with one service_type and preserves input order.

service_type · string · required
identifiers · string[] · required · max 100
get_balance

Reads the current account balance without charging it.

No parameters

Example prompts

After connecting, ask your assistant in plain language:

  • “Check whether +14155552671 is registered on Telegram.”
  • “Check these 20 numbers and summarize the results.”
  • “How much balance is left before I run this batch?”
06

Error handling

Tool failures use isError=true and the same code, msg, data contract as the API.

Example tool error
{
  "code": 42900,
  "msg": "rate limit exceeded",
  "data": null
}
40100

Missing or invalid API key

Check the Bearer header and confirm the key is active.

40200

Insufficient balance

Check the balance or top up before retrying.

42900 / 42901

Rate or concurrency limit

Wait for the rate window or in-flight checks to clear.

40000 / 40002

Invalid product or number

Use a product returned by list_products and E.164 numbers.

42200 / 50300

Undetermined or temporary failure

Do not classify the number as unregistered; retry later.

Ready to connect your AI assistant?

Create an account, copy your API key, and start checking from your preferred MCP client.

Create a free accountView REST API docs