MCP Client v1.00 Nov 2025

TNZ MCP Client

The TNZ MCP Client (Messaging Communications Protocol Client) gives AI and LLM platforms the power to communicate across SMS, Email, Voice and WhatsApp.

The MCP client runs locally on your machine. Your AI tools (like Gemini CLI or Claude Desktop) communicate with the local MCP client which relays your message using TNZ's Python Library. This gives you total control over your data and application logic, passing only necessary data to TNZ.

Core Capabilities

Send Messages:
- SMS - Send text messages to mobile phones worldwide. Use your AI to generate the message content, personalised to the contact.
- Email - Send transactional and marketing emails. Your AI can generate HTML designs and trigger the email to send.
- Voice - Convert text into audio and deliver these as a voice call. Your AI can create a personalised message and track whether the call was answered, direct keypad presses to another AI Agent, etc.
Receive Messages:
- SMS - If a mobile responds to an SMS message, your AI can generate a response or take other actions based ono the content.
- Voice - If the call was answered by voicemail, or the person presses a keypad button, your AI can perform actions.
Manage Contacts:
- Address Book - Create, update, and delete contacts and groups, taking data from other tools in your AI/MCP ecosystem.
- Send To Contacts - Find your contacts and send personalised messages to contacts.
Track Messages:
- Act on Failures - Track delivery results and send follow-up messages or notifications based on the outcome.
- Respond to Questions - When a recipient responds to a message, your AI can generate a response or take other actions based on the content.

Output Warning

LLMs can hallucinate.

The application will be capable of sending real messages, reaching real people and incurring real costs.

It is important to validate any output from your application using the MCP Client. TNZ does not take responsibility for the accuracy of the output generated by your application and fed to the TNZ API using the MCP Client.

Beta Endpoint

The tnz-mcp MCP Client is currently in beta.

As a beta product, endpoints and features may change, and we cannot warrant its stability for production-critical use cases at this time. We are actively developing it and welcome all feedback to help us improve.

This guide currently supports Python integration, with specific examples for Claude Desktop and Gemini CLI. We are actively building support for additional platforms and languages.

Prerequisites

This guide assumes you have a working installation of Python 3.10 or newer and are comfortable with basic command-line operations.

The tnz-mcp client is a Python package distributed via pip. Please ensure your pip is up to date.

Authentication

You must use a valid Auth Token when submitting requests.

To export your Auth Token:

