R-NACOS RNacos V1 Open API

Overview

This document describes the R-NACOS HTTP Open API endpoints under /rnacos/v1 , plus the MCP proxy, health-check, metrics-export, and data-backup endpoints under /rnacos . These are native R-NACOS protocols and are not compatible with the Nacos SDK.

Base URL: http://127.0.0.1:8848

---

1. MCP Service Management

1. List MCP Servers

Endpoint: GET /rnacos/v1/mcp/server/list

Description: List MCP servers with pagination.

Request Parameters

Parameter	Type	Required	Description
pageNo	number	No	Page number; defaults to 1 (must not be 0)
pageSize	number	No	Page size; defaults to 20 (maximum 1000)
namespaceId	string	No	Namespace ID; empty by default
nameFilter	string	No	Server-name filter (fuzzy match)

Response

Parameter	Type	Description
code	string	Response code
message	string	Error message
data	object	Paginated result
data.totalCount	number	Total records
data.list	array	MCP server list
data.list[].name	string	Server name
data.list[].description	string	Server description
data.list[].namespace	string	Namespace
data.list[].uniqueKey	string	Unique identifier key
data.list[].tools	array	Tool list
data.list[].tools[].name	string	Tool name
data.list[].tools[].description	string	Tool description
data.list[].tools[].inputSchema	object	JSON Schema for tool input parameters

Example

curl -X GET "http://127.0.0.1:8848/rnacos/v1/mcp/server/list?pageNo=1&pageSize=10&namespaceId="

Response:

{"code":"SUCCESS","message":null,"data":{"totalCount":1,"list":[{"name":"my-mcp-server","description":"Example MCP server","namespace":"","uniqueKey":"abc123","tools":[{"name":"query","description":"Query tool","inputSchema":{"type":"object","properties":{}}}]}}}

---

2. List Tool Specifications

Endpoint: GET /rnacos/v1/mcp/toolspec/list

Description: List MCP tool specifications with pagination.

Request Parameters

Parameter	Type	Required	Description
pageNo	number	No	Page number; defaults to 1 (must not be 0)
pageSize	number	No	Page size; defaults to 20 (maximum 1000)
namespaceId	string	No	Namespace ID; empty by default
groupFilter	string	No	Group filter
toolNameFilter	string	No	Tool-name filter (fuzzy match)

Response

Parameter	Type	Description
code	string	Response code
message	string	Error message
data	object	Paginated result
data.totalCount	number	Total records
data.list	array	Tool-specification list
data.list[].namespace	string	Namespace
data.list[].group	string	Group
data.list[].tool	object	Tool information
data.list[].tool.name	string	Tool name
data.list[].tool.description	string	Tool description
data.list[].tool.inputSchema	object	JSON Schema for tool input parameters

Example

curl -X GET "http://127.0.0.1:8848/rnacos/v1/mcp/toolspec/list?pageNo=1&pageSize=10&namespaceId="

Response:

{"code":"SUCCESS","message":null,"data":{"totalCount":2,"list":[{"namespace":"","group":"DEFAULT_GROUP","tool":{"name":"query","description":"Query tool","inputSchema":{"type":"object","properties":{}}}}]}}

---

2. MCP Proxy Endpoints

The MCP proxy is based on JSON-RPC 2.0 and SSE (Server-Sent Events), allowing an MCP (Model Context Protocol) client to connect directly to a service proxied by R-NACOS.

3. MCP JSON-RPC Request

Endpoint: POST /rnacos/mcp/{serverKey}/{authKey}

Description: Interact with an MCP server over JSON-RPC 2.0. The Accept header selects streaming or non-streaming mode.

Path Parameters

Parameter	Type	Required	Description
serverKey	string	Yes	Unique MCP server identifier
authKey	string	Yes	Authentication key

Request Headers

Parameter	Type	Required	Description
Accept	string	Yes	Must include application/json or text/event-stream
mcp-session-id	string	No	MCP session ID; omit on the first request and the server generates one

Request Body (JSON-RPC 2.0)

Parameter	Type	Required	Description
jsonrpc	string	Yes	Always 2.0
method	string	Yes	Method name
params	object	No	Method parameters
id	any	No	Request ID

Supported Methods

Method	Description	Parameters
initialize	Initialize the connection	protocolVersion , etc.
notifications/initialized	Notify the server that the client is initialized	None (returns 202 Accepted)
ping	Heartbeat check	None
tools/list	List tools	None
tools/call	Call a tool	name (tool name), arguments (arguments)
resources/list	List resources (returns empty)	None
resources/templates/list	List resource templates (returns empty)	None
prompts/list	List prompts (returns empty)	None

Response (JSON-RPC 2.0)

Parameter	Type	Description
jsonrpc	string	Always 2.0
result	object	Result on success (mutually exclusive with error)
error	object	Error information on failure
error.code	number	Error code
error.message	string	Error description
error.data	any	Additional error data
id	any	Matching request ID

initialize result structure:

Parameter	Type	Description
protocolVersion	string	Protocol version
capabilities	object	Server capabilities
capabilities.tools	object	Tool capabilities
capabilities.tools.listChanged	boolean	Whether tool-change notifications are supported
capabilities.resources	object	Resource capabilities
capabilities.prompts	object	Prompt capabilities
serverInfo	object	Server information
serverInfo.name	string	Server name（ r-nacos-mcp-server ）
serverInfo.version	string	Server version

tools/list result structure:

Parameter	Type	Description
tools	array	Tool list
tools[].name	string	Tool name
tools[].description	string	Tool description
tools[].inputSchema	object	Input-argument JSON Schema

tools/call result structure:

Parameter	Type	Description
content	array	Content list
content[].type	string	Content type; always text
content[].text	string	Text content

Error Codes

Error code	Description
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid parameters
-32000	Server error

Example

Initialize the connection:

curl -X POST "http://127.0.0.1:8848/rnacos/mcp/my-server/my-auth-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26"},"id":1}'

