Reference

TG Validator MCP reference

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, concurrency limits, timeouts, and result semantics as the REST API.

Products, pricing and limits are in the API reference

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 privateOnly add the key to your own trusted client configuration. Never expose it in browser code or public prompts.

Server URL

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

Item	Value
MCP endpoint	https://tgvalidator.com/mcp
Streamable HTTP	Requests use JSON-RPC over Streamable HTTP and the same API-key middleware as REST.

Connect your client

Choose the configuration format your client supports. Replace the placeholder with your API key.

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

Add the remote server from your terminal.

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

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

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.

Parameters

No parameters

check_number

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

Parameters

service_type · string · required
identifier · string · required

check_numbers

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

Parameters

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

get_balance

Reads the current account balance without charging it.

Parameters

No parameters

Example prompts

After connecting, ask your assistant in plain language:

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

Error handling

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

Example tool error

{
  "code": 42901,
  "msg": "too many concurrent requests",
  "data": null
}

Code	Description
`40000`Invalid product or field	Unsupported service_type or conflicting fields.
`40002`Invalid number	The submitted number is not a valid format.
`40100`Missing or invalid API key	Check the Bearer header and confirm the key is active.
`40200`Insufficient balance	The request is rejected before processing when the full batch amount cannot be covered.
`42200`Undetermined	The number could not be determined at this time. No result is returned, and this call is not charged.
`42901`Concurrency budget full	All five in-flight request slots are busy, or a multi check is already running on this account. Not charged; retry once one finishes.
`50303`Service at capacity	Too many checks are in progress platform-wide. Not charged; wait for the Retry-After seconds and resubmit.
`50400`Check timed out	Did not finish in time. Not charged; a timed-out multi check fails as a whole and is refunded in full.
`50300`Service maintenance	Retry later.