Client API

For how to obtain and configure access credentials when using the default auth plugin, see Configure Access Credentials.

0. Client API Notes

0.1. Scope

Client APIs are intended for application runtime access and custom clients. Callers usually already know the namespaceId, groupName, dataId, serviceName, or instance information they need to access.

Business applications should prefer SDKs. For range-based management capabilities, use Admin API or Maintainer SDK.

0.2. Unified Path Format

Nacos client APIs use a unified path format: [/$nacos.server.contextPath]/v3/client/[module]/[subPath]....

• $nacos.server.contextPath: Root path of the client APIs. The default value is /nacos, and it can be changed with the nacos.server.contextPath configuration item.
• module: Client API module name, such as server, cs, ns, or core.
• subPath: Client API subpath, such as state, namespace, or config. It may contain multiple path levels.

The client APIs listed below use the default $nacos.server.contextPath. If the deployment changes $nacos.server.contextPath, update the request URL accordingly when calling the API.

The examples below also use the default Nacos Web Server port. If the deployment changes $nacos.server.main.port, update the request URL accordingly when calling the API.

0.3. Swagger Documentation

Nacos 3.X client OpenAPI also provides Swagger-style documentation. You can view it at Nacos Swagger HTTP Client API.

0.4. Authentication And Example Setup

Nacos 3.3 enables Client authentication by default. Configuration reads, service registration/discovery, and other protected requests fail without valid credentials and resource permissions.

With the default auth plugin, follow Access Credentials to log in and save the returned accessToken in the NACOS_ACCESS_TOKEN environment variable. Run the examples below in the same terminal. They use Bash (Git Bash or WSL on Windows) and send the token in the accessToken header. This header requirement applies to every protected API and is not repeated in each parameter table.

If authentication fails, check account credentials, token expiration, and resource permissions. Log in again and update the variable after expiration. Logging in to the console does not configure credentials for curl in a separate terminal.

1. Configuration Management

1.1. Get Configuration

Description

Get the specified configuration.

Since

3.0.0

Request Method

GET

Request URL

/nacos/v3/client/cs/config

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Other fields are reserved and currently unused. You can ignore them.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X GET '127.0.0.1:8848/nacos/v3/client/cs/config?dataId=test&groupName=test'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "resultCode": 200,
    "errorCode": 0,
    "message": null,
    "requestId": null,
    "content": "test",
    "encryptedDataKey": null,
    "contentType": "text",
    "md5": "098f6bcd4621d373cade4e832627b4f6",
    "lastModified": 1743151634823,
    "tag": null,
    "beta": false,
    "success": true
  }
}

2. Service Discovery

2.1. Register/Renew Instance

Description

Register or renew an instance.

Since

3.0.0

Request Method

POST

Request URL

/nacos/v3/client/ns/instance

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Examples

• Request example

# Register instance
curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X POST "127.0.0.1:8848/nacos/v3/client/ns/instance" -d "serviceName=test1&ip=127.0.0.1&port=3306&ephemeral=true"

# Renew instance
curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X POST "127.0.0.1:8848/nacos/v3/client/ns/instance" -d "serviceName=test1&ip=127.0.0.1&port=3306&heartBeat=true&ephemeral=true"

• Response example

{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.2. Deregister Instance

Description

Deregister the specified instance.

Since

3.0.0

Request Method

DELETE

Request URL

/nacos/v3/client/ns/instance

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X DELETE "127.0.0.1:8848/nacos/v3/client/ns/instance?serviceName=test1&ip=127.0.0.1&port=3306&ephemeral=true"

• Response example

{
  "code": 0,
  "message": "success",
  "data": "ok"
}

2.3. List Instances of a Service

Description

Query the detailed instance list under the specified service.

Since

3.0.0

Request Method

GET

Request URL

/nacos/v3/client/ns/instance/list

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X GET '127.0.0.1:8848/nacos/v3/client/ns/instance/list?serviceName=test1'

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "ip": "127.0.0.1",
      "port": 3306,
      "weight": 1.0,
      "healthy": true,
      "enabled": true,
      "ephemeral": true,
      "clusterName": "DEFAULT",
      "serviceName": "DEFAULT_GROUP@@test1",
      "metadata": {},
      "ipDeleteTimeout": 30000,
      "instanceIdGenerator": "simple",
      "instanceHeartBeatInterval": 5000,
      "instanceHeartBeatTimeOut": 15000
    }
  ]
}

