客户端API

使用默认鉴权插件时如何获取和配置访问凭据，请参见配置访问凭据。

0. 客户端API 相关说明

0.1. 适用边界

客户端 API 面向应用运行时和自定义客户端。调用者通常已经知道要访问的 namespaceId、groupName、dataId、serviceName 或实例信息。

业务应用优先使用 SDK。需要范围型管理能力时，请使用运维 API或运维 SDK。

0.2. 统一路径格式

Nacos的客户端API，使用统一的Path格式进行的规范。格式为[/$nacos.server.contextPath]/v3/client/[module]/[subPath]..., 其中

• $nacos.server.contextPath：客户端API的根路径，默认为/nacos，可以通过nacos.server.contextPath配置项进行修改。
• module：客户端API模块名称，例如server、cs、ns、core等。
• subPath：客户端API的子路径，例如state、namespace、config等， 可能有多层子路径。

下列列出的客户端API，采用默认$nacos.server.contextPath的情况进行展示，若已修改部署环境中的$nacos.server.contextPath 配置项，请自行修改调用API时的请求URL。

同时下列列出的客户端API样例中，均采用默认Nacos Web Server的端口进行展示，若已修改部署环境中的$nacos.server.main.port 配置项，请自行修改调用API时的请求URL。

0.3. Swagger 类型文档

Nacos 3.X 的客户端 Open API 也提供了Swagger风格的文档，您可以通过访问Nacos Swagger HTTP 客户端 API查看。

下文的 map<string, any> 表示键为字符串、值可为任意 JSON 类型（字符串、数字、布尔值、对象、数组或 null）的映射。map<string, string>、map<string, boolean> 和命名模型映射仍遵循各自的值类型约束。

0.4. 鉴权与示例准备

Nacos 3.3 默认开启 Client 鉴权。未携带有效身份或缺少资源权限时，配置读取、服务注册与发现等请求会被拒绝。

使用默认鉴权插件时，先按配置访问凭据登录，将响应中的 accessToken 保存到 NACOS_ACCESS_TOKEN 环境变量，再在同一终端运行下文示例。示例使用 Bash（Windows 可使用 Git Bash 或 WSL），通过 accessToken 请求头携带 token；请求头要求适用于所有受保护接口，不再逐一列入参数表。

鉴权失败时检查账号密码、token 是否过期以及资源权限；token 过期后重新登录并更新变量。登录控制台不会自动为终端中的 curl 配置身份。

0.5. 请求关联 ID

建议直接 HTTP 调用方通过 Nacos-Request-Id 为每次请求提供唯一标识，便于排障关联。该请求头可选，详见 HTTP 请求关联 ID；具体接口要求的 X-Nacos-Client-Id 仍需单独配置。

1. 配置管理

1.1. 获取配置

接口描述

获取指定配置

起始版本

3.0.0

请求方式

GET

请求URL

/nacos/v3/client/cs/config

请求头

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

其他字段为预留字段，暂时无用，忽略即可。

示例

• 请求示例

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

• 返回示例

