## Related terms

- workspace
- user

See the [glossary](/glossary.md) for definitions.

---

# Getting started



<div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content">

This feature is available in [public preview](/docs/log-in-and-navigate-synerise-platform#public-preview) mode.

</div></div></div>


This page explains how to connect the Synerise MCP Server. The setup takes a few minutes and does not require writing any code.

## Prerequisites
---

Your AI client acts on your behalf, so it can only perform actions that are both allowed in the workspace settings and permitted by your user permissions. Before you start, make sure that:

- A user with the PROFILE_ADMIN role has enabled access for external AI clients in the [Synerise MCP Server settings](/docs/settings/agentic-ai/external-ai-clients-mcp) of the workspace you want to connect. By default, this access is disabled.
- If you want your AI client to create or edit resources, a user with the PROFILE_ADMIN role has also enabled the **Write** action in **Settings > Synerise MCP Server** (see [Allowed actions](/docs/settings/agentic-ai/external-ai-clients-mcp#allowed-actions)). Without it, only the tools that read data are available.
- You have a **Synerise account** with access to that workspace, the [MCP Server permission](/docs/settings/identity-access-management/permissions/ai-hub-permissions#use-the-synerise-mcp-server), and read permissions for the product areas you want your AI client to access. For example, without analytics permissions, analytics tools will return an authorization error when called. To create or edit resources, you also need the `create` or `edit` permissions for those product areas and for **AI Agents** > **MCP Server**.






## Configuration
---

The following example shows how to connect the Synerise MCP Server to Claude Code.

### One-time setup

Add the server using the Claude Code CLI:

```bash
claude mcp add -s user --transport http synerise-ai <MCP_ENDPOINT>
```

Replace `<MCP_ENDPOINT>` with the API URL for the data center where your workspace is hosted. See [Regional endpoints](#regional-endpoints) for the full list.

Then, in a Claude Code session, run:

```bash
/mcp
```

This starts the login flow and lets you select which Synerise workspace to connect.


<div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content">

The token is workspace-scoped; you choose the workspace when you log in. To switch workspaces, run `/mcp` again and log in with a different workspace.

</div></div></div>


The tools are usually available as soon as you log in. If they don't show up, restart Claude Code.

### Connecting several workspaces

To work with more than one workspace without logging in again, add the server several times under different names, one for each workspace:

1. Add the server once for each workspace, giving each server a different name. If two workspaces are hosted in the same data center, use the same endpoint URL for both.  
    For example:
    ```bash
    claude mcp add -s user --transport http synerise-ai-store-eu https://api.synerise.com/mcp
    claude mcp add -s user --transport http synerise-ai-store-us https://api.azu.synerise.com/mcp
    ```
2. Run `/mcp`.
3. Log in to each server separately, selecting a different workspace for each one.

Each connected server exposes the same tools, so your AI client may call a tool in a different workspace than you intended. To avoid this:
- Use server names that clearly identify the workspace.
- Name the workspace in your prompts.
- Before you create or change data, ask your AI client which workspace it's connected to. The AI client checks this with `account_whoami`.

### Changing the endpoint

If you added the server with the wrong endpoint, for example, for a different data center, remove the server and add it again:

1. Remove the server:
    ```bash
    claude mcp remove synerise-ai-store-eu
    ```
    Replace `synerise-ai-store-eu` with the name of your server. To check the names of your servers, run `claude mcp list`.
2. Add the server with the correct endpoint:
    ```bash
    claude mcp add -s user --transport http synerise-ai-store-eu <MCP_ENDPOINT>
    ```
    Replace `<MCP_ENDPOINT>` with the correct URL from [Regional endpoints](#regional-endpoints).
3. In a Claude Code session, run `/mcp` and log in again.

### Troubleshooting

- **Server not listed as connected** - run `claude mcp list` and confirm `synerise-ai` shows as `✓ Connected`.
- **"Authentication required" when calling a tool** - run `/mcp` and log in again.
- **Tools not showing up** - restart Claude Code.
- **Token expired** - run `/mcp` and re-authenticate.


## Verifying the connection
---

After the server is connected, you can verify it by asking:

> *What Synerise workspace am I connected to?*

Your AI client calls the `account_whoami` tool and returns the ID and name of the workspace you are connected to. If the server is not connected, your AI client will not be able to answer and will indicate that the tool is unavailable.


## Regional endpoints
---

The MCP endpoint depends on the data center where your workspace is hosted:

| Hosting | MCP endpoint |
|---|---|
| Azure EU | `https://api.synerise.com/mcp` |
| Google Cloud Platform | `https://api.geb.synerise.com/mcp` |
| Azure US | `https://api.azu.synerise.com/mcp` |

If you are not sure which data center your workspace uses, check the URL to which you log to the Synerise application.


## Permissions and data access
---

The Synerise MCP Server acts on your behalf using the [permissions of the Synerise account](/docs/settings/identity-access-management/permissions#which-permissions-do-i-need) you log in with. The operations the server can perform also depend on the allowed actions in the [Synerise MCP Server settings](/docs/settings/agentic-ai/external-ai-clients-mcp#allowed-actions) of the workspace: with **Read**, the server can retrieve, list, and calculate data, and with **Write**, it can also create and edit resources. There are no tools for deleting resources, but some write tools replace or clear existing data. In [Available tools](/developers/mcp/available-tools), the description of each such tool says what it replaces or clears. For example, tools marked "Full replace: omitted fields are cleared" clear the fields you don't send again.

If your account does not have access to a particular resource (for example, loyalty promotions or CRM contacts), your AI client will receive an authorization error when it tries to retrieve that data and will inform you accordingly.


<div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content">

Depending on your permissions, tool results may include personal data or other sensitive information. See [Data privacy and third-party AI clients](/developers/mcp/overview#data-privacy-and-third-party-ai-clients) before connecting an AI client. For answers to questions about the EU AI Act and data processing, see the [Synerise MCP Server FAQ](/developers/mcp/faq).

</div></div></div>



## Troubleshooting
---

**Your AI client says the Synerise tools are not available**

The MCP server is not connected. Check the following:

- Confirm you added the server correctly. If you did, fully restart your AI client.
- Run the login command again (for example, `/mcp` in Claude Code) to check the connection status and re-authenticate if needed.
- Open your AI client's MCP log or developer console to see if the connection failed.

**Your AI client says authentication is required**

Your login session has expired or was never completed. Re-run the login command (for example, `/mcp` in Claude Code) and log in again.

**Your AI client receives a 403 Forbidden error**

The requested operation isn't allowed. Check the following:

- Your account has the **AI Agents** > **MCP Server** permission and access to the relevant product area. See ["Use the Synerise MCP Server" in "AI Hub permissions"](/docs/settings/identity-access-management/permissions/ai-hub-permissions#use-the-synerise-mcp-server).
- If your AI client tries to create or edit a resource, both the **Write** action in the [Synerise MCP Server settings](/docs/settings/agentic-ai/external-ai-clients-mcp#allowed-actions) and the `create` or `edit` permission for **AI Agents** > **MCP Server** must be allowed.

**Your AI client is connected to the wrong workspace**

The token is workspace-scoped, chosen when you log in. Log in again and select the correct workspace.

**The server starts but returns no data**

Confirm that the workspace you are connected to contains the data you are asking about. For example, if you ask for recommendation campaigns and none exist, the tool returns an empty result; this is expected behavior, not an error.

## What's next
---

Once your connection is verified, you can start using the Synerise MCP Server straight away: just ask your AI client questions about your workspace and it will use the available tools automatically. If you want to know what tools are available and what each one does, see [Available tools](/developers/mcp/available-tools).