3. AI

This chapter covers AI APIs for application runtime access. See the Unified Lifecycle for version publishing and visibility, and the RAD Integration Guide for Agent integration. Search returns currently visible, enabled resources; newly published resources may be temporarily absent while the index catches up.

3.1. Query Prompt

Description

Query Prompt by version, label, or latest (priority: version > label > latest); supports md5 for 304 conditional response.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/prompt

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X GET '127.0.0.1:8848/nacos/v3/client/ai/prompt?promptKey=myPrompt'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "promptKey": "myPrompt",
    "version": "1.0",
    "template": "You are a helpful assistant.",
    "md5": "..."
  }
}

3.2. Get AgentSpec

Description

This interface allows getting an AgentSpec detail by namespace, name, version, or label.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agentspecs

Request Parameters

Response Data

Return body follows Nacos open API common response format; this table describes fields in data.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X GET '127.0.0.1:8848/nacos/v3/client/ai/agentspecs?name=my-agent'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {}
}

3.3. Search AgentSpecs

Description

This interface allows paginated searching of AgentSpecs by namespace and keyword.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agentspecs/search

Request Parameters

Response Data

Return body follows Nacos open API common response format; this table describes fields in data.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X GET '127.0.0.1:8848/nacos/v3/client/ai/agentspecs/search?keyword=agent&pageNo=1&pageSize=10'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {}
}

3.4. Download Skill

Description

This interface allows downloading a Skill ZIP file by namespace, name, version, or label.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/skills

Request Parameters

Examples

• Request example

curl -f -H "accessToken: ${NACOS_ACCESS_TOKEN}" '127.0.0.1:8848/nacos/v3/client/ai/skills?name=my-skill' -o my-skill.zip

• Response description

A successful response is a Skill ZIP file, saved as my-skill.zip by this command. It is not wrapped in a JSON Result.

Agent Management API note: The Agent APIs in sections 3.5–3.11 are the recommended integration path going forward and are planned to gradually replace the existing A2A management APIs. New users and SDKs should prioritize compatibility with these Agent Management APIs instead of adding new dependencies on the legacy A2A APIs. Existing A2A integrations can migrate in line with future release and migration guidance. This describes the evolution of the management APIs and does not mean that the A2A protocol itself is deprecated.

3.5. Discover Agent

Description

Discovers one exact visible Agent version and its currently matching endpoint sets. Supplying X-Nacos-Client-Id renews only an already-existing HTTP Client and cannot replace Publisher heartbeat.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agents

Request Headers

Request Parameters

