Connect an external registry (Nacos)

When the enterprise already manages A2A agents and MCP services with Nacos, the platform can treat a Nacos namespace as an external registry source and sync its entries on a poll interval. Synced-in external agents and MCP services are called through the gateway proxy, and are under the same distribution, traffic-rule, and audit constraints as hand-connected objects of the same kind. The full path from register, sync, review, to call, and how credentials are split, is in section 8.

1. Nacos requirements

• Version: Nacos 3.x, providing the AI registry management APIs (/nacos/v3/admin/ai/a2a, /nacos/v3/admin/ai/mcp). The platform has been verified with Nacos 3.1.2.
• Authentication: when authentication is on, the platform signs in with the username and password filled in on the registry source, obtains an access token, and renews it before expiry. When authentication is off, leave username and password blank. The account must be able to read A2A and MCP entries in the target namespace.
• Address: fill in the Nacos server address (for example http://nacos.example.com:8848), not the console address. When the platform's HTTP outbound protection is on, only an https:// address is accepted.

2. Register in Nacos

External agents (A2A)

Register an AgentCard in Nacos by agent name. The platform reads each agent's full card. url in the card must be an A2A endpoint the platform can reach. Authentication declared in the card (securitySchemes) is carried into the platform. An administrator configures matching credentials in the external-agent detail.

Management API as an example:

curl -X POST "http://nacos.example.com:8848/nacos/v3/admin/ai/a2a" \
  -H "accessToken: $TOKEN" \
  --data-urlencode "namespaceId=public" \
  --data-urlencode "agentName=order-agent" \
  --data-urlencode 'agentCard={"name":"order-agent","url":"https://agents.example.com/order/a2a", ...}'

MCP services

• Direct MCP: frontProtocol is mcp-streamable (Streamable HTTP) or mcp-sse (HTTP+SSE). The endpoint is registered with DIRECT address and port. remoteServerConfig.exportPath is the MCP path (for example /mcp, /sse). After sync, the platform discovers tools automatically.
• REST-to-MCP templates: the platform only syncs the parts it can execute equivalently. When a template contains body or header rewrite, Go/GJSON transforms, or similar that the platform cannot reproduce word for word, that entry is skipped and counted in Skipped templates.

3. Connect in the platform

1. From Admin Console → External registries, choose New source. Fill in Name, Address, Namespace, and Poll interval (seconds) (default 30, minimum 5).
2. When Nacos authentication is on, fill in Username and Password as a pair. On edit, leaving password blank keeps the existing credential.
3. Choose objects to sync: external agents, MCP services.
4. Decide whether Auto-approve (trusted source) is on; see section 5.
5. After save, choose Test connection. The result shows how many external agents and MCP services can be synced, and how many templates were skipped.
6. Choose Sync now, or wait for automatic sync on the poll interval. The list shows Health, Last sync, Sync count, and Enabled.

4. Allow intranet addresses

Platform access to the Nacos address, and to service addresses registered in Nacos (A2A card URLs, MCP endpoints), all go through outbound protection. Configure it only on Platform SSRF outbound protection under Admin Console → Security settings → Outbound protection. Deployment operations do not need to change environment variables or restart services:

Each list item is an exact host:port (for example nacos.corp:8848). Host-only, wildcards, or CIDRs are not supported. The Nacos address and registered service addresses are maintained in the same list. After save it takes effect on the control plane and gateway nodes within a few seconds.

Service addresses registered in Nacos are judged as external data. They do not hit the read-only Deployment built-in allow items on the page, so a registry address cannot point at the platform's own internal services. When allow is missing, Test connection or sync fails, the registry source shows Abnormal or Degraded, and matching entries are not synced.

5. Auto-approve and manual review

• Auto-approve (on by default when creating): synced-in external agents are Approved directly. MCP services take effect directly and can be called through the proxy.
• Auto-approve off: external agents enter the External agents list as Pending review. An administrator Approves or Rejects them one by one. MCP services enter as not in effect, and are published after checking. A rejected entry returns to Pending review on the next sync.

6. Visible after distribution

Whether auto-approve is on or not, synced-in external agents and MCP services still need availability set in their Distribution (whole tenant, department, function group, and similar) before members can see and call them in the external-agent plaza and the MCP plaza. In the external-agent list, the source of these entries shows as Registry. Before go-live, verify visibility and call results with an in-scope account and an out-of-scope account separately.

7. Sync and delete rules

• Repeating sync of the same entry from the same registry source updates the original record.
• An upstream entry is treated as deleted only after it is missing in two consecutive polls: the external agent is disabled; the MCP service is archived and its gateway tokens are revoked.
• When a single sync result is empty, or one sync would delete more than half of the entries, the platform pauses deletion and marks the registry source Degraded, so a Nacos failure does not take the whole set offline.
• Deleting a registry source revokes MCP gateway tokens synced from it, and removes synced-in external agents and MCP services. It can be connected again afterwards.

8. End-to-end path

This section states the full process of an MCP service from registration in Nacos to being called by a member, and which credential each segment uses. External agents (A2A) follow the same register, sync, review, and distribution process. The call segment is forwarded by the external-agent gateway.

Flow

① Register     Provider ──register MCP / A2A entry──▶ Nacos namespace

② Sync         Platform control plane ──Nacos username and password sign-in──▶ Nacos
               Nacos ──access token──▶ Platform control plane (cached; re-sign-in 60 seconds before expiry)
               Platform control plane ──carry the access token; list entries on the poll interval──▶ Nacos
               Platform control plane: diff against the last result → add / update / disable or archive
               Platform control plane ──for newly synced or updated MCP services──▶ tool discovery

③ Review / distribute  Auto-approve: take effect directly ┐
                       Manual review: take effect after an administrator checks ┴──▶ distribute to members (whole tenant, department, function group, …)

④ Obtain a token  Path 1: member → MCP service detail **Get connection config** → issue an MCP token (starts with zg_mcp_, shown only once)
                  Path 2: MCP client ──OAuth authorization code + PKCE S256──▶ platform authorization
                          member signs in and agrees on the authorization page → platform issues an MCP token (starts with zg_mcp_) to the client

⑤ Call         MCP client ──Authorization: Bearer zg_mcp_…──▶ gateway node
               Gateway node: validates the token in the local snapshot (does not hit the control plane per request)
               Gateway node ──injects upstream credentials, then forwards──▶ upstream MCP service
               Upstream MCP service ──result──▶ gateway node ──▶ MCP client

⑥ Record       Gateway node: produces a call record and audit event ──local queue, async upload──▶ platform control plane

Step by step

1. The provider registers the service in Nacos. Register an MCP service or an external-agent card in the target namespace per section 2. Registration describes only service address, protocol, and tools. It does not carry credentials needed for upstream authentication.
2. The platform signs in to Nacos and syncs. Sync is run by the platform control plane. In a multi-instance deployment only one instance polls Nacos. When Nacos authentication is on, the platform calls the Nacos sign-in API with the username and password filled in on the registry source, reuses the access token while it is valid, and signs in again 60 seconds before expiry. When Nacos does not return a validity period, it is treated as 5 minutes. The platform lists entries in the namespace on the Poll interval (seconds), then adds, updates, or deletes after diffing against the last result (delete rules in section 7). For known entries, the platform also listens to Nacos configuration changes, so an update does not wait for the next poll. Every synced-in address is checked by outbound protection before it is written (see section 4). After a direct MCP service is synced, the platform connects to that service and discovers tools automatically. A REST-to-MCP template is compiled locally by the platform into tools.
3. An administrator reviews and distributes. When the registry source has Auto-approve (trusted source) on, synced-in MCP services take effect directly. When it is off they enter as not in effect and are published after an administrator checks (see section 5). Then set availability in the MCP service's Distribution (see section 6).
4. A member obtains an MCP token. Both methods are turned on by the tenant under Allowed types in Security policy on Admin Console → System Settings → Global settings → Account & session security:
   • Token: the member opens the service detail in the MCP plaza, chooses Get connection config, chooses Token validity, then issues. The token starts with zg_mcp_, is shown only at issue time, and represents the current member when calling. Validity does not exceed the tenant's Maximum token validity.
   • OAuth: the member chooses Show MCP config in the service detail and writes the access URL into an MCP client that supports OAuth. On first connect the client receives 401, then jumps to platform authorization with authorization-code plus PKCE S256. After the member signs in and chooses Allow access on the Authorization request page, the platform issues the client an MCP token that also starts with zg_mcp_. This method requires the tenant to have enabled an Enterprise IAM (OAuth2) identity source, with sign-in method External OAuth2 IAM or Platform account direct sign-in. An OpenID Connect identity source is only for web sign-in and cannot be used for this flow.
5. The client calls the gateway carrying the token. The access URL is https://<gateway-address>/api/v1/agent-gateway/mcp-servers/<service-id>/mcp. The request header is Authorization: Bearer zg_mcp_…. The gateway node validates the token in the tenant snapshot stored on this host: whether the token exists and is not revoked, whether it is expired, whether it belongs to the service being called, whether the service is in effect, whether the tenant license is valid. Any miss returns 401. Validation does not hit the control plane per request. When a just-issued token is not yet in the local snapshot, the node fetches the snapshot once for that tenant and then validates. After validation passes, the gateway decrypts that service's upstream credentials, injects them into the request, forwards to the upstream MCP service, and runs traffic rules, content safety, and outbound protection.
6. The gateway produces a call record and audit. Each call's result, duration, token used, and tool name are produced as a call record and audit event on the gateway node, written to a local queue, then uploaded asynchronously to the control plane. An administrator can view each token's use record and recent activity under Token management on the MCP services page.

Credentials and authentication

The whole path involves three kinds of credential. Each is used on only one segment; they do not substitute for each other:

Unified authentication: the caller only faces an MCP token issued by the gateway. Whether the service came from Nacos or was connected by hand, the gateway validates identity, distribution scope, and license by the same rules. Nacos accounts and upstream credentials are never given to the caller. Token expiry is judged immediately by the gateway node against the local clock. Token revocation, a disabled member, or the service no longer being distributed to that member takes effect after the gateway node's next snapshot update. When a registry source is deleted, or an upstream entry is confirmed deleted, the platform revokes every MCP token of that service (see section 7).

Current boundary: the MCP-service call ingress currently only accepts MCP tokens (issued directly or issued after OAuth authorization). A business system carrying a user token issued by the enterprise identity source and calling directly currently covers only the model-call ingress (see Call models with enterprise identity). It does not apply to MCP services or external agents.