Nacos 3.3: AI Agent Registry, MCP Lifecycle, DNS Discovery & Spring Boot 4 Support

01 New Features (Feature)

Optional DNS service discovery via UDP/TCP with A, AAAA, SRV record resolution, metrics, and configurable external DNS forwarding.

Neutral JSON adapter supporting both Jackson 2 and Jackson 3 runtime environments.

Protocol-neutral Agent lifecycle management, console workflows, RAD (Resource/Agent Discovery), runtime endpoints, transport protocol negotiation, Watch/Push mechanisms, and Java SDK.

Distributed reentrant and non-reentrant locks with watchdog auto-renewal, FIFO queuing, gRPC change notifications, Raft strong consistency, and Java Lock SDK.

SkillSpector as AI asset publishing pipeline.

Unified dynamic plugin configuration, lifecycle management, runtime hot-reload, deterministic discovery, and console configuration workflows.

Plugin-hosted visibility Grant/Revoke APIs and console management for Skill and AgentSpec resources.

Agentic Resource Discovery (ARD) supporting search, exploration, artifact retrieval, visibility filtering, persistent indexing, and hybrid keyword/vector search.

Linux RISC-V64 architecture compatibility for RocksDB JNI loading and startup.

Shared MCP lifecycle management with draft, review, publish, online/offline operations, visibility control, Java SDK, and historical data alignment while preserving existing config and naming service runtime data.

Figure: Nacos MCP Management Architecture showing MCP registration, discovery, and management relationships. Source: Nacos official documentation.

02 Enhancements & Refactoring (Enhancement/Refactor)

Replaced mandatory Prometheus Client dependency with pluggable client metrics SPI, defaulting to no-op implementation.

Customizable gRPC port offset via separate client configuration property.

Config Center SDK adds Request/Result object-based invocation methods, encrypted config CAS publish, and conditional query reusing local cache.

Prints client-resolved log configuration and supplements namespace ID in subscription logs.

Optimizes Agent console workflow, exposes SDK discovery capabilities and A2A conversion utilities, adds traceability for discovery request sources.

Defaults deprecated Pipeline and MCP import APIs to disabled with global temporary compatibility switch.

Reduces lock contention in legacy MCP cache read path, improves index consistency.

Supports deregistering persistent service instances in Console v3.

Optimizes Skill upload pre-check logic, conflict handling, and server-side ZIP validation.

Removes legacy config migration compatibility code, retains only current standard config storage model.

Returns cached Skill metadata frontmatter in list queries and metadata detail responses.

Server-side unified management of latest tag for AI resource retention.

Defaults client API authentication to enabled, with automated verification for standard integration scenarios.

Cleans reviewed unused Java code while preserving existing compatibility contracts.

Optimizes Console UI Next English translation texts.

Skill upload permission errors now explicitly indicate current Owner.

Returns deterministic per-entry processing results for Skill batch upload candidate sets.

Restricts distributed embedded database query results to supported scalar types and registered Row Mappers.

Decouples visibility plugin SPI from server runtime module.

Aligns authentication method resolution logic with Spring MVC routing, expands Controller-layer auth regression test coverage.

Adds native JRaft gRPC request server identity authentication and smooth forced transition mechanism for rolling upgrades.

Optimizes config detail, edit, and history pages with larger content areas and full-screen reading support.

First Skill version upload defaults to auto-publish.

Introduces ops-controlled outbound access policies for MCP tool imports.

Adds on-demand initialization support for multiple Spring AOT contexts, improves GraalVM runtime metadata.

Documents that rolling back the first added config history record deletes the config.

Removes parsing logic for legacy untagged Raft requests, throws explicit exception on malformed log entries.

Supports disabling local config snapshots via startup parameter configSnapshotEnabled.

Refactors Copilot streaming responses to strongly-typed AgentScope events while preserving existing SSE response contract.

Correlates Java SDK HTTP requests with server request context end-to-end via Nacos-Request-Id.

Adds standalone parallel search MCP example covering service registration, endpoint discovery, web search, and page scraping.