When both version and label are omitted, the response contains the latest definition metadata and Runtime Endpoints compatible with any currently online version. Explicit label=latest keeps only Runtime Endpoints matching the latest version.

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X GET '127.0.0.1:8848/nacos/v3/client/ai/agents?namespaceId=public&agentName=my-agent&version=1.0.0&protocol=a2a' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "namespaceId": "public",
    "agentName": "my-agent",
    "version": "1.0.0",
    "contentDigest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "callInterfaces": [
      {
        "protocol": "a2a",
        "protocolVersion": "1.0",
        "descriptorMediaType": "application/json",
        "nativeDescriptor": {
          "name": "my-agent",
          "version": "1.0.0",
          "description": "Example Agent",
          "protocolVersion": "1.0",
          "supportedInterfaces": [
            {
              "url": "https://example.com/my-agent/jsonrpc",
              "protocolBinding": "JSONRPC",
              "protocolVersion": "1.0",
              "transport": "JSONRPC"
            }
          ],
          "capabilities": {
            "streaming": true,
            "extendedAgentCard": true
          }
        },
        "endpointSets": [
          {
            "source": "RUNTIME",
            "sourceRevision": "1",
            "endpoints": [
              {
                "uri": "http://127.0.0.1:8081/a2a",
                "transport": "HTTP+JSON",
                "priority": 0,
                "weight": 1.0,
                "metadata": {},
                "healthy": true,
                "bindings": [
                  {
                    "runtimeVersion": "1.0.0",
                    "versionRange": "[1.0.0]"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

3.6. Publish Agent Definition

Description

Publishes one exact Agent version from application code, optionally submitting it for review.

Since

3.3.0

Request Method

POST

Request parameters are encoded as an application/x-www-form-urlencoded form.

Request URL

/nacos/v3/client/ai/agents

Request Parameters

This API creates or fully replaces an editable Agent draft. Creating the first version submits it automatically; subsequent versions and existing drafts use autoSubmit. Submission may require review, so a successful response does not imply that the version is online. Existing non-draft versions are neither overwritten nor brought online again. See Agent Management.

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X POST '127.0.0.1:8848/nacos/v3/client/ai/agents' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'namespaceId=public' \
  -d 'agentName=my-agent' \
  -d 'version=1.0.0' \
  --data-urlencode 'callInterfaces=[{"protocol":"a2a","protocolVersion":"1.0","descriptorMediaType":"application/json","nativeDescriptor":{"name":"my-agent","version":"1.0.0","description":"Example Agent","protocolVersion":"1.0","supportedInterfaces":[{"url":"https://example.com/my-agent/jsonrpc","protocolBinding":"JSONRPC","protocolVersion":"1.0","transport":"JSONRPC"}],"capabilities":{"streaming":true,"extendedAgentCard":true}},"endpointSourceOrder":["DECLARED","RUNTIME"],"endpointSets":[{"source":"DECLARED","endpoints":[{"uri":"https://example.com/my-agent/jsonrpc","transport":"JSONRPC"}]}]}]' \
  -d 'author=demo' \
  -d 'changeDescription=initial version' \
  -d 'autoSubmit=true'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "namespaceId": "public",
    "agentName": "my-agent",
    "version": "1.0.0",
    "status": "online",
    "callInterfaces": [
      {
        "protocol": "a2a",
        "protocolVersion": "1.0",
        "descriptorMediaType": "application/json",
        "nativeDescriptor": {
          "name": "my-agent",
          "version": "1.0.0",
          "description": "Example Agent",
          "protocolVersion": "1.0",
          "supportedInterfaces": [
            {
              "url": "https://example.com/my-agent/jsonrpc",
              "protocolBinding": "JSONRPC",
              "protocolVersion": "1.0",
              "transport": "JSONRPC"
            }
          ],
          "capabilities": {
            "streaming": true,
            "extendedAgentCard": true
          }
        },
        "endpointSourceOrder": ["DECLARED", "RUNTIME"],
        "endpointSets": [
          {
            "source": "DECLARED",
            "endpoints": [
              {
                "uri": "https://example.com/my-agent/jsonrpc",
                "transport": "JSONRPC"
              }
            ]
          }
        ]
      }
    ],
    "author": "demo",
    "changeDescription": "initial version",
    "contentDigest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "createTime": 1785897600000,
    "updateTime": 1785897600000
  }
}

3.7. Register Agent Endpoints

Description

Replaces one HTTP publisher’s complete runtime endpoint batch for an Agent protocol. Reuse one stable X-Nacos-Client-Id for every batch owned by the same logical client in its bound namespace. The returned ClientLivenessInfo is the effective server policy: schedule one heartbeat task for this client id at heartbeatIntervalMillis, not one task per endpoint or batch.

Since

3.3.0

Request Method

POST

Request parameters are encoded as an application/x-www-form-urlencoded form; endpoints is a JSON array string.

Request URL

/nacos/v3/client/ai/agents/endpoints

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X POST '127.0.0.1:8848/nacos/v3/client/ai/agents/endpoints' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Request-Module: AI' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'namespaceId=public' \
  -d 'agentName=my-agent' \
  -d 'runtimeVersion=1.0.0' \
  --data-urlencode 'versionRange=[1.0.0]' \
  -d 'protocol=a2a' \
  --data-urlencode 'endpoints=[{"uri":"http://127.0.0.1:8081/a2a","transport":"HTTP+JSON","priority":0,"weight":1.0,"metadata":{}}]'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "heartbeatIntervalMillis": 5000,
    "unhealthyTimeoutMillis": 15000,
    "expireTimeoutMillis": 30000
  }
}

3.8. Deregister Agent Endpoints

Description

Removes one HTTP publisher’s complete runtime endpoint publication for an Agent protocol owned by the supplied X-Nacos-Client-Id. Keep one client-level heartbeat while any publication owned by this client remains, and stop it after the last publication is removed.

This endpoint binds the ordinary namespaceId, agentName, and protocol request parameters through a dedicated form. It does not accept Endpoint natural keys or a JSON request body.

Since

3.3.0

Request Method

DELETE

Request URL

/nacos/v3/client/ai/agents/endpoints

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X DELETE '127.0.0.1:8848/nacos/v3/client/ai/agents/endpoints?namespaceId=public&agentName=my-agent&protocol=a2a' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Request-Module: AI'

• Response example

{
  "code": 0,
  "message": "success",
  "data": null
}

3.9. Heartbeat Agent Endpoints

Description

Refreshes the HTTP Client and every Agent endpoint publication owned by its X-Nacos-Client-Id. Send one heartbeat task per client id regardless of endpoint, Agent, protocol, or batch count; never schedule heartbeats per endpoint. Use heartbeatIntervalMillis returned by registration or the latest heartbeat as the delay before the next heartbeat, and reschedule when a later response changes it instead of hard-coding the current defaults. unhealthyTimeoutMillis and expireTimeoutMillis are effective server thresholds and cannot be overridden by the request. Search and Discover do not renew Publisher liveness. On HTTP_CLIENT_NOT_FOUND (50404), re-register every complete desired batch before continuing heartbeats.

Since

3.3.0

Request Method

PUT

Request URL

/nacos/v3/client/ai/agents/endpoints/heartbeat

Request Headers

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X PUT '127.0.0.1:8848/nacos/v3/client/ai/agents/endpoints/heartbeat' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Request-Module: AI'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "heartbeatIntervalMillis": 5000,
    "unhealthyTimeoutMillis": 15000,
    "expireTimeoutMillis": 30000
  }
}

3.10. Search Agent Catalog

Description

Searches visible Agent catalog entries by name, tags, protocols, and pagination. Supplying X-Nacos-Client-Id renews only an already-existing HTTP Client and never its endpoint Publisher liveness.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agents/search

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -H "accessToken: ${NACOS_ACCESS_TOKEN}" -X GET '127.0.0.1:8848/nacos/v3/client/ai/agents/search?namespaceId=public&agentNameContains=agent&tagsAll=assistant&protocolsAny=a2a&pageNo=1&pageSize=10' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
      {
        "agentName": "my-agent",
        "displayName": "My Agent",
        "description": "Example Agent",
        "iconUrl": "https://example.com/icon.png",
        "provider": {
          "name": "example-provider",
          "url": "https://example.com"
        },
        "tags": ["assistant"],
        "versionInfo": {
          "labels": {"latest": "1.0.0"},
          "onlineVersions": [
            {
              "version": "1.0.0",
              "labels": [],
              "protocols": ["a2a"]
            }
          ]
        }
      }
    ]
  }
}