Login to the TNZ Dashboard
Navigate to 'Users'
Create a new user or select an existing one
Enable API access (if it's not already enabled)
Click on the 'API' tab
Enable 'Auth Token' and create a new Auth Token
Click the 'Copy' button to copy it to your clipboard
Use the Auth Token in the Authorization Header when submitting an API call (remember to prefix with Basic, e.g. "Basic ey...0123")

To refresh or invalidate your Auth Token:

Login to the TNZ Dashboard
Navigate to 'Users'
Click on your API user
Click on the 'API' tab
Click on the refresh/recycle button in the Auth Token section
Update your applications to use the new Auth Token

Installation

To install the tnz-mcp client, run the following command in your terminal.

This will download the package from PyPi and install it along with its required dependencies, tnzapi and mcp.

pip install tnz-mcp

Configure Your Auth Token

After installation, you need to import your TNZ Auth Token. There are three common methods.

Method 1: Environment Variable

Set the TNZ_AUTH_TOKEN environment variable in your operating system.

export TNZ_AUTH_TOKEN="Your-Auth-Token-Here"

Replace Your-Auth-Token-Here with your actual TNZ Auth Token.

Method 2: Configuration File

Create a configuration file named tnz_mcp.ini in your project directory with the following content:

[TNZ]
AuthToken = Your-Auth-Token-Here

Replace Your-Auth-Token-Here with your actual TNZ Auth Token.

Method 3: AI Agent Configuration File

If you're using an AI Agent like Claude Desktop or Gemini CLI, you can add the Auth Token directly to the agent's configuration file (e.g. settings.json or config.json).

This is done in the same config.json used to register the MCP client. Include the TNZ_AUTH_TOKEN in the env field of the MCP server configuration. Examples are provided in later in this guide (where the AuthToken is set within the mcpServers configuration).

Note: If the AuthToken is set in the AI agent's config file, it will override any token set via environment variable or tnz_mcp.ini when the server is launched by the AI agent.

Running the MCP Server

The server can run in two different modes - Stdio and HTTP.

Stdio (Default, Local CLI)

In Stdio mode, the MCP client communicates with the AI agent via standard input (stdin) and standard output (stdout) streams. This is the default mode and is recommended for most users.

Use this with command-line tools that can "pipe" their output to another process, such as Gemini CLI and Claude Desktop.

tnz-mcp

HTTP (Remote Access)

To run in HTTP mode, add the --http flag with a host and port. This starts a local web server on the specified port (e.g., 8080).

Use this for applications that communicate over HTTP, such as web browsers or remote clients. This mode is useful for remote access scenarios or when used with Claude Desktop's local server tool.

This starts the server on http://localhost:8000:

tnz-mcp --transport streamable-http --host localhost --port 8000

Features

Messaging: Send SMS, Email, Voice and Fax messages.
Reports: Check message status, SMS replies, and received messages.
Addressbook: Manage contacts, groups, and relationships.

Usage

Trigger messages:

Send an SMS to +64211231234 with message "Test using MCP" using tnz-mcp

Send an SMS to TNZ Address Book contact "John" with message "Test using MCP" using tnz-mcp

Send an Email to TNZ Address Book contact "John" with a beautifully designed HTML email for my business using tnz-mcp

Send a Voice call to +6495006000 with message "Test using MCP" using tnz-mcp

Check outcomes:

Check my SMS to +64211231234 for delivery results using tnz-mcp

Check for SMS replies from TNZ Address Book contact "John" using tnz-mcp

Update contacts:

Create a new TNZ Address Book contact called "Jared" with mobile phone number +6427400400 using tnz-mcp

Add my new TNZ Address Book contact "Jared" to the "VIP" group using tnz-mcp

Find any TNZ Address Book contacts with Mobile Phone number +6427400400 using tnz-mcp

Remove any TNZ Address Book contacts with Mobile Phone number +6427400400 using tnz-mcp

Configuring AI Tools

Configuring Gemini CLI →

Configuring Claude Desktop →

Troubleshooting & FAQ

Why does the MCP client run client-side?

A key feature of this client is that it runs on your machine, not on TNZ's infrastructure. This provides two major benefits:

Data Privacy: Your prompts, logic and generated content remain on your machine. Only the final, approved message payload (e.g. the recipient number and the message text) is securely sent to the TNZ API for delivery.
Better Performance: Your AI application communicates locally and minimises network latency; important for applications that require real-time interactions.

I'm using a different platform. Can you support this?

We have tested the MCP client using Python (pip) with Gemini CLI and Claude Desktop.

If you are using another platform, please contact TNZ for support.

Does using the MCP client cost extra?

As the MCP client runs on your infrastructure, there are no additional costs from TNZ for using the MCP client itself. You pay for the messaging usage, similarly to using the TNZ API directly.

Can I test whether my MCP server is active?

Yes - you can use MCP Inspector.

MCP Inspector is a dedicated command-line tool designed to confirm that tnz-mcp is correctly implemented.

If using stdio mode, run:

npx @modelcontextprotocol/inspector --transport stdio

If using HTTP mode, run:

npx @modelcontextprotocol/inspector --transport http --url http://localhost:8000

Can I test whether tnz-mcp is correctly installed?

Yes - a unit test is a good fit for this.

Unit tests are focused on the internal application logic of the TNZ MCP Python package. These tests do not rely on the external MCP protocol or the AI client; they simply verify that the functions within the plugin work as expected.

If you have cloned the tnz-mcp repository, you can run the built-in tests using the Python unittest module:

python -m unittest discover tests

A successful run should show an "OK" message, indicating that all internal logic checks within the tnz-mcp package have passed.

I'm receiving a 401 Unauthorized error?

Your Auth Token is likely incorrect, expired, or the user it's linked to does not have API Access enabled. Please re-check your token in the TNZ Dashboard.

I'm receiving a Connection Refused error?

If using HTTP mode, ensure you are connecting to the correct port (e.g., localhost:8080). Check that no other service is using that port.

I'm receiving a Tool Not Found error?

The MCP server is likely submitting a JSON payload to the TNZ API that doesn't include a tool parameter (e.g. "tool": "send_sms"). Contact TNZ for troubleshooting.

We want your feedback!

This is a beta product, and your feedback is critical. Please contact our support team with any bug reports, feature requests, or success stories.