Adds optional Jev relevance filtering for ARD search with stable result sorting and fallback to basic retrieval.

Adds Russian localization pack and language switcher for Console UI Next.

Allows visibility plugins to declare additional AI resource scopes and extend Agent validation logic via optional SPI while preserving default PUBLIC/PRIVATE behavior.

Figure: MCP Auto Registration and Discovery Flow using Python Wrapper and Nacos MCP Router as example. Source: Nacos official documentation.

03 Bug Fixes (BugFix)

Supports healthCheckEnabled as health check switch parameter while retaining legacy check alias.

Preserves filter conditions and pagination state when returning from detail page to config/service lists.

Prevents accidental deletion of still-existing instance metadata after instance restart.

Adds retry mechanism for config dump write lock acquisition to prevent stale MD5 cache data.

Fixes native-image metadata configuration required for gRPC client connection establishment.

Ensures AI retrieval service high availability during index backfill, supports returning partial results.

Guarantees Agent SDK Watch connection survival during transient network jitter, delivers initial state and subsequent changes via unified Listener chain.

Fixes config concurrent publish primary key conflict handling via data source dialect SPI, including PostgreSQL unique_violation exception compatibility.

Fixes extra trailing delimiter when joining collections containing null elements.

Prevents valid plugin configs from being discarded due to individual malformed plugin property names.

Fixes errors when uploading Skill ZIP packages with invalid or unavailable version candidate sets.

Prevents IndexOutOfBoundsException from batch processing index overflow.

Fixes total page count calculation for empty result sets and when total count is exactly divisible by page size.

Prevents NamingUtils.getServiceName failure when service name ends with delimiter.

Corrects Skill upload API @Since version annotation documentation.

Prevents service discovery connection cleanup from blocking on unrelated distributed lock Raft write operations.

Fixes standalone console auth plugin initialization and correctly propagates caller identity to downstream server requests.

Enforces Prompt visibility permission validation in list, detail, version query, download, and client read APIs.

Ensures health checks start only after persistent service metadata loading completes.

Fixes Chinese garbled characters in Skill Scanner pipeline reports on Windows.

Restores full MCP tool advanced template configuration support in Console UI Next.

Explicitly rejects access when invalid Bearer Token is provided, no longer silently falls back to anonymous access.

Generates deterministic ASCII-safe underlying physical config keys for AI resources.

Restores case-sensitive collation rules for newly initialized MySQL config database tables.

Fixes service startup failure caused by restoring plugin state snapshots before unified plugin discovery completes.

Fixes loss of MCP tool passthrough identity auth info when editing and publishing runtime templates.

Fixes visibility query condition conversion error when explicit authorized resources exist.

Prioritizes low-priority explicit Skill upload specified version before auto-generating version numbers.

Allows AI resource versions to be resubmitted after review completion or review result expiration.

Fixes NPE and cross-thread memory visibility issues in config dump service and client long connections for gray config cache.

Fixes API auth metadata parsing priority, custom resource parser priority, AgentSpec auth failure, and Prometheus monitoring secure path matching errors.

Refactors AI resource deletion to clean-then-delete mode with retry support across full storage versions.

Ensures AI resource read/update/delete strictly bind to persisted storage provider.

Fixes standalone console startup exception when config clone source permission validator unavailable.

Preserves case sensitivity of AI resource identifiers in MySQL search and task tables.

Fully preserves MCP tool nullable output schemas during edit, display, and OpenAPI import.

Fixes login response information discrepancy to prevent username enumeration attacks.

Preserves config storage ID string serialization format in Jackson 3 environment to prevent long integer precision loss.

Fixes Derby database SQL syntax for querying next config history record, maintains gray version filtering.

Migrates legacy skills.sh importer state keys to avoid overwriting standard official configs.

Cleans invalid Skill and AgentSpec draft files after storage failure while retaining metadata for retry.

Explicitly declares required SQL LIKE escape clauses for affected dialects like Derby and Oracle.

Strictly validates and rejects unsafe instance addresses, HTTP request targets, headers, and MySQL connection parameters in active health checks.

Fixes legacy Controller method parser inconsistency with encoded context paths.