{
  "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. 服务发现

2.1. 注册实例/续约实例

接口描述

注册或续约一个实例

起始版本

3.0.0

请求方式

POST

请求URL

/nacos/v3/client/ns/instance

请求头

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

示例

• 请求示例

# 注册实例
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"

# 续约实例
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"

• 返回示例

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

2.2. 注销实例

接口描述

注销指定实例

起始版本

3.0.0

请求方式

DELETE

请求URL

/nacos/v3/client/ns/instance

请求头

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

示例

• 请求示例

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"

• 返回示例

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

2.3. 查询指定服务的实例列表

接口描述

查询指定服务下的实例详情信息列表

起始版本

3.0.0

请求方式

GET

请求URL

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

请求头

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

示例

• 请求示例

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

• 返回示例

{
  "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 相关

本章覆盖应用运行时使用的 AI 接口。AI 资源的版本发布与可见性参见统一生命周期，Agent 接入流程参见 RAD 接入指南。搜索返回当前可见且启用的资源；索引同步期间，新发布的资源可能暂未出现在结果中。

3.1. 查询 Prompt

接口描述

通过该接口，可按 version、label 或 latest 查询 Prompt，优先级 version > label > latest；支持 md5 条件返回 304。

起始版本

3.2.0

请求方式

GET

请求URL

/nacos/v3/client/ai/prompt

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

示例

• 请求示例

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

• 返回示例

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

3.2. 获取 AgentSpec

接口描述

通过该接口，可按命名空间、名称、版本号或 label 获取指定 AgentSpec 详情；支持通过 md5 进行缓存条件查询。

起始版本

3.2.0

请求方式

GET

请求URL

/nacos/v3/client/ai/agentspecs

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

AgentSpecResource.metadata 为 map<string, any>，允许任意 JSON 值。200 响应通过 ETag、X-Nacos-AgentSpec-Md5 和 X-Nacos-AgentSpec-Resolved-Version 返回非空的内容 MD5 和解析后版本；304 无响应体，返回 MD5 相关的前两个响应头，客户端继续使用缓存。

示例

• 请求示例

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

• 返回示例

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

3.3. 搜索 AgentSpec

接口描述

通过该接口，可按命名空间和关键词分页搜索 AgentSpec。

起始版本

3.2.0

请求方式

GET

请求URL

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

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

示例

• 请求示例

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'

• 返回示例

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

3.4. 下载 Skill

接口描述

通过该接口，可按命名空间、名称、版本号或 label 下载 Skill ZIP 文件；支持通过 md5 进行缓存条件查询。

起始版本

3.2.0

请求方式

GET

请求URL

/nacos/v3/client/ai/skills

请求参数

示例

• 请求示例

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

• 返回说明

200 返回 Skill ZIP 文件（Content-Type: application/zip），以上命令保存为 my-skill.zip，不使用 JSON Result 包装。304 无响应体，客户端继续使用已有 ZIP 缓存，不应以空响应覆盖缓存文件。两种响应均会在值非空时返回 ETag、X-Nacos-Skill-Md5 和 X-Nacos-Skill-Resolved-Version，分别用于内容校验及确认解析后的版本。

Agent 管理 API 说明： 以下 Agent API（3.5～3.11）是后续推荐的统一集成方向，未来将逐步替代现有 A2A 管理 API。新接入的用户和 SDK 应优先对接并兼容这些 Agent 管理 API，避免为新集成继续依赖旧 A2A API；已有 A2A 集成可依据后续版本发布和迁移说明逐步切换。这里描述的是管理 API 的演进，不表示 A2A 协议本身已废弃。

3.5. 发现 Agent

接口描述

发现指定的可见 Agent 版本及当前匹配的端点集合。携带 X-Nacos-Client-Id 时只续约已存在的 HTTP Client，不能替代 Publisher 心跳。

起始版本

3.3.0

请求方式

GET

请求URL

/nacos/v3/client/ai/agents

请求头

收到 Watch changed-ID 通知后重新 Discover 时，可携带 X-Nacos-Agent-Discovery-Trigger: watch-notify；主动查询、初始化和轮询回退不设置该标记。

请求参数

version 和 label 均省略时，返回 latest 定义元数据，并保留兼容任一当前在线版本的 Runtime Endpoint；显式指定 label=latest 时，只保留与 latest 版本匹配的 Runtime Endpoint。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表阐述 data 及其字段。

示例

• 请求示例

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'

• 返回示例

{
  "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. 发布 Agent 定义

接口描述

从应用代码创建或完整替换可编辑的 Agent 草稿。首次创建首个版本时自动提交；后续新版本或已有草稿由 autoSubmit 决定是否提交。提交可能进入审核，成功返回不代表版本已上线。已有非草稿版本不会被覆盖或重新上线，详见 Agent 管理。

起始版本

3.3.0

请求方式

POST

请求参数编码为 application/x-www-form-urlencoded Form。

请求URL

/nacos/v3/client/ai/agents

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表阐述 data 及其字段。

示例

• 请求示例

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'

• 返回示例

{
  "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. 注册 Agent 端点

接口描述

替换某个 HTTP Publisher 针对 Agent 协议发布的完整运行时 Endpoint Batch。同一逻辑客户端在其绑定 namespace 下拥有的全部 Batch 必须复用一个稳定的 X-Nacos-Client-Id。返回的 ClientLivenessInfo 是服务端实际活性策略：应按 heartbeatIntervalMillis 为该 client id 调度一个心跳任务，而不是为每个 Endpoint 或 Batch 分别调度。

起始版本

3.3.0

请求方式

POST

请求参数编码为 application/x-www-form-urlencoded Form；其中 endpoints 是 JSON 数组字符串。

请求URL

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

请求头

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表阐述 data 及其字段。

示例

• 请求示例

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":{}}]'

• 返回示例

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

3.8. 注销 Agent 端点

接口描述

移除指定 X-Nacos-Client-Id 所拥有的、针对某个 Agent 协议的整份 HTTP Publisher Runtime Endpoint Publication。该 Client 仍有任意 Publication 时保留一个 Client 级心跳，最后一份 Publication 移除后停止心跳。

该接口使用专用 Form 绑定 namespaceId、agentName 和 protocol 普通请求参数，不接收 Endpoint 自然键或 JSON 请求体。

起始版本

3.3.0

请求方式

DELETE

请求URL

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

请求头

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表阐述 data 字段。

示例

• 请求示例

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'

• 返回示例

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

3.9. Agent 端点心跳

接口描述

刷新该 X-Nacos-Client-Id 对应的 HTTP Client 及其拥有的全部 Agent Endpoint Publication。无论 Endpoint、Agent、协议或 Batch 数量多少，每个 client id 只维护一个心跳任务，禁止按 Endpoint 分别调度。使用注册响应或最新心跳响应中的 heartbeatIntervalMillis 作为下一次心跳的等待间隔；后续响应发生变化时重新调度，不要硬编码当前默认值。unhealthyTimeoutMillis 和 expireTimeoutMillis 是服务端实际阈值，调用方不能通过请求覆盖。Search 和 Discover 不会续约 Publisher 活性。收到 HTTP_CLIENT_NOT_FOUND (50404) 后，应先重新注册每个完整期望 Batch，再继续心跳。

起始版本

3.3.0

请求方式

PUT

请求URL

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

请求头

返回数据

返回体遵循Nacos open API 统一返回体格式，下表阐述 data 及其字段。

示例

• 请求示例

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'

• 返回示例

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

3.10. 搜索 Agent 目录

接口描述

按名称、标签、协议和分页参数搜索可见的 Agent 目录条目。携带 X-Nacos-Client-Id 时只续约已存在的 HTTP Client，不会续约其 Endpoint Publisher 活性。

起始版本

3.3.0

请求方式

GET

请求URL

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

请求头

请求参数

返回数据

返回体遵循Nacos open API 统一返回体格式，下表阐述 data 及其字段。

示例

• 请求示例

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'

• 返回示例

{
  "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. 监听 Agent 发现变化

接口描述

对当前完整的监听集合执行一次批量长轮询。响应只提示哪些监听项发生变化；应用需再次 Discover 获取完整结果，再开始下一轮监听。持续监听优先使用 RAD SDK。

起始版本

3.3.0

请求方式

POST，请求体类型为 application/x-www-form-urlencoded。

请求URL

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

请求头

请求参数

每个监听项包含以下字段：

Java 客户端可用 AgentDiscoveryCanonicalizer.fingerprint(snapshot) 计算指纹。它不是定义的 contentDigest，也不能用 HTTP 原始 JSON 文本的 SHA-256 替代。监听集合变化后应替换上一轮请求，忽略过期代次及已取消项的响应。

返回数据

示例

先将同一发现请求的当前快照指纹保存到 NACOS_AGENT_FINGERPRINT，再执行：

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}\"}]"

正常超时示例：

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

3.12. 查询 MCP 服务版本

接口描述

获取指定 MCP 服务的在线版本及端点。省略版本时查询 latest。可选的客户端标识仅续约已有 HTTP Client，不能替代端点心跳。

起始版本

3.3.0

请求方式

GET

请求URL

/nacos/v3/client/ai/mcp

请求头

请求参数

返回数据

示例

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. 发布 MCP 版本

接口描述

从应用发布 MCP 版本。默认直接上线；createDraft=true 时只创建草稿，需要资源已进入生命周期托管模式，再按生命周期流程提交和发布。

起始版本

3.3.0

请求方式

POST，请求体类型为 application/x-www-form-urlencoded。

请求URL

/nacos/v3/client/ai/mcp

请求参数

返回数据

示例

以下发布一个 stdio 服务定义；它不会在 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. 注册 MCP 端点

接口描述

为已发布且配置了服务引用（REF）的远程 MCP 服务注册运行端点。先按 MCP 管理准备远程服务定义及版本；此处示例使用 my-remote-mcp 的 1.0.0。注册成功后按返回的心跳间隔持续续约。

同一身份和命名空间内，一个逻辑客户端的 Agent/MCP 发布复用稳定的 Client ID，并维护一个心跳任务。

起始版本

3.3.0

请求方式

POST，请求体类型为 application/x-www-form-urlencoded。

请求URL

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

请求头

请求参数

返回数据

示例

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'

返回示例（后续心跳使用实际响应中的间隔）：

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

3.15. 注销 MCP 端点

接口描述

注销当前 HTTP Client 拥有的 MCP 运行端点。使用注册时相同的 Client ID、服务、版本、地址和端口；不会删除服务定义。

起始版本

3.3.0

请求方式

DELETE，请求体类型为 application/x-www-form-urlencoded。

请求URL

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

请求头

请求参数

返回数据

成功时返回统一 Result，data 为 null。

示例

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 端点心跳

接口描述

续约共享 HTTP Client 及其拥有的 Agent/MCP 发布。按最新响应的 heartbeatIntervalMillis 调度一个心跳任务；返回 HTTP_CLIENT_NOT_FOUND 时重新注册需要保留的端点。查询或 Watch 不能代替发布者心跳。

起始版本

3.3.0

请求方式

PUT

请求URL

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

请求头

请求参数

无。

返回数据

示例

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. 搜索 MCP 资源

接口描述

按关键词、标签、协议和能力分页搜索当前可见且启用的 MCP 资源。空查询列出资源；同一数组内 tagsAll 全部匹配，protocolsAny 和 capabilitiesAny 各自任一匹配，不同条件之间同时满足。

起始版本

3.3.0

请求方式

GET

请求URL

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

请求参数

返回数据

示例

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. 搜索 Skill 资源

接口描述

按关键词和标签分页搜索当前可见且启用的 Skill，空查询列出资源。获取内容请使用 Skill 下载接口。

起始版本

3.3.0

请求方式

GET

请求URL

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

请求参数

返回数据

示例

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. 搜索 Prompt 资源

接口描述

按关键词和标签分页搜索当前可见且启用的 Prompt，空查询列出资源。获取模板内容请使用 Prompt 查询接口。

起始版本

3.3.0

请求方式

GET

请求URL

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

请求参数

返回数据

示例

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. 跨类型搜索 AI 资源

接口描述

使用游标搜索当前可见且启用的 AI 资源。空白 query 列出资源；非空时按相关度搜索。结果来自异步同步的索引，新发布的内容可能暂未出现。返回资源摘要，调用或下载内容仍需使用相应资源接口。

起始版本

3.3.0

请求方式

GET

请求URL

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

请求参数

每个数组过滤参数最多 32 个非空值；不同过滤条件同时满足。翻页时保持搜索条件不变，没有 nextCursor 即已到末页。

返回数据

示例

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'

无匹配资源示例：

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

3.21. 查询 AI HTTP 能力

接口描述

查询当前节点实现的 Client HTTP 能力，用于客户端选择接入方式。遵循 Client 鉴权配置，只校验身份，不要求具体 AI 资源权限。结果不授予资源访问权限，也不代表全部节点支持或迁移已完成。

起始版本

3.3.0

请求方式

GET

请求URL

/nacos/v3/client/ai/capabilities

请求参数

无。

返回数据

示例

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}}}