3.11. Watch Agent Discovery Changes

Description

Perform one batch long poll for the complete current watch set. The response only identifies changed watches; call Discover again to retrieve their complete results, then start the next poll. Prefer the RAD SDK for continuous subscriptions.

Since

3.3.0

Request Method

POST, with an application/x-www-form-urlencoded body.

Request URL

/nacos/v3/client/ai/agents/watch

Request Headers

Request Parameters

Each watch item contains these fields:

Java clients can calculate the fingerprint with AgentDiscoveryCanonicalizer.fingerprint(snapshot). It is neither the definition’s contentDigest nor a SHA-256 hash of the raw HTTP JSON. Replace the previous poll when the watch set changes, and ignore responses for stale generations or cancelled items.

Response Data

Examples

Save the current snapshot fingerprint for this discovery request in NACOS_AGENT_FINGERPRINT before running:

curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/client/ai/agents/watch' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -H 'X-Nacos-Client-Id: agent-consumer-1' \
  -H 'Request-Module: AI' \
  -d 'generation=1' -d 'timeoutMillis=30000' \
  --data-urlencode "watches=[{\"clientWatchId\":\"watch-1\",\"discoveryRequest\":{\"namespaceId\":\"public\",\"reference\":{\"agentName\":\"my-agent\",\"version\":\"1.0.0\"}},\"materializedFingerprint\":\"${NACOS_AGENT_FINGERPRINT}\"}]"

