> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connection-and-security.md).
# MCP - Connection and security
This page explains how to connect to the [MCP Server](/welcome/technical-guides/mcp-server.md) — from your own AI assistant or directly as an API — how sign-in works, what happens on each request, and the security model. For what you can do once connected, see [MCP - Tools and entity types](/welcome/technical-guides/mcp-server/mcp-tools-and-entity-types.md). Before you connect, check [MCP - Who can use it](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-who-can-use-it). For step-by-step instructions per client, see [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients).
## Two ways to use it
You can use the MCP Server with your own external AI assistant or as a direct API from your own code.
### Option A — Connect your own AI assistant
Add Smartico as an MCP connector in your assistant, using the endpoint below, and start a conversation — the assistant discovers the available tools automatically. There are two ways to authenticate the connection (see [Authentication](#authentication)):
* **Sign in with Smartico (OAuth)** — the recommended option. Point the assistant at the MCP endpoint; it opens a Smartico sign-in page where you log in and choose which label(s) to grant, then connects automatically. Nothing to copy or paste.
* **Static MCP token** — create a token in the back-office and add it to the connector.
{% hint style="info" %}
**Before you start with a static token,** you need back-office access to obtain your label's MCP connection token. If you can't find it, contact your Smartico account manager.
{% endhint %}
**Step 1 - Create an MCP token** (static-token path)
Generate a token in the backoffice. You can create more than one - for example, a separate token per tool, integration, or teammate - and give each a recognizable name. A token may be scoped to one or more labels your user can access.
1. Log in to the Smartico backoffice.
2. Open the **MCP** section and go to **Access tokens**.
3. Click **Create token**, enter a name, choose an **Access profile** (such as MCP Viewer, MCP Editor, MCP Analyst, or MCP Full access), select the authorized labels, and copy the token. It is shown in full only once at creation — afterward, it is masked and cannot be retrieved. For details on privilege tiers, see [MCP Access Profiles](/welcome/technical-guides/mcp-server/mcp-access-profiles.md).
{% hint style="warning" %}
Treat your MCP token like a password. Don't share it or paste it into untrusted tools. If it's ever exposed, deactivate it from the **Access tokens** screen and generate a new one.
{% endhint %}
**Step 2 - Add Smartico to your AI assistant**
If your assistant supports OAuth, point it at the MCP endpoint and complete **Sign in with Smartico** — no token to paste.
If you are using a static token, the quickest way to connect (for example in **Claude Code**) is to run a single command. In a terminal, run:
```bash
claude mcp add --transport http smartico https://aichat-api.smartico.ai/mcp --header "Authorization: Bearer "
```
Replace:
* `` with your Smartico environment number - for example `aichat-api2.smartico.ai`. If you're unsure which environment you're on, check with your account manager.
* `` with the MCP token you copied in Step 1.
That's it - your assistant is now connected to Smartico.
{% hint style="info" %}
**Prefer editing the config file?** Instead of the command, you can add the same entry to your AI client's MCP configuration file by hand:
```json
{
"mcpServers": {
"smartico": {
"url": "https://aichat-api.smartico.ai/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
Save the file and restart your AI client so it picks up the new connection.
{% endhint %}
**Connecting with web AI assistants (Claude, ChatGPT custom connectors):** In your AI client's settings, open Connectors → Add custom connector and enter your environment connector URL. Choose **Sign in with Smartico** where the client supports it; otherwise put the token in the URL path: `.../mcp/`. If your account uses a back-office IP allowlist, add the IP addresses of ChatGPT and other web connectors to it first, or their requests are refused. Claude's web connectors are accepted without it. Steps for each client: [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients).
**Step 3 - Start a conversation**
Once connected, just describe what you want. For example:
> *"Connect to Smartico and create a segment of users who haven't deposited in the past 14 days but logged in at least once."*
The AI assistant automatically discovers the right properties in your label, assembles the configuration, validates it, and asks you to confirm before saving.
### Option B — Call it directly as an API
The server speaks **JSON-RPC 2.0** over HTTP. Send a `POST` to the `/mcp` endpoint with your token; clients that stream responses also open a `GET` connection to the same endpoint. Any HTTP client works — no special library required.
**Endpoint**
```
https://aichat-api.smartico.ai/mcp
```
Use the URL for your environment (your Smartico contact can confirm it). Example: `aichat-api2.smartico.ai`.
**Headers**
| Header | Value |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `Authorization` | `Bearer ` (a bare token is also accepted) |
| `Content-Type` | `application/json` |
| `x-mcp-mode` | `json` for programmatic clients (returns standard JSON). The default, `toon`, is a compact format optimised for AI assistants. |
If your connector can't set custom headers, put the token in the URL path instead: `.../mcp/`.
**Example - list active real-time automation rules**
```bash
curl -X POST https://aichat-api.smartico.ai/mcp \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-H "x-mcp-mode: json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "entity_list",
"arguments": {
"entity_type": "automation_rule",
"filters": { "rule_type_id": 1, "is_active": true },
"limit": 10
}
}
}'
```
{% hint style="info" %}
**Preview before you commit.** `entity_create` and `entity_update` accept a `dry_run` option. With `dry_run: true` the request is validated and a preview of exactly what would be built is returned - nothing is saved. With `dry_run: false` the change is committed. We recommend a dry run before creating or updating any record. `exec_operation` also supports `dry_run`.
{% endhint %}
**Building your own AI agent?** Start from the open-source example [smarticoai/simple-mcp-agent](https://github.com/smarticoai/simple-mcp-agent) on GitHub: a Node.js and TypeScript agent that connects with a token, gives the MCP tools to an AI model and previews every change with `dry_run`.
## Authentication
You can connect in one of two ways.
### Sign in with Smartico (OAuth)
For AI assistants that support OAuth, this is the easiest and most secure option — there's no token to create, copy, or store.
1. Add the Smartico MCP endpoint to your assistant.
2. The assistant discovers Smartico's OAuth configuration automatically and opens a **Smartico sign-in page** in your browser.
3. You log in and **choose which label(s)** the connection may access.
4. On approval, the assistant is connected. The access it receives does not expire, so you don't have to reconnect — unless your access profile changes or your back-office user is deactivated.
Behind the scenes this maps to your back-office user and issues a personal access scoped to the labels you approved — the same permission model as a token. Each back-office user has one personal MCP access: signing in again, from any assistant, replaces the labels it may use. It uses standard **OAuth 2.0**, so any OAuth-capable MCP client works without manual configuration.
### Static MCP token
Create an **MCP token** in the Smartico back-office (see Step 1 under Option A) and give it to your connector or script. Treat it like a password — it grants access at your user's permission level.
* Pass it in the `Authorization` header as `Bearer ` (a bare token is also accepted).
* If your connector can't set custom headers, put it in the URL path instead: `.../mcp/`.
## How a request works
Whichever method you use, the flow is designed so that nothing is saved without your approval:
1. You (or your assistant) call a tool with its arguments — in plain language, or as an API call.
2. The server authenticates your token and resolves it to a **label**. If you passed an optional `label_id`, it must be one your token is authorized for; otherwise the token's default label is used.
3. The assistant (or your code) explores your label to find the right properties, events, activities, or other records.
4. The tool runs against your back-office, applying the same validation the UI does. Writes can be previewed with `dry_run: true` — no changes are made yet.
5. You review a plain-language summary (or the dry-run preview) of exactly what will be created or changed.
6. You confirm, and only then is the change saved. A link to the affected record in the backoffice is returned.
## Security & permissions
* **Access = user + label + access profile.** Whether you connect with OAuth or a static token, the connection is scoped to an access profile (such as MCP Viewer, Editor, Analyst, or Full access) and a set of authorized labels. For comprehensive profile configuration details, see [MCP Access Profiles](/welcome/technical-guides/mcp-server/mcp-access-profiles.md).
* **Per-label authorization.** A token may be scoped to several labels. Any tool call can target one of them with the optional `label_id` argument; a label the token isn't authorized for is rejected.
* **Same rules as the UI.** Creates and updates go through the same validation as the back-office forms, so MCP can't write data the platform would reject.
* **Create and name multiple tokens.** Issue separate tokens per tool, integration, or teammate, each with its own name, so you can track and revoke them independently. Anyone with a token can act at your user's permission level, so manage them accordingly.
* **Copy a token once.** The full token is shown only at creation and is masked afterward — store it securely, and generate a new one if it's lost.
* **Nothing changes without approval.** Reference and catalog types and the knowledge tools can't change anything. The read tools are marked read-only, so an assistant may run them without asking. The tools that write — `entity_create`, `entity_update`, and `exec_operation` — are not, so assistants that follow these markings ask a person to confirm them. Use `dry_run` to preview before committing.
* **Tokens can be revoked at any time.** Deactivate a token from the **Access tokens** screen, and access is lost immediately.
* **Changes are attributed.** Changes made with a static MCP token are recorded under a dedicated AI/API user of the label where the token was created, so integration changes are easy to distinguish from manual changes in your change history. Changes made through **Sign in with Smartico** are recorded under your own back-office user.
* **Usage is logged.** Every tool call is recorded and visible in the backoffice under **MCP → Usage**, where it can be filtered by tool, entity type, and token, so label activity can be reviewed and audited.
To see the labels a token can use, read the resource `smartico://labels`.
## Frequently asked questions
**Which AI assistants are supported?** Any MCP-compatible client, including Claude, Claude Code, ChatGPT and Cursor. Claude, ChatGPT and Cursor can connect with **Sign in with Smartico**; Claude Code and other clients use a static MCP token. If your account uses a back-office IP allowlist, ChatGPT and other web connectors need their IP addresses on it. See [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients).
**Where do I generate and manage MCP access tokens?** In the Smartico back-office, navigate to **MCP → Access tokens** and click **Create**. You can assign a descriptive name and select which label(s) the token can access. The full token is displayed only once upon creation; make sure to copy and store it securely.
**What should I do if the MCP section is not visible in my back-office menu?** Access to the MCP menu (Access tokens, Access profiles, Playground, Usage) requires the feature to be enabled for your label and granted to your user permission group. If the **MCP** section is missing from your navigation menu, contact your Smartico account manager or support team to enable MCP access for your account. For the full checklist, see [MCP - Who can use it](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-who-can-use-it) and [MCP - Troubleshooting](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-troubleshooting).
**How do I know which environment endpoint URL to use?** The environment number in your connection URL matches the environment hosting your Smartico back-office (for example, environment 6 uses the environment 6 AI API endpoint). You can find your exact endpoint URL and pre-formatted configuration commands in the back-office under **MCP → Access tokens** after creating a token.
**Can team members connect their own AI assistant accounts individually?** Yes. Using OAuth (**Sign in with Smartico**), each team member logs in with their own back-office credentials and selects their authorized labels. All actions are scoped to that user's permissions and MCP access profile, and audit logs attribute changes to the individual user.
**Do back-office IP allowlist restrictions apply to MCP connections?** Yes. If your account enforces an IP allowlist, every MCP request must come from an allowed IP address — with a static token and with **Sign in with Smartico** alike, and the sign-in page itself checks it too. The allowlist of the token owner's account applies; for a static token, that is the label where the token was created. Claude's web connectors (claude.ai custom connectors) are accepted without being on your allowlist; other web connectors, such as ChatGPT, are not, so their requests are refused unless their addresses are allowed.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connection-and-security.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
