0
# AI/MCP Integration API
1

2
Model Context Protocol (MCP) integration for Nacos, enabling AI agents and tools to interact with Nacos services through standardized protocols. This module provides comprehensive support for registering, discovering, and managing MCP servers within the Nacos ecosystem.
3

4
## Capabilities
5

6
### AI Constants and Protocol Support
7

8
Core constants and protocol definitions for MCP integration, supporting multiple communication protocols including HTTP, SSE, WebSocket, and local execution modes.
9

10
```java { .api }
11
/**
12
 * Constants for AI and MCP protocol configuration
13
 */
14
class AiConstants {
15
    /**
16
     * MCP protocol and configuration constants
17
     */
18
    static class Mcp {
19
        /** Default namespace for MCP services */
20
        static final String MCP_DEFAULT_NAMESPACE = "public";
21
        
22
        /** Standard I/O protocol for local MCP servers */
23
        static final String MCP_PROTOCOL_STDIO = "stdio";
24
        
25
        /** Server-Sent Events protocol for streaming communication */
26
        static final String MCP_PROTOCOL_SSE = "mcp-sse";
27
        
28
        /** Streamable protocol for real-time data exchange */
29
        static final String MCP_PROTOCOL_STREAMABLE = "mcp-streamable";
30
        
31
        /** HTTP protocol for REST-based communication */
32
        static final String MCP_PROTOCOL_HTTP = "http";
33
        
34
        /** Dubbo RPC protocol for high-performance communication */
35
        static final String MCP_PROTOCOL_DUBBO = "dubbo";
36
        
37
        /** Reference-based endpoint type using Nacos service discovery */
38
        static final String MCP_ENDPOINT_TYPE_REF = "REF";
39
        
40
        /** Direct endpoint type with explicit address configuration */
41
        static final String MCP_ENDPOINT_TYPE_DIRECT = "DIRECT";
42
    }
43
}
44
```
45

46
### MCP Tool Management
47

48
Comprehensive tool specification and metadata management for AI agents, including schema validation and execution context.
49

50
```java { .api }
51
/**
52
 * MCP Tool definition with schema and metadata
53
 */
54
class McpTool {
55
    /** Tool name identifier */
56
    private String name;
57
    
58
    /** Human-readable tool description */
59
    private String description;
60
    
61
    /** JSON Schema for tool input validation */
62
    private Map<String, Object> inputSchema;
63
    
64
    String getName();
65
    void setName(String name);
66
    String getDescription();
67
    void setDescription(String description);
68
    Map<String, Object> getInputSchema();
69
    void setInputSchema(Map<String, Object> inputSchema);
70
}
71

72
/**
73
 * Tool metadata and execution context configuration
74
 */
75
class McpToolMeta {
76
    /** Execution context parameters for tool invocation */
77
    private Map<String, String> invokeContext;
78
    
79
    /** Tool availability flag */
80
    private boolean enabled = true;
81
    
82
    /** Template configurations for dynamic tool behavior */
83
    private Map<String, Object> templates;
84
    
85
    Map<String, String> getInvokeContext();
86
    void setInvokeContext(Map<String, String> invokeContext);
87
    boolean isEnabled();
88
    void setEnabled(boolean enabled);
89
    Map<String, Object> getTemplates();
90
    void setTemplates(Map<String, Object> templates);
91
}
92

93
/**
94
 * Complete tool specification container
95
 */
96
class McpToolSpecification {
97
    /** List of available tools */
98
    private List<McpTool> tools = new LinkedList<>();
99
    
100
    /** Metadata mapping for each tool by name */
101
    private Map<String, McpToolMeta> toolsMeta = new HashMap<>(1);
102
    
103
    List<McpTool> getTools();
104
    void setTools(List<McpTool> tools);
105
    Map<String, McpToolMeta> getToolsMeta();
106
    void setToolsMeta(Map<String, McpToolMeta> toolsMeta);
107
}
108
```
109

110
### MCP Server Configuration
111

112
Server registration and configuration management with support for multiple deployment modes and service discovery integration.
113

