smartchat

MCP server

MCP (Model Context Protocol) is a standard that lets an AI assistant use tools. The SmartChat MCP server gives an assistant most of the abilities of the REST API: read contacts, prepare a newsletter, build an automation, edit the landing page. You decide what the assistant may do. Not every REST call is an MCP tool; the table REST to MCP shows which are.

#Address

The server is at https://api.smartchat.marketing/mcp (Streamable HTTP). There is one server for all assistants.

#Sign-in

You can connect in two ways:

  • OAuth. The assistant opens a consent page. You see which permissions it asks for and agree. The assistant then gets an access token (sc_at_...). The consent page suggests small permissions: the level Read is chosen by default.
  • API key. Paste an API key (sc_...) as bearer token. See Authentication.

Connections of the earlier SmartChat server are not valid any more. Connect again.

#What the assistant can see

The assistant only sees the tools its permissions allow. With the level Read it sees no tool that changes your data, with one exception: it can request a contact export, which creates a file with the data of your contacts. With more permissions more tools appear. See the tool list.

#Built for assistants

  • Each tool has one clear job. Reading and writing are never in the same tool. Names have the form verb_noun, for example search_contacts.
  • Each tool tells the assistant what it does: it only reads, it changes data, it sends messages, it publishes. See the hints on each tool page.
  • Lists have at most 50 items per page (default 20) and use a cursor.
  • Text from contacts is marked with the suffix _untrusted (why).
  • Errors come back as a tool result with isError: true. The error body has a request_id. Keep it and give it to support if you need help.
  • Calls that send messages are checked on the server like REST calls: opt-in, unsubscribed contacts, the 24-hour window and approved templates. See Sending safely.

#Special arguments

Some tools take arguments the REST API sends as headers. An MCP tool call has no headers, so they are normal arguments:

ArgumentWhenWhat it does
idempotency_keyRequired for tools that send messages. Optional for tools that create something.A unique value you make up, for example a UUID. The same key with the same arguments within 24 hours returns the first result and does nothing again.
confirmed_by_userRequired where the tool page lists it (for example unsubscribe_contact). Must be true.Your statement that the user said yes in the conversation. Ask the user first. The server cannot check it, so the assistant must show the question to the user.
detailOptional on some list tools.concise (default) returns a few key fields per item, full returns every field.

Example call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_text_message",
    "arguments": {
      "contact_id": "con_0123456789abcdef0123456789abcdef",
      "text": "Hello, your table is ready.",
      "idempotency_key": "6f1c1f6e-3b7a-4c52-9a43-0f6d2a1c9b11"
    }
  }
}

Without idempotency_key a sending tool answers idempotency_key_required; without confirmed_by_user: true a confirmation tool answers validation_failed.

#What the assistant can never do

There are no tools for deleting data, for the plan or payment, for managing the account or the team, for API keys, for connecting the WhatsApp number or for legal texts. A free text prompt to another AI does not exist either. Uploading knowledge with a model and creating images stay in the app.

#Set up