MCP Server

Zelnum hosts a public MCP server at https://mcp.zelnum.com/mcp. Any MCP-capable client — Claude, Cursor, an IDE agent — can list products, price a check, run it and read the result without writing integration code. One URL serves every customer: you connect with your own API key, and every charge lands on your own balance.

Endpoint

Setting	Value
URL	https://mcp.zelnum.com/mcp
Transport	Streamable HTTP
Credentials	Authorization: Bearer YOUR_KEY_HERE

The credential is the same API key your REST calls use. Create, rotate and revoke it under API Center in the Console — see Authentication.

Connect a client

Three steps, and nothing is installed.

1. Create a key. Make an API key under API Center in the Console — the same key your REST calls use. See Authentication.

2. Add the server. Cursor and other clients that read the standard mcpServers map can use this entry as it is:

{
  "mcpServers": {
    "zelnum": {
      "url": "https://mcp.zelnum.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY_HERE"
      }
    }
  }
}

Claude takes the same two values through its custom-connector dialog — the URL, and an Authorization header carrying your key.

3. Check the connection. Ask the agent which realtime products it can check. A working connection answers by calling list_products, which is read-only and free, so the check costs nothing. A 401 instead means the key is missing, revoked, or not accepted by the platform.

Tools

Tool	What it does	Billable
list_products	Active product catalog with IDs, slugs and series. Read-only.	No
get_balance	Balance of the account the connection is authenticated as. Read-only.	No
quote_realtime_check	Authoritative price for one check. The only price source an agent should trust.	Free
check_realtime	Run one realtime check against up to ten products.	Yes
create_bulk_task	Submit an inline list for an asynchronous bulk task.	Yes
get_task_status	Progress and billing counters for a bulk task.	No
get_task_result	Result metadata and the authenticated download link for a finished task.	No

Things you can say

Those are the tools; these are the lines you type. Every one of them is served by a tool that already exists — no phrasing is special-cased.

Say this	What happens
Which products can I check in realtime?	Calls list_products and answers with the IDs to use. Free.
What is my balance?	Calls get_balance for the key you connected with. Free.
What would it cost to check +14155550123 on WhatsApp?	Calls quote_realtime_check and shows the price. Free, and nothing is charged.
Go ahead at that price.	Calls check_realtime against the quoted products and charges the quoted total.
Check these 200 numbers for WhatsApp and tell me when it is done.	Calls create_bulk_task, then polls get_task_status and reports progress.
Is that job finished? Send me the download link.	Calls get_task_result and returns the authenticated link.

Two habits worth keeping:

• Ask the price first. A billable tool answers with a quote before it charges, so “what would this cost?” is always free. Only the confirmation moves money.
• Name the country when the number is not E.164. +14155550123 carries its own country; 0812345678 does not, and the gateway refuses to guess.

Confirming a charge

A billable tool never charges on its first call. Called without confirmed, it returns a confirmation payload instead — the products, the count and the estimated cost — together with a quote_token that signs the exact input. Confirm by repeating the same call with:

1. confirmed set to true
2. the quote_token from that payload
3. quoted_total, exactly the amount you were shown
4. the same identifier, products and country

An agent never supplies an idempotency key of its own: the gateway derives one from the signed quote, so the same approved quote keeps the same key across retries, reconnects and gateway restarts. A different charge needs a new quote. After a timeout that leaves the outcome unknown, repeat the identical call rather than changing parameters.

Never confirm silently

An agent must show the estimated cost and get explicit approval before it sets the confirmed flag. A quote expires after five minutes, and a quote whose price snapshot has moved is rejected rather than charged at the new price.

Identifiers

Identifier rules mirror the REST contract, so what an agent validates is what the API accepts:

• Country omitted — the identifier must be a +-prefixed E.164 number.
• Country provided — an uppercase two-letter ISO code, and the identifier is then the national number or an E.164 number.
• The country is never inferred from an ambiguous national number such as 0812345678, which several countries match. Leave the country out only for a complete E.164 number.
• Bulk tasks on phone products require an explicit country.

Money rails

Four rails stand between an agent and your balance:

1. Signed quotes. The platform reads live prices and returns an encrypted quote that binds the account, the exact input, the products and the price snapshot. Changed input, an expired quote or a moved price is rejected before anything is billed.
2. Deterministic idempotency. The idempotency key comes from the signed quote and not from the model, so no wording of a request can turn one approval into two charges.
3. Per-key guardrails. A daily charge ceiling and a balance floor are enforced per API key, and every reservation is serialised before the upstream call, so concurrent agents cannot race past them.
4. Fail closed. If the balance cannot be read, or comes back malformed, billable calls are refused instead of running unguarded.

Errors and limits

• A missing or malformed credential is rejected with HTTP 401 before the request reaches the platform.
• A key the platform does not accept comes back as a tool error carrying the upstream status and body, so the agent reports it rather than retrying blindly.
• Rate limits, error codes and result download behave exactly as they do over REST — the gateway adds no second contract to learn. See Rate limits and Error codes.

Next steps

• Authentication — create the key you will connect with.
• Realtime check — the endpoint behind check_realtime.
• Bulk workflow — the asynchronous path behind create_bulk_task.
• Error codes — the codes the platform returns.