114
```java { .api }
115
/**
116
 * MCP Server capability enumeration
117
 */
118
enum McpCapability {
119
    /** Server provides executable tools */
120
    TOOL,
121
    
122
    /** Server provides AI prompts and templates */
123
    PROMPT,
124
    
125
    /** Server provides accessible resources */
126
    RESOURCE;
127
}
128

129
/**
130
 * Basic MCP server information and configuration
131
 */
132
class McpServerBasicInfo {
133
    /** Unique server identifier */
134
    private String id;
135
    
136
    /** Human-readable server name */
137
    private String name;
138
    
139
    /** Communication protocol (stdio, mcp-sse, mcp-streamable, http, dubbo) */
140
    private String protocol;
141
    
142
    /** Frontend protocol for client communication */
143
    private String frontProtocol;
144
    
145
    /** Server description and purpose */
146
    private String description;
147
    
148
    /** Repository information for server source */
149
    private Repository repository;
150
    
151
    /** Version details and metadata */
152
    private ServerVersionDetail versionDetail;
153
    
154
    /** Current server version */
155
    private String version;
156
    
157
    /** Remote service configuration (for non-stdio protocols) */
158
    private McpServerRemoteServiceConfig remoteServerConfig;
159
    
160
    /** Local server configuration (for stdio protocol) */
161
    private Map<String, Object> localServerConfig;
162
    
163
    /** Server availability status */
164
    private boolean enabled = true;
165
    
166
    /** Auto-discovered server capabilities */
167
    private List<McpCapability> capabilities;
168
    
169
    // Standard getters and setters for all properties
170
    String getId();
171
    void setId(String id);
172
    String getName();
173
    void setName(String name);
174
    String getProtocol();
175
    void setProtocol(String protocol);
176
    String getFrontProtocol();
177
    void setFrontProtocol(String frontProtocol);
178
    String getDescription();
179
    void setDescription(String description);
180
    Repository getRepository();
181
    void setRepository(Repository repository);
182
    ServerVersionDetail getVersionDetail();
183
    void setVersionDetail(ServerVersionDetail versionDetail);
184
    String getVersion();
185
    void setVersion(String version);
186
    McpServerRemoteServiceConfig getRemoteServerConfig();
187
    void setRemoteServerConfig(McpServerRemoteServiceConfig remoteServerConfig);
188
    Map<String, Object> getLocalServerConfig();
189
    void setLocalServerConfig(Map<String, Object> localServerConfig);
190
    boolean isEnabled();
191
    void setEnabled(boolean enabled);
192
    List<McpCapability> getCapabilities();
193
    void setCapabilities(List<McpCapability> capabilities);
194
}
195

196
/**
197
 * Extended server information with detailed endpoint and tool specifications
198
 */
199
class McpServerDetailInfo extends McpServerBasicInfo {
200
    /** Backend endpoint information list */
201
    private List<McpEndpointInfo> backendEndpoints;
202
    
203
    /** Complete tool specification */
204
    private McpToolSpecification toolSpec;
205
    
206
    /** All available versions */
207
    private List<ServerVersionDetail> allVersions;
208
    
209
    /** Nacos namespace identifier */
210
    private String namespaceId;
211
    
212
    List<McpEndpointInfo> getBackendEndpoints();
213
    void setBackendEndpoints(List<McpEndpointInfo> backendEndpoints);
214
    McpToolSpecification getToolSpec();
215
    void setToolSpec(McpToolSpecification toolSpec);
216
    List<ServerVersionDetail> getAllVersions();
217
    void setAllVersions(List<ServerVersionDetail> allVersions);
218
    String getNamespaceId();
219
    void setNamespaceId(String namespaceId);
220
}
221

222
/**
223
 * Server version information with release details
224
 */
225
class McpServerVersionInfo extends McpServerBasicInfo {
226
    /** Latest published version identifier */
227
    private String latestPublishedVersion;
228
    
229
    /** Detailed version information list */
230
    private List<ServerVersionDetail> versionDetails;
231
    
232
    String getLatestPublishedVersion();
233
    void setLatestPublishedVersion(String latestPublishedVersion);
234
    List<ServerVersionDetail> getVersionDetails();
235
    void setVersions(List<ServerVersionDetail> versionDetails);
236
}
237
```
238

239
### Service Discovery and Endpoint Management
240

241
Integration with Nacos service discovery for dynamic endpoint resolution and load balancing.
242