Response:

{"jsonrpc":"2.0","result":{"protocolVersion":"2025-03-26","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"r-nacos-mcp-server","version":"0.1.0"}},"id":1}

List tools:

curl -X POST "http://127.0.0.1:8848/rnacos/mcp/my-server/my-auth-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "mcp-session-id: abc123" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

Call a tool:

curl -X POST "http://127.0.0.1:8848/rnacos/mcp/my-server/my-auth-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "mcp-session-id: abc123" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"query","arguments":{"key":"value"}},"id":3}'

---

4. MCP GET Request

Endpoint: GET /rnacos/mcp/{serverKey}/{authKey}

Description: MCP GET request; currently returns 405 Method Not Allowed .

Path Parameters

Parameter	Type	Required	Description
serverKey	string	Yes	Unique MCP server identifier
authKey	string	Yes	Authentication key

Response

Returns 405 METHOD_NOT_ALLOWED .

---

5. MCP DELETE Request

Endpoint: DELETE /rnacos/mcp/{serverKey}/{authKey}

Description: MCP DELETE request used to close a connection.

Path Parameters

Parameter	Type	Required	Description
serverKey	string	Yes	Unique MCP server identifier
authKey	string	Yes	Authentication key

Response

• Success: returns ok

---

6. MCP SSE Connection

Endpoint: GET /rnacos/mcp/sse/{serverKey}/{authKey}

Description: Establish a persistent MCP SSE (Server-Sent Events) connection. Once connected, the server pushes an endpoint event containing the URL for subsequent messages.

Path Parameters

Parameter	Type	Required	Description
serverKey	string	Yes	Unique MCP server identifier
authKey	string	Yes	Authentication key

Response

• Response type: text/event-stream
• Response headers include: Content-Type: text/event-stream 、 Cache-Control: no-cache 、 X-Accel-Buffering: no

SSE Events

After the connection is established, the server first pushes an endpoint event:

event: endpoint
data: /rnacos/mcp/sse/messages/{nodeId}/{serverKey}/{sessionId}

The server then pushes message events over SSE in response to client messages:

event: message
data: {"jsonrpc":"2.0","result":{...},"id":1}

Example

curl -N "http://127.0.0.1:8848/rnacos/mcp/sse/my-server/my-auth-key"

---

7. MCP SSE Message

Endpoint: POST /rnacos/mcp/sse/messages/{nodeId}/{serverKey}/{sessionId}

Description: Send JSON-RPC requests through the SSE message channel. The endpoint event emitted when the SSE connection is established provides nodeId , serverKey , and sessionId .

Path Parameters

Parameter	Type	Required	Description
nodeId	number	Yes	Raft node ID
serverKey	string	Yes	Unique MCP server identifier
sessionId	string	Yes	SSE session ID

Request Body

Uses the same JSON-RPC 2.0 format as an MCP JSON-RPC request.

Response

• Success: returns 202 Accepted

Example

curl -X POST "http://127.0.0.1:8848/rnacos/mcp/sse/messages/1/my-server/abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Response:

Accepted

Notes

• If the requested nodeId differs from the current node, the request is forwarded to the correct node
• After processing, the result is pushed to the client over SSE; the HTTP response only returns Accepted

---

3. Health Check

8. Health Check

Endpoint: GET /rnacos/health

Description: Check the health of the R-NACOS service.

Request Parameters

None

Response

• Healthy: returns success
• Unhealthy: returns error: <Error message> (HTTP 503)

Example

curl -X GET "http://127.0.0.1:8848/rnacos/health"

Response:

success

---

4. Metrics Export

9. Export Metrics

Endpoint: GET /rnacos/metrics

Description: Export metrics in Prometheus format.

Request Parameters

None

Response

Returns Prometheus metrics as text/plain;version=0.0.4;charset=utf-8 .

Example

curl -X GET "http://127.0.0.1:8848/rnacos/metrics"

---

5. Data Backup

10. Export a Data Backup

Endpoint: GET /rnacos/backup

Description: Export an R-NACOS data backup. RNACOS_BACKUP_TOKEN must be configured.

Request Parameters

Parameter	Type	Required	Description
token	string	Yes	Backup token; must match RNACOS_BACKUP_TOKEN

Response

• Success: returns the data backup as a binary stream
• Backup disabled: returns backup api is not open （HTTP 500）
• Token mismatch: returns backup token is not matched （HTTP 500）

Example

curl -X GET "http://127.0.0.1:8848/rnacos/backup?token=your_backup_token" -o backup.zip

Notes

• Set the RNACOS_BACKUP_TOKEN environment variable first
• The backup token cannot be empty; otherwise the backup endpoint is unavailable