Overview

Nacos MCP Router MCP Server Distribution Proxy is a distribution and routing layer that simplifies deploying, discovering, and managing MCP (Model Context Protocol) server instances using the official Nacos SDK. It consolidates common concerns such as service registration, discovery, distribution rules, and proxying so developers and operators can focus on model delivery and runtime configuration rather than manual orchestration.

The project acts as a lightweight control plane for MCP servers: it registers server instances in Nacos, exposes simple APIs for recommending and distributing server endpoints to clients, and can act as a reverse proxy for environments that require a single ingress point. This is particularly useful in edge-cloud scenarios, multi-cluster deployments, or when you need programmatic distribution strategies for model-serving endpoints.

Features

Service registration and discovery via the official Nacos SDK
Centralized recommendation/distribution logic for MCP servers
HTTP REST API for management (list, register, distribute, health)
Reverse-proxying to MCP servers (single ingress option)
Configurable distribution rules (by region, version, tags)
Metrics and health checks for operational visibility
Docker and Kubernetes-friendly deployment patterns
Simple configuration through YAML and environment variables

Installation / Configuration

Prerequisites:

Java 11+ (if running from JAR)
Docker (optional)
A running Nacos server (for service registry)

Quick start (build from source)

# clone and build (Maven)
git clone https://github.com/nacos-group/nacos-mcp-router.git
cd nacos-mcp-router
mvn -DskipTests package

# run the built jar
java -jar target/nacos-mcp-router-*.jar --spring.config.location=./application.yml

Run from Docker

# build an image
docker build -t nacos-mcp-router:latest .

# run with environment variables
docker run -d --name mcp-router \
  -e NACOS_SERVER_ADDR=127.0.0.1:8848 \
  -e ROUTER_PORT=8080 \
  -p 8080:8080 \
  nacos-mcp-router:latest

Kubernetes (example Deployment manifest snippet)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-router
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: mcp-router
        image: nacos-mcp-router:latest
        env:
        - name: NACOS_SERVER_ADDR
          value: "nacos.default.svc.cluster.local:8848"
        - name: ROUTER_PORT
          value: "8080"
        ports:
        - containerPort: 8080

Sample application.yml

nacos:
  server-addr: 127.0.0.1:8848
  namespace: public
router:
  port: 8080
  proxy-enabled: true
  distribution:
    default-strategy: zone-aware
    rules:
      - id: "rule-1"
        region: us-east
        target-tag: v2
metrics:
  prometheus: true

Configuration table (common keys)

Key	Description	Example
nacos.server-addr	Nacos server address for registry/discovery	127.0.0.1:8848
router.port	HTTP port to listen on	8080
router.proxy-enabled	Enable reverse proxy functionality	true
router.distribution.rules	Distribution rules used to select servers	See YAML example

Available Resources

GitHub repository: https://github.com/nacos-group/nacos-mcp-router
Nacos documentation for SDK and service discovery (refer to your Nacos version)
REST endpoints (common)
- GET /health — health check
- GET /servers — list registered MCP servers
- POST /servers — register a server (if manual registration is needed)
- POST /distribute — request a recommended server list or apply a distribution operation
- GET /metrics — Prometheus metrics (if enabled)

Example: list servers

curl -s http://localhost:8080/servers | jq

Example: request distribution

curl -X POST http://localhost:8080/distribute \
  -H "Content-Type: application/json" \
  -d '{
    "app": "image-inference",
    "region": "us-east",
    "tags": ["gpu","v2"]
  }'

Use Cases

Centralized model rollout: orchestrate which MCP server versions (tags) should receive client traffic during staged rollouts (canary, A/B).
- Example: Move traffic gradually from tag “v1” to “v2” in region “eu-west” by updating distribution rules in the router and letting the router recommend endpoints to clients.
Edge and disconnected deployments: use the router as a proxy to forward MCP requests from constrained networks to centrally managed MCP servers, while keeping local discovery in sync via Nacos.
- Example: Deploy a single router in each edge site to provide a local entry point that forwards to selected upstream MCP servers.
Blue/green and failover: maintain multiple candidate MCP servers and let the router switch traffic based on health and configured policies.
- Example: If health checks show backend A degraded, router switches new requests to backend B without changing client configuration.
Developer testing and CI: spin up a local router and register short-lived MCP servers via the REST API to simulate multi-instance scenarios for integration tests.

Notes for Developers

The router leverages the official Nacos SDK for registry and discovery; make sure your Nacos version is compatible.
Distribution rules are intentionally flexible—design rules around your deployment topology (region, zone, tags, versions).
Observe metrics and health endpoints in production to automate failover and monitoring.
Extend or integrate with your orchestration (CI/CD) to update distribution rules programmatically for progressive rollouts.

For the latest code, issues, and contribution guidelines, see the GitHub repo: https://github.com/nacos-group/nacos-mcp-router.