243
```java { .api }
244
/**
245
 * Nacos service reference for MCP server discovery
246
 */
247
class McpServiceRef {
248
    /** Target namespace for service lookup */
249
    private String namespaceId;
250
    
251
    /** Service group classification */
252
    private String groupName;
253
    
254
    /** Service name for discovery */
255
    private String serviceName;
256
    
257
    String getNamespaceId();
258
    void setNamespaceId(String namespaceId);
259
    String getGroupName();
260
    void setGroupName(String groupName);
261
    String getServiceName();
262
    void setServiceName(String serviceName);
263
}
264

265
/**
266
 * Remote service configuration for non-local MCP servers
267
 */
268
class McpServerRemoteServiceConfig {
269
    /** Service reference for Nacos discovery */
270
    private McpServiceRef serviceRef;
271
    
272
    /** API export path for service endpoints */
273
    private String exportPath;
274
    
275
    McpServiceRef getServiceRef();
276
    void setServiceRef(McpServiceRef serviceRef);
277
    String getExportPath();
278
    void setExportPath(String exportPath);
279
}
280

281
/**
282
 * Endpoint specification with flexible configuration
283
 */
284
class McpEndpointSpec {
285
    /** Endpoint type: DIRECT or REF */
286
    private String type;
287
    
288
    /** 
289
     * Endpoint configuration data:
290
     * - For DIRECT: includes 'address' and 'port'
291
     * - For REF: includes 'namespaceId', 'groupName', 'serviceName'
292
     */
293
    private Map<String, String> data = new HashMap<>();
294
    
295
    String getType();
296
    void setType(String type);
297
    Map<String, String> getData();
298
    void setData(Map<String, String> data);
299
}
300

301
/**
302
 * Concrete endpoint information for backend communication
303
 */
304
class McpEndpointInfo {
305
    /** Server IP address or hostname */
306
    private String address;
307
    
308
    /** Server port number */
309
    private int port;
310
    
311
    /** API path for MCP communication */
312
    private String path;
313
    
314
    String getAddress();
315
    void setAddress(String address);
316
    int getPort();
317
    void setPort(int port);
318
    String getPath();
319
    void setPath(String path);
320
}
321
```
322

323
### Registry and Version Management
324

325
Server registry operations with version control and remote repository integration.
326

327
```java { .api }
328
/**
329
 * Basic registry server information
330
 */
331
class McpRegistryServer {
332
    /** Server unique identifier */
333
    private String id;
334
    
335
    /** Server display name */
336
    private String name;
337
    
338
    /** Server description */
339
    private String description;
340
    
341
    /** Repository source information */
342
    private Repository repository;
343
    
344
    /** Version detail information */
345
    private ServerVersionDetail version_detail;
346
    
347
    String getId();
348
    void setId(String id);
349
    String getName();
350
    void setName(String name);
351
    String getDescription();
352
    void setDescription(String description);
353
    Repository getRepository();
354
    void setRepository(Repository repository);
355
    ServerVersionDetail getVersion_detail();
356
    void setVersion_detail(ServerVersionDetail version_detail);
357
}
358

359
/**
360
 * Detailed registry server with remote endpoints
361
 */
362
class McpRegistryServerDetail extends McpRegistryServer {
363
    /** List of remote communication endpoints */
364
    private List<Remote> remotes;
365
    
366
    List<Remote> getRemotes();
367
    void setRemotes(List<Remote> remotes);
368
}
369

370
/**
371
 * Nacos-specific registry server extension
372
 */
373
class NacosMcpRegistryServerDetail extends McpRegistryServerDetail {
374
    /** Nacos-specific endpoint specification */
375
    private McpEndpointSpec nacosMcpEndpointSpec;
376
    
377
    /** Tool specification for the server */
378
    private McpToolSpecification mcpToolSpecification;
379
    
380
    /** Associated Nacos namespace */
381
    private String nacosNamespaceId;
382
    
383
    McpEndpointSpec getNacosMcpEndpointSpec();
384
    void setNacosMcpEndpointSpec(McpEndpointSpec nacosMcpEndpointSpec);
385
    String getNacosNamespaceId();
386
    void setNacosNamespaceId(String nacosNamespaceId);
387
    McpToolSpecification getMcpToolSpecification();
388
    void setMcpToolSpecification(McpToolSpecification mcpToolSpecification);
389
}
390

391
/**
392
 * Registry server list with pagination support
393
 */
394
class McpRegistryServerList {
395
    /** List of registry servers */
396
    private List<McpRegistryServer> servers;
397
    
398
    /** Total count of available servers */
399
    private int total_count;
400
    
401
    /** Pagination token for next page */
402
    private String next;
403
    
404
    List<McpRegistryServer> getServers();
405
    void setServers(List<McpRegistryServer> servers);
406
    int getTotal_count();
407
    void setTotal_count(int total_count);
408
    String getNext();
409
    void setNext(String next);
410
}
411

412
/**
413
 * Version detail information
414
 */
415
class ServerVersionDetail {
416
    /** Version identifier */
417
    private String version;
418
    
419
    /** Release date timestamp */
420
    private String release_date;
421
    
422
    /** Latest version flag */
423
    private Boolean is_latest;
424
    
425
    String getVersion();
426
    void setVersion(String version);
427
    String getRelease_date();
428
    void setRelease_date(String releaseDate);
429
    Boolean getIs_latest();
430
    void setIs_latest(Boolean is_latest);
431
}
432

433
/**
434
 * Remote endpoint configuration
435
 */
436
class Remote {
437
    /** Transport protocol type */
438
    private String transport_type;
439
    
440
    /** Complete endpoint URL */
441
    private String url;
442
    
443
    String getTransport_type();
444
    void setTransport_type(String transport_type);
445
    String getUrl();
446
    void setUrl(String url);
447
}
448

449
/**
450
 * Repository placeholder for server source information
451
 */
452
class Repository {
453
    // Repository implementation details
454
}
455
```
456