Safely escapes special characters in all LIKE predicates when retrieving built-in roles with username filter.

Fully forwards namespace parameter when querying config listeners by IP across cluster nodes.

Aligns Bootstrap startup config with distribution package default config items.

Intercepts and rejects illegal IPv6 mixed-format addresses with excessive explicit address blocks.

Allows Java client to run fully in Jackson 3 environment (including auth chain) after excluding Jackson 2 core and databind dependencies.

Intercepts unsafe AgentSpec and Skill ZIP package directory layouts, enforces compression entry count and decompression size limits.

Validates and rejects unsafe filesystem path inputs before config write, archive, and local rule storage operations.

Increases embedded Derby database connection timeout to prevent startup initialization timeout on low-performance disks.

Fixes plugin availability RPC serialization error, ensures remote cluster node plugin states correctly perceived and reported.

Corrects default gRPC protocol negotiator type.

Restores default PUBLIC visibility for newly created Agent and MCP resources, strictly preserves existing resource visibility scopes.

Auto-matches default JDBC driver by data source dialect, improves non-MySQL database config examples.

Supplements schema metadata in current config, history, and previous version config details.

Prevents expired Distro snapshots from overwriting client redo registration process after cluster restart, avoiding service instance loss.

Supports resolving HEAD requests via corresponding GET mapping rules in legacy Controller method cache.

Unregisters server list event subscriptions on client shutdown to prevent shutdown callback accessing closed ServerListProvider.

Correctly displays subscriber addresses, client versions, and application names in Console UI Next.

Ignores registration responses from stale network connections, ensures temporary instances correctly re-register after reconnect storms.

Fixes occasional HTTP 403 from identity-only verification interface when console deployed independently.

Fixes Console UI Next page load failure on Chromium 90 via fallback transpilation of unsupported JavaScript syntax.

Prevents uncaught runtime exceptions from permanently interrupting service registration redo tasks, ensuring registration and subscription recovery reliability after network jitter.

Correctly parses multi-line Skill descriptions in YAML, prevents generation of spurious frontmatter fields.

Preserves empty and whitespace-only files in Skill resource packages during version read and package download.

Ensures Skill description consistency with current display version during draft editing and lifecycle transitions, retains correct description after last online version offline.

Keeps "Publish" and "Cancel" buttons persistently visible in Console UI Next config create/edit pages, eliminates extra nested scrollbars in config and history detail pages.

04 Dependency Upgrades (Dependencies)

Spring Boot upgraded from 3.5.14 to 4.0.6.

SOFA JRaft upgraded to 1.4.1, retains callback cache mechanism and JRaft auth capabilities.

Maven Compiler Plugin upgraded from 3.5.1 to 3.15.0 for JDK 25 compilation support.

Classic and Next console third-party frontend dependencies upgraded, static assets refreshed, embedded DOMPurify HTML sanitizer upgraded to 3.4.17.

Log4j API upgraded from 2.25.4 to 2.25.5.

gRPC upgraded to 1.81.0 to fix security vulnerability CVE-2026-33871.

Apache Derby upgraded from 10.14.2.0 to 10.16.1.1, aligns split build artifacts, maintains Java 17 as runtime baseline.

Copilot AgentScope Java dependency upgraded from 1.0.7 to 2.0.3.

05 Breaking Change Notice

Nacos 3.3.0 adjusts default authentication behavior, disables some deprecated APIs, and introduces data migration requirements. Applications using new Agent SDK in BETA/RC must also adapt to finalized subscription interface contracts.

Affected Users

Applications relying on credential-free Client API calls or deprecated Pipeline and MCP import interfaces.

Production clusters with legacy config center data, historical AI storage physical keys, untagged historical Raft logs, or requiring A2A/MCP resource migration.

Applications depending on client-built-in Prometheus metrics export or implicit AI resource visibility defaults.

Users of RAD agent subscription interfaces in early BETA/RC versions, or those needing remote access to optional built-in DNS service.

Recommended Upgrade Actions

