> ## 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.

# Migration notes

> What to change in your application when upgrading Atoti Intelligence from one version to the next.

For a detailed list of all changes, see the [Changelog](./changelog).
For details about versioning, see our [Versioning Policy](https://docs.activeviam.com/atoti-eos.html).

## 6.2.1

\{@today: -}

### Chat and Auto-Explain REST namespaces

Chat and Auto-Explain each have their own REST namespace, so the two features version independently:

| Feature      | Address                              | Namespace on `/versions`    |
| ------------ | ------------------------------------ | --------------------------- |
| Chat         | `/activeviam/ai/chat/rest/v1`        | `activeviam/ai/chat`        |
| Auto-Explain | `/activeviam/ai/autoexplain/rest/v1` | `activeviam/ai/autoexplain` |

<Info>
  No action is required to upgrade.
</Info>

The addresses these replace — `/activeviam/ai/rest/v2/chat` and `/activeviam/ai/rest/v2/autoexplain` — keep answering with the same payloads, and the `activeviam/ai` namespace stays advertised on `/versions`, which is how Atoti UI and the Atoti Python SDK detect that Atoti Intelligence is available. Both addresses are served by the same instances, so a conversation started on one is visible from the other and you can migrate one caller at a time.

The new addresses are versioned from `v1` because their namespaces are new; the payloads are those the old addresses served as `v2`. The old addresses are deprecated and will be removed in a future major release, so move your own callers to the new ones when convenient.

If you secured the AI endpoints with your own filter chain rather than the built-in one, extend its matcher to cover `/activeviam/ai/chat/rest/**` and `/activeviam/ai/autoexplain/rest/**`.

### Connecting to other MCP servers

Atoti Server can now connect out to other MCP servers, typically the other Atoti Server instances of the same deployment, and use their tools as its own, both in chat and on its own MCP endpoint. An application that declares no connection is unaffected.

A connection is declared under Spring AI's own `spring.ai.mcp.client.streamable-http.connections` prefix, and `authentication` is the only key Atoti adds to it. That key selects how this server identifies itself to the remote one: `none`, the default, sends no credential, `atoti-jwt` mints a token for the calling user, and `pass-through` forwards the token that user presented. Every mode but `none` derives its credential from the calling user's security context, so a remote tool runs under the identity of whoever triggered it and the remote cube's role-based data restrictions stay in force.

A new `getConnectedServers` chat tool reports which servers can answer: first the one the chat is running on, marked `current: true` and addressed up to its context path, then each connected server with its address, its tool prefix, and whether the calling user can reach it. It is registered for chat only, never as a `ToolCallbackProvider` bean, since it puts the deployment's internal addresses into the prompt, from where they reach the model provider and any user who can chat.

Two points to settle before declaring a connection. Write `atoti-jwt` only for a server of the same deployment, since the token it mints is accepted by every server sharing the deployment's signing key. And declare the connection under `streamable-http`, the only outbound transport supported: one declared under `spring.ai.mcp.client.sse.connections` is reported at startup as unsupported, carries no credential whatever `authentication` says, and is absent from `getConnectedServers`.

The connected servers' tools are also reported on this server's own MCP endpoint, per calling client. Nothing has to be enabled and no service account is needed: an MCP client authenticates to this server before it can ask for tools, so Atoti lists each connected server with that user's own credential. Spring AI's `spring.ai.mcp.server.expose-mcp-client-tools` is a different, fixed-list mechanism and is not needed; leave it unset. This applies to the Streamable HTTP transport, which is the default.

This capability requires the Atoti Intelligence Extension tier. See [How connecting to other MCP Servers works](../developer-guide/mcp-server/connect-to-other-servers/how-it-works) for the authentication modes in full, remote tool naming, `getConnectedServers`, how the remote tools reach this server's own MCP endpoint, and what an unreachable remote server costs.

### Spring AI MCP client defaults

Two Spring AI defaults change for applications that already declare MCP client connections. Atoti contributes these defaults at the lowest precedence, so a property already set by the application still wins.

* `spring.ai.mcp.client.initialized` now defaults to `false` instead of Spring AI's `true`. With the previous default, Spring AI performed the MCP initialize handshake with every declared server while the application context was being built, before any user had authenticated. Against a secured remote server this failed with a 401 error and took startup down with it; against an unsecured one it opened a session belonging to nobody. Connections are now established lazily on first use, which happens while serving a user's request, so the handshake carries that user's credential like every later request of the session.
* `spring.ai.mcp.client.toolcallback.enabled` now defaults to `false`, handing tool listing to an Atoti provider that lists each server separately. Spring AI's stock provider lists all servers in a single stream, so one unreachable peer aborts the whole listing, and with `expose-mcp-client-tools` enabled, that listing happens at startup and would stop the server from booting. A peer is a remote dependency, not a prerequisite: failures are not cached, so a server that was down is retried on the next request. Successful listings are cached per calling identity rather than once for the whole application, so one user's list is never served to another. Setting the property back to `true` restores Spring AI's provider and gives up all three of those guarantees; Atoti logs a warning naming them at startup when you do.

`starter-ai-mcp-server` now also pulls in `org.springframework.ai:spring-ai-starter-mcp-client` (the JDK `HttpClient` variant, matching the servlet stack) as a mandatory dependency.