457
### Security and Authentication
458

459
Credential management and authentication integration for secure MCP server communication.
460

461
```java { .api }
462
/**
463
 * AI service credential configuration
464
 */
465
class AiCredential {
466
    /** 
467
     * Credential type: OAuth2.0, JWT token, or custom
468
     * Default: "custom"
469
     */
470
    private String type = "custom";
471
    
472
    /** Credential reference or identifier */
473
    private String ref;
474
    
475
    String getType();
476
    void setType(String type);
477
    String getRef();
478
    void setRef(String ref);
479
}
480
```
481

482
### Error Handling
483

484
Error response handling for registry operations and MCP communication.
485

486
```java { .api }
487
/**
488
 * MCP registry error response
489
 */
490
class McpErrorResponse {
491
    /** Error message or code */
492
    private String error;
493
    
494
    String getError();
495
    void setError(String error);
496
}
497
```
498

499
## Usage Examples
500

501
### Basic MCP Server Registration
502

503
```java
504
import com.alibaba.nacos.api.ai.model.mcp.*;
505
import com.alibaba.nacos.api.ai.constant.AiConstants;
506

507
// Create a basic MCP server configuration
508
McpServerBasicInfo server = new McpServerBasicInfo();
509
server.setName("example-mcp-server");
510
server.setDescription("Example MCP server for AI tools");
511
server.setProtocol(AiConstants.Mcp.MCP_PROTOCOL_HTTP);
512
server.setEnabled(true);
513

514
// Configure remote service
515
McpServerRemoteServiceConfig remoteConfig = new McpServerRemoteServiceConfig();
516
McpServiceRef serviceRef = new McpServiceRef();
517
serviceRef.setNamespaceId("public");
518
serviceRef.setGroupName("AI_GROUP");
519
serviceRef.setServiceName("mcp-tool-service");
520
remoteConfig.setServiceRef(serviceRef);
521
remoteConfig.setExportPath("/mcp/api");
522
server.setRemoteServerConfig(remoteConfig);
523
```
524

525
### Tool Specification Setup
526

527
```java
528
// Create tool specification
529
McpTool tool = new McpTool();
530
tool.setName("calculate");
531
tool.setDescription("Perform mathematical calculations");
532

533
// Define input schema
534
Map<String, Object> schema = new HashMap<>();
535
schema.put("type", "object");
536
Map<String, Object> properties = new HashMap<>();
537
properties.put("expression", Map.of("type", "string", "description", "Mathematical expression"));
538
schema.put("properties", properties);
539
tool.setInputSchema(schema);
540

541
// Create tool specification container
542
McpToolSpecification toolSpec = new McpToolSpecification();
543
toolSpec.getTools().add(tool);
544

545
// Add tool metadata
546
McpToolMeta meta = new McpToolMeta();
547
meta.setEnabled(true);
548
Map<String, String> context = new HashMap<>();
549
context.put("timeout", "30s");
550
meta.setInvokeContext(context);
551
toolSpec.getToolsMeta().put("calculate", meta);
552
```
553

554
### Endpoint Configuration
555

556
```java
557
// Direct endpoint configuration
558
McpEndpointSpec directEndpoint = new McpEndpointSpec();
559
directEndpoint.setType(AiConstants.Mcp.MCP_ENDPOINT_TYPE_DIRECT);
560
Map<String, String> data = new HashMap<>();
561
data.put("address", "192.168.1.100");
562
data.put("port", "8080");
563
directEndpoint.setData(data);
564

565
// Reference-based endpoint configuration
566
McpEndpointSpec refEndpoint = new McpEndpointSpec();
567
refEndpoint.setType(AiConstants.Mcp.MCP_ENDPOINT_TYPE_REF);
568
Map<String, String> refData = new HashMap<>();
569
refData.put("namespaceId", "public");
570
refData.put("groupName", "AI_GROUP");
571
refData.put("serviceName", "mcp-service");
572
refEndpoint.setData(refData);
573
```
574

575
### Credential Configuration
576

577
```java
578
// Configure AI service credentials
579
AiCredential credential = new AiCredential();
580
credential.setType("OAuth2.0");
581
credential.setRef("oauth-token-reference");
582

583
// For JWT tokens
584
AiCredential jwtCredential = new AiCredential();
585
jwtCredential.setType("jwt");
586
jwtCredential.setRef("jwt-token-key");
587
```
588

589
This AI/MCP integration provides a comprehensive framework for connecting AI agents and tools with Nacos services, enabling dynamic service discovery, tool management, and secure communication across distributed AI systems.