Normal timeout example:

{"code":0,"message":"success","data":{"generation":1,"changed":false,"changedClientWatchIds":[]}}

3.12. Query an MCP Server Version

Description

Retrieve an online MCP server version and its endpoints. Omitting the version selects latest. The optional client identifier renews only an existing HTTP Client and cannot replace endpoint heartbeats.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/mcp

Request Headers

Request Parameters

Response Data

Examples

curl -sS -G 'http://127.0.0.1:8848/nacos/v3/client/ai/mcp' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' \
  --data-urlencode 'mcpName=my-mcp' \
  --data-urlencode 'version=1.0.0'

3.13. Publish an MCP Version

Description

Publish an MCP version from an application. By default, the version goes directly online. With createDraft=true, only a draft is created; the resource must already use lifecycle management. Then follow the lifecycle workflow to submit and publish it.

Since

3.3.0

Request Method

POST, with an application/x-www-form-urlencoded body.

Request URL

/nacos/v3/client/ai/mcp

Request Parameters

Response Data

Examples

This publishes a stdio server definition; it does not start the process on Nacos Server.

curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/client/ai/mcp' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -d 'namespaceId=public' \
  --data-urlencode 'serverSpecification={"name":"my-mcp","protocol":"stdio","frontProtocol":"stdio","versionDetail":{"version":"1.0.0"},"localServerConfig":{"command":"python","args":["server.py"]}}' \
  -d 'createDraft=false'

3.14. Register an MCP Endpoint

Description

Register a runtime endpoint for a published remote MCP server configured with a service reference (REF). Prepare the remote definition and version using MCP Management; this example uses version 1.0.0 of my-remote-mcp. After registration, send heartbeats at the returned interval.

Within one identity and namespace, a logical client’s Agent/MCP publications share a stable Client ID and one heartbeat task.

Since

3.3.0

Request Method

POST, with an application/x-www-form-urlencoded body.

Request URL

/nacos/v3/client/ai/mcp/endpoints

Request Headers

Request Parameters

Response Data

Examples

curl -sS -X POST 'http://127.0.0.1:8848/nacos/v3/client/ai/mcp/endpoints' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -H 'X-Nacos-Client-Id: mcp-publisher-1' \
  -H 'Request-Module: AI' \
  -d 'namespaceId=public' -d 'mcpName=my-remote-mcp' \
  -d 'address=127.0.0.1' -d 'port=9999' -d 'version=1.0.0'

Example response (use the interval from the actual response for subsequent heartbeats):

{"code":0,"message":"success","data":{"heartbeatIntervalMillis":5000,"unhealthyTimeoutMillis":15000,"expireTimeoutMillis":30000}}

3.15. Deregister an MCP Endpoint

Description

Deregister an MCP runtime endpoint owned by this HTTP Client. Use the same Client ID, server, version, address, and port as registration. This does not delete the server definition.

Since

3.3.0

Request Method

DELETE, with an application/x-www-form-urlencoded body.

Request URL

/nacos/v3/client/ai/mcp/endpoints

Request Headers

Request Parameters

Response Data

Returns the common Result with data=null on success.

Examples

curl -sS -X DELETE 'http://127.0.0.1:8848/nacos/v3/client/ai/mcp/endpoints' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -H 'X-Nacos-Client-Id: mcp-publisher-1' \
  -H 'Request-Module: AI' \
  -d 'namespaceId=public' -d 'mcpName=my-remote-mcp' \
  -d 'address=127.0.0.1' -d 'port=9999' -d 'version=1.0.0'

