> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How the Atoti MCP Server works

> How the Atoti MCP Server works once set up, the `/mcp` endpoint and its Streamable HTTP transport, the Extension license tier that gates it, how a client authenticates, and which tools it exposes.

<Info>
  ### Atoti Intelligence SDK

  This is part of the Atoti Intelligence SDK offer.
</Info>

The Atoti MCP Server exposes Atoti's cube tools to external MCP clients, once it is set up. This
page covers the behavior shared by both SDKs; setting the server up is SDK-specific.

<Note>
  To set up the MCP Server, see [How to set up the Atoti MCP Server in Java](./setup-java) or
  [How to set up the Atoti MCP Server in Python](./setup-python). For what the MCP Server is and why
  to use it, see [What is the Atoti MCP Server?](../introduction).

  The Atoti MCP Server requires the Atoti Intelligence Extension tier, which itself requires
  Essentials.
</Note>

## Where is the MCP endpoint?

On a Java application, the MCP Server answers `POST /mcp`. On a session started from the Atoti
Python SDK, it answers `f"{session.url}/mcp"`. Both speak the Streamable HTTP transport.

Spring AI's own default transport is the older server-sent events transport, `SSE`. Atoti overrides
that default: a property contributed at the lowest precedence sets
`spring.ai.mcp.server.protocol=STREAMABLE`. An application that sets the property itself always wins
over it.

The server-sent events transport at `/sse` is deprecated for removal in Spring AI 2.0.0. Prefer
`/mcp` everywhere.

## Which license tier does the MCP Server require?

The Atoti MCP Server requires a license including the Atoti Intelligence Extension tier, which
itself requires Essentials. The Extension tier gates the whole MCP surface:

* The MCP Server itself
* Its OAuth 2.1 discovery and self-issued authorization-server modes
* The credentials page
* Connecting out to other MCP Servers

Essentials alone is enough for the cube tools to exist. Chat and Auto-Explain already call them
internally under Essentials.

The Extension tier does not add new tools. It exposes the existing ones
externally, at the MCP endpoint, to any MCP client.

## What happens when the license does not include the Extension tier?

When the license lacks the Extension tier, Atoti forces `spring.ai.mcp.server.enabled=false` at the
highest property precedence. The property cannot be overridden, even when set to `true` the forced value `false` wins. A warning is logged naming the `ai-extension` license component.

A license without Essentials does not start the server.

## How does an MCP client authenticate?

The MCP endpoint and the deprecated `/sse` endpoint sit behind their own security filter chain. It
requires an authenticated user holding a user or admin role. Each SDK implements this separately.

* On a Java application: the required roles are the combined set of configured admin roles and user
  roles.

* On a session started from the Atoti Python SDK, the required roles are `ROLE_USER` or `ROLE_ADMIN`.

Only an authenticated user holding one of those roles is admitted. `OPTIONS` requests are permitted without authentication, for CORS preflight.

The accepted credentials are the ones Atoti's machine-to-machine security allows everywhere: HTTP
Basic, and a bearer JWT.

An unauthenticated request is answered `401 Unauthorized`. When OAuth 2.1 discovery is enabled, that
response additionally carries `WWW-Authenticate: Bearer realm="mcp", resource_metadata="..."`. A
compliant MCP client reads that header to discover the authorization server. It then drives the
browser PKCE flow with no manual token handling. See
[Configure OAuth 2.1 discovery](./configure-oauth2-discovery) and
[Configure self-issued OAuth 2.1](./configure-oauth2-self-issued) for the two modes.

The opt-in [MCP credentials page](./mcp-credentials-page) is the alternative to embedding a
password in a client configuration. A signed-in user mints a long-lived bearer token once, then
pastes it into the client.

## Which tools does the MCP Server expose?

The MCP Server exposes the same built-in cube tools that chat and Auto-Explain use internally:

* Discovery tools, for cube names, dimensions, hierarchies, levels, members, measures, and KPIs
* Validation tools, for checking that a measure, level, hierarchy, or dimension exists
* MDX query tools, including `runMdxQuery` and `getAvailableCubeNames`
* Auto-Explain tools, for running an analysis, listing analyses that already ran, and dropping one

[Custom tools](../custom-tools) add to that set.

The tools from other MCP Server can be exposed by the Atoti server they are connected to.
This means that:

* A single Atoti Server can show an external client the tools of a whole deployment.
* Each client is told only what its own credential can reach. See
  [How connecting to other MCP Servers works](../connect-to-other-servers/how-it-works).

One tool is the exception. `getConnectedServers` is registered for chat only, never on the MCP
endpoint. It puts deployment-internal addresses into the prompt.
No LLM is required to expose or call these tools. An LLM is only required for chat.

## What does each SDK decide?

Server set up follows the same pattern for both Java and Python set up:

1. Install a package
2. Supply minimal or no configuration
3. The server is available.

However, Atoti Java SDK and Atoti Python SDK do not share the same configuration:

|                                     | Java                                                                                  | Python                                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Setting the server up               | Two Maven dependencies. See [Set up in Java](./setup-java).                           | `uv add "atoti[ai]"` and an empty `AiConfig()`. See [Set up in Python](./setup-python). |
| Custom tools                        | Spring beans. See [How to add custom tools](../custom-tools).                         | No configuration exposed.                                                               |
| OAuth 2.1 modes                     | Spring properties. See [Configure OAuth 2.1 discovery](./configure-oauth2-discovery). | No configuration exposed.                                                               |
| Connecting out to other MCP Servers | See [Connect to other MCP Servers in Java](../connect-to-other-servers/setup-java).   | See [Connect to other MCP Servers in Python](../connect-to-other-servers/setup-python). |

## Related reading

* [How to set up the Atoti MCP Server in Java](./setup-java) and [in Python](./setup-python)
* [What is the Atoti MCP Server?](../introduction)
* [How to add custom tools](../custom-tools)
* [How connecting to other MCP Servers works](../connect-to-other-servers/how-it-works)
* [Configure OAuth 2.1 discovery](./configure-oauth2-discovery) and
  [Configure self-issued OAuth 2.1](./configure-oauth2-self-issued)
* [MCP credentials page](./mcp-credentials-page)