MCP servers

The AI agent answers from your knowledge base out of the box. MCP servers let it go further: when you connect a server that speaks the Model Context Protocol (MCP), the agent can call your tools mid-conversation — to read live data or take an action in your own systems — and use the result in its reply. This is how you give the agent abilities Chatasist doesn't ship natively, without us building each one.

What you can do with it#

Anything you can expose as a tool, the agent can use. Common examples:

The agent decides whether to call a tool based on the customer's message — it only calls one when it clearly fits, and it never invents a result if the call fails.

How it works#

Chatasist acts as the MCP client; you host the MCP server. Nothing about your data is imported or stored — the agent reads it on demand.

Connect an MCP server#

What your server must implement#

Your server needs to answer two standard MCP calls over JSON-RPC. You don't have to build these by hand — most MCP server frameworks provide them — but here's the contract Chatasist relies on.

1. List your tools — Chatasist calls tools/list; your server returns the tools it offers, each with a name, a description, and an input schema:

{
  "tools": [
    {
      "name": "get_shipping_price",
      "description": "Quote a shipping price. Args: origin (country), weight_grams (int), destination (city).",
      "inputSchema": {
        "type": "object",
        "properties": {
          "origin": { "type": "string" },
          "weight_grams": { "type": "integer" },
          "destination": { "type": "string" }
        },
        "required": ["origin", "weight_grams", "destination"]
      }
    }
  ]
}

2. Run a tool — when the agent decides to use a tool, Chatasist calls tools/call with the tool name and an arguments object. Your server returns a text result:

{
  "content": [
    { "type": "text", "text": "5 kg from China to Baku = 40.40 AZN (pickup)." }
  ]
}

The agent paraphrases that text into its reply. Return a clear, self-contained sentence — the agent reads the text, not your internal fields.

Write tool descriptions the agent can act on#

The agent picks a tool from its name and description alone, so those are your real control surface:

• Say what it's for and when to use it — "Quote a shipping price when the customer asks how much delivery costs," not just "pricing."
• List the arguments and their format — names, types, units (grams vs. kg), and example values. The agent fills arguments from the conversation, so be explicit.
• Keep each tool focused — one job per tool beats one tool with a dozen modes.

Headers we send with every call#

Alongside the credential you configured, each tools/call carries what Chatasist knows about who is asking:

Treat a missing header as "unknown" rather than falling back to a default — an unauthenticated customer and a customer from an unknown country are both real cases.

Confirming who the customer is#

Chatasist never decides that a customer is who they say they are — your server does. There are three ways to tell it, and they can be combined.

1. A signed-in customer on your website or in your app. Mint a short-lived token for the logged-in customer on your side and hand it to Chatasist: to the website widget as customerToken (how), or to the Flutter SDK (1.6.0 or later) through customerTokenProvider or setCustomerToken. It arrives on every call as X-Customer-Token. Refresh it before it expires — the Flutter SDK's provider does that for you. If your server rejects it with HTTP 401, Chatasist repeats that call once without the token, so your public tools keep working and the customer can still confirm by code.

2. A confirmation code, for channels with no login. On Instagram, Messenger, WhatsApp and Telegram there is no session to carry. Offer two tools — one that sends a one-time code to the customer's email or phone, and one that checks it — and have your account tools answer an unconfirmed caller with a tool error that says so. The agent then asks the customer's permission, sends the code, and checks what they read back.

3. Remembering it. So the customer is not asked again on their next message, return a reusable credential from your verify tool as JSON. Chatasist keeps it encrypted and sends it back for you:

Add expires_in (seconds) or expires_at to say how long it is good for. Without either, a customer_token is kept until your server rejects it, and a verification_code for 24 hours. If one response returns both, expires_in and expires_at describe the code; give the token its own lifetime with customer_token_expires_in or customer_token_expires_at, or leave them out to keep it until you reject it.

A customer_token is never shown to the AI agent or kept in the conversation: Chatasist stores it encrypted and adds it to your calls itself. When your server stops accepting it, answer 401 (for a token) or a tool error saying the customer is no longer confirmed. Chatasist then drops it and asks the customer to confirm again.

{ "customer_token": "…", "header": "X-Customer-Token", "expires_in": 1800 }

On a messaging platform the confirmation is remembered for that platform account, across conversations, for as long as you allow. In the website widget it is remembered for that one conversation only. Your team can see and end these links on the customer's profile (see Confirmed accounts).

Personal details in tool results#

Fields that identify a person, such as names, phone numbers, emails, addresses and the recipient, are removed from a tool's JSON result before the agent sees it. Someone who only knows an order number sees its status and dates, not who it belongs to.

They are kept when your server answered a call that carried the customer's confirmation:

• a signed-in customer's token that your server accepted, or
• the verification_code your verify tool returned, passed to a tool that declares a verification_code argument in its input schema (or that refused the call without it).

A public tool that does not take the code, such as order tracking, never shows these details. Make sure a tool that accepts the confirmation returns only records that belong to that customer.

Showing products as cards#

When a tool returns products, the agent draws them as cards rather than writing them out as a list — a picture, the name, the price, and a tap that opens the product page. It uses whatever each channel supports: a scrollable carousel on Messenger and Instagram, a photo with a link button on Telegram, a captioned photo on WhatsApp, and cards in the website widget.

To get the most out of this, return per product:

• An image URL — without one there is no picture to lead with.
• A link to the product page — Chatasist will not build one from a slug or an id, and a card whose link it cannot trace back to your data is shown without one rather than sending the customer to a page that may not exist.
• The price, and when the item is discounted, the pre-discount price and the saving. The agent passes these through as you state them and never works a discount out itself.

When a call fails or finds nothing#

The agent is instructed to never guess. In each of these cases it tells the customer plainly and offers to open a support ticket:

• Unreachable / timeout — your server didn't respond in time.
• Error response — your server returned an error. The agent says it could not check right now; it does not tell the customer their order or record was not found.
• No useful result — the call succeeded but returned no text.
• No matching tool — none of your tools fit the request.

Security#

• You control access. The agent can only call the tools your server exposes, using the auth headers you set.
• Header values are write-only. After saving, Chatasist shows which header names are set but never displays their values again.
• On-demand only. Tools are called during a conversation when relevant — there's no background polling of your server.
• Public HTTPS only. Server URLs must resolve to public addresses; internal or private addresses are rejected.
• Enforce your own rules. Treat every call as untrusted input — validate arguments and apply your own authorization for any tool that takes an action.

Disable or remove a server at any time to immediately stop the agent from using its tools.

Troubleshooting#