Configure Client API Auth Credentials : nacos.core.auth.enabled default changes to true (auth enabled by default). Explicit false config remains honored. Can temporarily set false during upgrade, distribute credentials to all clients, verify, then switch cluster to enabled. Admin and console auth defaults unchanged.

Migrate Deprecated AI API Calls : Legacy Pipeline and console MCP import endpoints return HTTP 410 ( API_DEPRECATED). Switch to standard Pipeline /list and /detail, and unified /v3/console/ai/import/validate and /execute. Temporary compatibility via nacos.core.api.compatibility.enabled=true; nacos.ai.resource.import.legacy-mcp-api-enabled permanently deprecated.

Complete Legacy Config Center Data Migration : Clusters below 3.0 must transition via earlier Nacos 3.x. Migrate default namespace data from empty tenant to public, historical beta/tag data to config_info_gray gray table. For deployments using nacos_config as AI storage provider, must explicitly migrate historical configs with non-ASCII or oversized coordinates to deterministic ASCII-safe mapping format.

Check Persistent Raft Logs : Nacos 3.3 no longer replays untagged historical log entries (including those originally written by Nacos 2.0.x and retained through multiple intermediate upgrades). Before upgrade, must use compatible version to recover and transform these logs/snapshots; simply swapping server version does not auto-convert persisted historical logs.

Plan Historical A2A and MCP Data Migration : Default nacos.ai.a2a.compatibility.mode=CANONICAL does not auto-scan historical A2A data. Refer to official A2A upgrade runbook, use AUTO migration mode for 3.3 pre-check. After permanent switch to Canonical mode, nodes supporting only old protocol must not rejoin cluster. Preserve MCP data alignment status and existing config/service discovery runtime data during one-way lifecycle switch.

Maintain Consistent Cluster Node Identity Config : After all members declare support, native JRaft auth is forcibly enabled and persists across cluster restarts. Rolling downgrade to unsupported JRaft credential versions cannot guarantee cluster availability.

Update BETA/RC Agent SDK Usage : RAD's new subscribeAgent return type changed to void. Clients must receive initial state and subsequent changes via registered Listener. Prepare Listener state before subscribe call, recompile dependent applications. Existing legacy A2A interface signatures and underlying HTTP/gRPC transport contracts unchanged.

Explicitly Configure Client Metrics : nacos-client no longer bundles mandatory Prometheus Client. If business systems need client metrics, explicitly provide and install NacosClientMetricsProvider implementation; without implementation, metrics remain no-op even if enableClientMetrics enabled.

Review MCP Import and Visibility Config : For MCP import targets in private networks or localhost, server requires explicit whitelist nacos.console.ai.mcp.import.allowed-private-addresses, and system no longer auto-follows HTTP redirects. Built-in visibility plugin now sets newly created Agent and MCP resources to PUBLIC by default; choose PRIVATE explicitly at creation for isolation. Existing historical resource scopes and Prompt/Skill defaults unchanged.

Review DNS Listen Address Config : DNS discovery remains optional, default disabled. When enabled, nacos.naming.dns.bind-address defaults to 127.0.0.1; configure actual external listening IP for remote clients. External recursive forwarding requires separate explicit forwarding rules.

Refresh Affected Skill Metadata : Historical Skill packages missing frontmatter continue using saved metadata; this version does not auto-re-extract. Recommend updating content or re-uploading relevant Skills to regenerate frontmatter and correct multi-line description formats.

Perform Production Backup and Upgrade Drills : Fully backup database and server persistent runtime directories before upgrade. Validate auth, data migration, service discovery, and client call behavior in staging/test. Derby upgrade to 10.16.1.1 requires verification of persistent data reads, subsequent writes, and node restart recovery.

For fresh or minimal deployments without affected historical data, corresponding migrations are not required; however, auth default enablement, API deprecations, and SDK contract changes still require attention and self-check.

06 Java Runtime Version Requirements

Nacos-Server / Nacos-Console (Server / Console): Java 17

Nacos-Client (Java Client): Java 8

Nacos-Maintainer-Client (Ops Admin Client): Java 8

Source: JAVA Architecture Diary