With Nuwa MCP Proxy, you can convert an existing MCP server (Streamable HTTP or STDIO) into a Nuwa‑Compatible MCP endpoint, enable DID authentication for the server and payment for your MCP tools, without changing the service. The proxy exposes a single JSON‑RPC endpoint (/mcp) over streamable HTTP, forwards tools, and attaches Nuwa payment semantics.
NPM Package: @nuwa-ai/mcp-server-proxy - Ready to use without building from source.
Nuwa MCP Proxy is designed to be single-server, single-endpoint MCP server. For multiple MCP servers, you have to deploy multiple Nuwa MCP Proxy instances.
Quick start
Before you start: obtain a Service Key for your service DID. See the
Service Key guide and use the copied value as
SERVICE_KEY. Install globally
# Install the published package
npm install -g @nuwa-ai/mcp-server-proxy
# Or use without installation
npx @nuwa-ai/mcp-server-proxy --help
Create a config.yaml
# Minimal proxy config
port: 8088
endpoint: "/mcp"
# Upstream MCP (streamable http or stdio)
upstream:
type: "httpStream"
url: "https://api.example.com/mcp"
# Optional auth to upstream
auth:
scheme: "bearer"
token: "${UPSTREAM_API_TOKEN}"
# Payment & network
serviceId: "my-mcp-service"
serviceKey: "${SERVICE_KEY}"
network: "test"
defaultPricePicoUSD: "100000000" # 0.0001 USD
debug: false
# Optional per-tool pricing (overrides default)
register:
tools:
- name: "example.search"
pricePicoUSD: "200000000" # 0.0002 USD
Not sure where SERVICE_KEY comes from? Follow the
Service Key guide to generate it via cadop-web. Run the proxy
export SERVICE_KEY=... # required for settlement
export UPSTREAM_API_TOKEN=... # if your upstream requires it
# Run with global installation
mcp-server-proxy --config ./config.yaml
# Or run with npx (no installation needed)
npx @nuwa-ai/mcp-server-proxy --config ./config.yaml
# → serves POST /mcp (JSON-RPC over streamable HTTP)
Verify the proxied MCP server
You can use the MCP Debug tool provided by Cap Studio to verify and debug the proxied MCP server. Clone and build
For development or customization, you can build from source. Find the full implementation in the Nuwa Monorepo.git clone https://github.com/nuwa-protocol/nuwa.git
cd nuwa/nuwa-services/mcp-server-proxy
pnpm install
pnpm build
Create config and run
Create your config.yaml (same as above) and run:export SERVICE_KEY=...
export UPSTREAM_API_TOKEN=...
node dist/index.js --config ./config.yaml
Upstream modes
upstream:
type: "httpStream"
url: "https://api.example.com/mcp"
auth:
scheme: "bearer"
token: "${UPSTREAM_API_TOKEN}"
upstream:
type: "stdio"
command: ["npx", "-y", "@vendor/your-mcp@latest"]
env:
API_KEY: "${UPSTREAM_API_KEY}"
Using NPM Package:# Download config file
curl -o amap-config.yaml https://raw.githubusercontent.com/nuwa-protocol/nuwa/main/nuwa-services/mcp-server-proxy/deployments/instances/amap-proxy/config.yaml
export AMAP_API_KEY=your_amap_api_key_here
export SERVICE_KEY=your_service_key_here
export PORT=8088
# Run with npm package
mcp-server-proxy --config ./amap-config.yaml
# Or with npx
npx @nuwa-ai/mcp-server-proxy --config ./amap-config.yaml
cd nuwa-services/mcp-server-proxy
export AMAP_API_KEY=your_amap_api_key_here
export SERVICE_KEY=your_service_key_here
export PORT=8088
./examples/run-amap-local.sh
# → Serves /mcp on http://localhost:8088
deployments/instances/amap-proxy/config.yaml Using NPM Package:# Download config file
curl -o context7-config.yaml https://raw.githubusercontent.com/nuwa-protocol/nuwa/main/nuwa-services/mcp-server-proxy/deployments/instances/context7-proxy/config.yaml
export SERVICE_KEY=your_service_key_here
export PORT=8089
# Run with npm package
mcp-server-proxy --config ./context7-config.yaml
# Or with npx
npx @nuwa-ai/mcp-server-proxy --config ./context7-config.yaml
cd nuwa-services/mcp-server-proxy
export SERVICE_KEY=your_service_key_here
export PORT=8089
./examples/run-context7-local.sh
# → Serves /mcp on http://localhost:8089
deployments/instances/context7-proxy/config.yaml Relevant Docs
