> 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-connect-claude-chatgpt-cursor-and-other-mcp-clients.md).

# MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients

This page shows how to connect the Smartico [MCP Server](https://help.smartico.ai/welcome/technical-guides/mcp-server) to Claude, Claude Code, ChatGPT, Cursor and any other MCP client, how to call it as a plain JSON-RPC API, and where to start when you build your own AI agent in code. Before you start, check [MCP - Who can use it](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-who-can-use-it). For the security model, see [MCP - Connection and security](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connection-and-security.md).

## Before you start

**The address.** Every client connects to one address:

```
https://aichat-api<N>.smartico.ai/mcp
```

`<N>` is the number of the environment of your back office, for example `https://aichat-api2.smartico.ai/mcp` for environment 2. The address must match the environment of your account: a token or a sign-in from one environment is not known on another. After you create a token, **Label → MCP → Access tokens** shows the exact address and ready-made commands. If you are not sure, ask your account manager.

**Two ways to sign in.**

|                            | Sign in with Smartico (OAuth)                                                | Access token                                                                  |
| -------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Works with                 | Claude (claude.ai and Claude Desktop), ChatGPT, Cursor, Windsurf and Gemini  | Claude Code, scripts and any MCP client                                       |
| What you do                | Add the address; a Smartico sign-in page opens; log in and choose the labels | Create a token under **Label → MCP → Access tokens** and add it to the client |
| Labels                     | You choose them on the sign-in page                                          | Chosen on the token                                                           |
| Access profile             | Your own MCP access profile                                                  | The profile chosen on the token                                               |
| Changes are recorded under | You, as a person                                                             | The AI/API user of the label where the token was created                      |

Sign in with Smartico accepts only the clients named in the table. Every other client, Claude Code included, connects with an access token. A token made under **Label → MCP → Access tokens** is a service account token: it belongs to the label, not to a person. Sign in wherever the client allows it.

**The IP allowlist.** If your account uses a back-office IP allowlist, it applies to every MCP request and to the sign-in page.

* Claude's web connectors (claude.ai custom connectors) are accepted without being on the allowlist.
* ChatGPT and other web connectors call Smartico from their own servers. Their IP addresses must be on the allowlist, or their requests are refused.
* Claude Code, Cursor and scripts call Smartico from your own computer or server. That address must be on the allowlist.
* The sign-in page checks the address of your browser.

## Claude (claude.ai and Claude Desktop)

1. In Claude, open **Settings → Connectors** and choose **Add custom connector**. On a Team or Enterprise plan, an owner may need to add the connector for the organisation first.
2. Enter a name, for example `Smartico`, and the address `https://aichat-api<N>.smartico.ai/mcp`. Leave the other fields empty.
3. Click **Connect**. A Smartico sign-in page opens.
4. Log in with your back-office account and choose the labels the connection may use. The page shows your MCP access profile.
5. Approve. Claude is connected. The access does not expire. You sign in again only when your access profile changes or your user is deactivated.

To change the labels later, connect again and choose other labels. Each back-office user has one personal MCP access: a new sign-in, from any client, replaces its labels.

## Claude Code

Claude Code connects with an access token.

1. Create a token under **Label → MCP → Access tokens**: a name, an access profile, the labels. Copy it: it is shown in full only once.
2. In a terminal, run:

```bash
claude mcp add --transport http smartico https://aichat-api<N>.smartico.ai/mcp --header "Authorization: Bearer <token>"
```

3. Run `claude mcp list` to check that `smartico` is connected, or type `/mcp` inside Claude Code.

The labels of a Claude Code connection are the labels of the token. To use other labels, edit the token or create another one.

## ChatGPT

ChatGPT connects through a custom connector. The menu names can differ by plan and workspace.

1. **Allow ChatGPT's IP addresses.** If your account uses a back-office IP allowlist, ask your administrator to add the IP addresses ChatGPT uses for connectors. OpenAI publishes them at `https://openai.com/chatgpt-connectors.json`. The list can change, so check it from time to time. Without this step, every call from ChatGPT is refused.
2. In ChatGPT, open **Settings → Apps & Connectors**. Under **Advanced settings**, switch on **Developer mode** if your plan requires it for custom connectors.
3. Create a connector: enter a name, for example `Smartico`, the address `https://aichat-api<N>.smartico.ai/mcp`, and choose **OAuth** as the authentication.
4. A Smartico sign-in page opens. Log in with your back-office account, choose the labels and approve.
5. In a new chat, turn on the Smartico connector and ask a question.

**Sign-in or token?** Use **Sign in with Smartico** where you can: changes are recorded under your name, and there is no secret to store. If you must use a token, put it in the address: `https://aichat-api<N>.smartico.ai/mcp/<token>`, with no authentication. Anyone who has that address can use the token, so keep it private.

## Cursor and other MCP clients

Add Smartico to the client's MCP configuration file. For Cursor, open **Settings → MCP** (or edit its MCP configuration file):

```json
{
  "mcpServers": {
    "smartico": {
      "url": "https://aichat-api<N>.smartico.ai/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

Save the file and restart the client if it does not pick up the change.

* **Sign in instead of a token:** Cursor and Windsurf can leave out `headers`. The client then opens the Smartico sign-in page.
* **A client that cannot set headers:** put the token in the address instead: `https://aichat-api<N>.smartico.ai/mcp/<token>`.

## Your own AI agent (code example)

To build your own AI agent on the MCP Server, start from the open-source example [smarticoai/simple-mcp-agent](https://github.com/smarticoai/simple-mcp-agent) on GitHub (MIT license). It is a Node.js and TypeScript chat that:

* connects with an access token and uses the server's instructions, so it knows the labels and the access profile of the token;
* gives the MCP tools to Google Gemini as functions and runs the calls the model asks for;
* checks every create or update with `dry_run` and saves only after you confirm.

Only one file talks to the model, so you can switch it to Claude, an OpenAI model or another model.

## Plain JSON-RPC calls

The server is also a plain JSON-RPC 2.0 API over HTTP. You do not need an AI assistant or a special library. Send a `POST` to the address with your token. Set `x-mcp-mode: json` to get standard JSON; the default, `toon`, is a compact format for AI assistants.

List the tools your token may use:

```bash
curl -X POST https://aichat-api<N>.smartico.ai/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-mcp-mode: json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

Call a tool, for example the list of object types:

```bash
curl -X POST https://aichat-api<N>.smartico.ai/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-mcp-mode: json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "entity_types_list", "arguments": {}}}'
```

Every tool that reads or changes data takes an optional `label_id` in `arguments`. Without it, the token's default label is used. For all tools and operations, see [MCP - Tools and entity types](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-tools-and-entity-types.md).

## Choose the labels

* **Sign in with Smartico:** you choose the labels on the sign-in page.
* **Token:** the labels are set on the token under **Label → MCP → Access tokens**.
* **In one conversation:** a connection that covers several labels can work on any of them. Name the label in your request ("on the label …"), and the assistant passes its `label_id`.
* To see the labels of a connection, ask the assistant "Which Smartico labels can you use?". It reads the resource `smartico://labels`.

## Check that it works

1. Ask: *"Which Smartico labels can you use, and what is my MCP access profile?"* The assistant answers from the server: the labels, the default label and the profile.
2. Ask for a read: *"List the five most recent campaigns."*
3. In the back office, open **Label → MCP → Usage**. Your calls are listed there.

If a step fails, see [MCP - Troubleshooting](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-troubleshooting).


---

# 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-connect-claude-chatgpt-cursor-and-other-mcp-clients.md?ask=<question>&goal=<user_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.