{"code":0,"message":"success","data":null}

3.16. MCP Endpoint Heartbeat

Description

Renew the shared HTTP Client and all Agent/MCP publications it owns. Schedule one heartbeat task using the latest heartbeatIntervalMillis. Re-register the desired endpoints on HTTP_CLIENT_NOT_FOUND. Queries and Watch cannot replace publisher heartbeats.

Since

3.3.0

Request Method

PUT

Request URL

/nacos/v3/client/ai/mcp/endpoints/heartbeat

Request Headers

Request Parameters

None.

Response Data

Examples

curl -sS -X PUT 'http://127.0.0.1:8848/nacos/v3/client/ai/mcp/endpoints/heartbeat' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  -H 'X-Nacos-Client-Id: mcp-publisher-1' \
  -H 'Request-Module: AI'

3.17. Search MCP Resources

Description

Search currently visible, enabled MCP resources by text, tags, protocols, and capabilities. An empty query lists resources. All tagsAll values must match; protocolsAny and capabilitiesAny each require any matching value. Different conditions are combined with AND.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/mcp/search

Request Parameters

Response Data

Examples

curl -sS -G 'http://127.0.0.1:8848/nacos/v3/client/ai/mcp/search' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' --data-urlencode 'query=weather' \
  --data-urlencode 'capabilitiesAny=TOOL' \
  --data-urlencode 'pageNo=1' --data-urlencode 'pageSize=20'

3.18. Search Skill Resources

Description

Search currently visible, enabled Skills by text and tags. An empty query lists resources. Use the Skill download API to retrieve content.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/skills/search

Request Parameters

Response Data

Examples

curl -sS -G 'http://127.0.0.1:8848/nacos/v3/client/ai/skills/search' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' --data-urlencode 'query=travel' \
  --data-urlencode 'pageNo=1' --data-urlencode 'pageSize=20'

3.19. Search Prompt Resources

Description

Search currently visible, enabled Prompts by text and tags. An empty query lists resources. Use the Prompt query API to retrieve template content.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/prompt/search

Request Parameters

Response Data

Examples

curl -sS -G 'http://127.0.0.1:8848/nacos/v3/client/ai/prompt/search' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' --data-urlencode 'query=assistant' \
  --data-urlencode 'pageNo=1' --data-urlencode 'pageSize=20'

3.20. Search Across AI Resource Types

Description

Search currently visible, enabled AI resources using cursor pagination. A blank query lists resources; a non-blank query searches by relevance. Newly published content may be temporarily absent while the index catches up. Results are summaries; use the corresponding resource APIs to invoke or download content.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/resources/search

Request Parameters

Each array filter allows up to 32 non-empty values. Different conditions are combined with AND. Keep search conditions unchanged when paging; an absent nextCursor means the last page.

Response Data

Examples

curl -sS -G 'http://127.0.0.1:8848/nacos/v3/client/ai/resources/search' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}" \
  --data-urlencode 'namespaceId=public' --data-urlencode 'query=travel' \
  --data-urlencode 'resourceTypes=agent' --data-urlencode 'resourceTypes=skill' \
  --data-urlencode 'limit=20'

Example with no matching resources:

{"code":0,"message":"success","data":{"items":[]}}

3.21. Query AI HTTP Capabilities

Description

Query this node’s Client HTTP capabilities to select a client binding. This follows Client authentication settings and checks identity without requiring permissions for specific AI resources. The result grants no resource access and does not imply support across all nodes or completed migration.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/capabilities

Request Parameters

None.

Response Data

Examples

curl -sS 'http://127.0.0.1:8848/nacos/v3/client/ai/capabilities' \
  -H "accessToken: ${NACOS_ACCESS_TOKEN}"

{"code":0,"message":"success","data":{"schemaVersion":1,"capabilities":{"radV1":true,"mcp":true,"skill":true,"prompt":true,"agentSpec":true}}}