Let your assistant use your own systems

How it works

MCP (Model Context Protocol) is an open standard for connecting AI assistants to other software. An MCP server offers a list of tools, such as find_slots or my_orders. You connect it once in MagizAI, choose which tools the assistant may use, and from then on it calls them whenever a visitor's question needs one.

1. 01

   Connect

   Skills, then MCP servers. Paste the https address and the token. MagizAI reads the list of tools.

2. 02

   Choose the tools

   Press Manage. Tick the tools to use. Anything unticked is never called.

3. 03

   Safe or Sensitive

   Safe tools run straight away. Sensitive tools wait until the visitor types back a six-digit code, so nothing changes without their go-ahead.

4. 04

   Tie accounts to the sign-in

   For a tool that reads one customer's data, set its email or account argument to "Filled from the signed-in visitor". It is then never taken from the chat.

Limits to design for

These are the real limits of the MagizAI side. A server built within them works first time.

Signed-in customers

Tools such as "my orders" or "my appointments" must only ever show the signed-in customer's own data. MagizAI does this with a signed identity token from your website, never with what the visitor types.

1. In MagizAI, open the chatbot, find Signed visitor identity and generate a secret. Keep it on your server.
2. When a customer is signed in to your website, your backend signs a short token (HS256) with their email and an expiry, and puts it on the widget tag as data-identity.
3. In the MCP tool settings, set the email argument to "Filled from the signed-in visitor". MagizAI fills it from the verified token and refuses the call if the visitor is not signed in.

<?php
// On your server, for the signed-in customer. $secret comes from the chatbot's
// "Signed visitor identity" setting and never goes to the browser.
function magiz_identity(string $email, string $name, string $secret): string
{
    $b64 = fn ($s) => rtrim(strtr(base64_encode($s), '+/', '-_'), '=');
    $head = $b64(json_encode(['alg' => 'HS256', 'typ' => 'JWT']));
    $body = $b64(json_encode([
        'email' => $email,
        'name'  => $name,
        'iat'   => time(),
        'exp'   => time() + 3600,
    ]));
    return "$head.$body." . $b64(hash_hmac('sha256', "$head.$body", $secret, true));
}
?>
<script src="https://magiz.ai/widget.js" data-key="YOUR_WIDGET_KEY"
        data-identity="<?= magiz_identity($user->email, $user->name, $secret) ?>" defer></script>

The token must include exp and can last at most 24 hours. The secret never goes in the browser; only the finished token does. WHMCS sites get this from our WHMCS module automatically.

Examples by business

Each business type has a real use case, a sample conversation, and two ways to do it: a service you can connect today, or a starter program you upload to your own hosting and point at your own data.

Services you can connect today

These services run an MCP server of their own that MagizAI can connect to with a key. Give every key the smallest permissions that do the job: the assistant can only do what the key allows.

Run a starter program

Each starter is a small PHP program with no dependencies. It runs on ordinary shared hosting, comes with demo data so it works the moment you upload it, and has one tools.php file to point at your own database. Needs PHP 7.4 or newer with PDO (SQLite for the demo data, or MySQL).

1. Download the starter for your business and upload its folder to your website, for example to public_html/mcp/.
2. Copy config.sample.php to config.php and set token to a long random secret. The server refuses to run with the sample token.
3. Check it answers. The command below should list the tools.

curl -X POST https://yourdomain.com/mcp/index.php \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. In MagizAI, connect it with the address of index.php and Bearer token authentication, then set the tools as shown on its card.
5. Ask your assistant a question from the chat on your own site. Recent tool calls on the server page shows each call.

Use your real data

Set dsn, db_user and db_pass in config.php to your MySQL or MariaDB database, and change the SQL in tools.php to your own tables. Each tool is one block: a name, a one-line description of when to use it, its arguments, and a function that returns short text.

<?php
// tools.php: one block per tool. $db is a PDO connection from config.php.
$server->tool(array(
    'name' => 'my_orders',
    'description' => 'Use when a signed-in customer asks where their order is.',
    'inputSchema' => array('type' => 'object', 'properties' => array(
        'email' => array('type' => 'string', 'maxLength' => 190),
    ), 'required' => array('email')),
    'annotations' => array('readOnlyHint' => true),
    'handler' => function (array $args) use ($db) {
        $q = $db->prepare('SELECT number, status, tracking FROM orders
                           WHERE email = ? ORDER BY placed_on DESC LIMIT 5');
        $q->execute(array($args['email']));
        $out = array();
        foreach ($q->fetchAll() as $o) {
            $out[] = "#{$o['number']}: {$o['status']} {$o['tracking']}";
        }
        return $out ? implode("\n", $out) : 'No orders found.';
    },
));

Included .htaccess lets the web reach index.php only. On nginx, add the same rule yourself, or the demo database could be downloaded.

Build your own

Any language works if it speaks Streamable HTTP. These are the maintained options.

Rules that make tools work well

• Write one clear sentence per tool saying when to use it. The assistant picks tools by reading these descriptions.
• Mark look-ups with readOnlyHint and anything that deletes or cancels with destructiveHint. MagizAI never lets a destructive tool be marked Safe.
• Validate every argument on your side too, and limit each query to the signed-in customer's own rows.
• Return short text with the facts the assistant needs. Never return passwords, full card numbers or internal notes.
• Treat a tool call like any public API request: check the token, log it, and rate-limit it.

Troubleshooting