MCP Proxy

Set up your existing MCP server with a Nuwa MCP Proxy to start accepting payments

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.

Using NPM Package (Recommended)

1. 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
   
2. 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.

3. 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)
   
4. Verify the proxied MCP server

   You can use the MCP Debug tool provided by Cap Studio to verify and debug the proxied MCP server.

Build from Source

1. 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
   
2. 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

httpStream

upstream:
  type: "httpStream"
  url: "https://api.example.com/mcp"
  auth:
    scheme: "bearer"
    token: "${UPSTREAM_API_TOKEN}"

stdio

upstream:
  type: "stdio"
  command: ["npx", "-y", "@vendor/your-mcp@latest"]
  env:
    API_KEY: "${UPSTREAM_API_KEY}"

Preconfigured examples

Two ready-to-run examples are included. You can use them with either the npm package or source code:

Amap proxy (HTTP upstream)

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

Using Source Code:

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

Config reference: deployments/instances/amap-proxy/config.yaml

Context7 proxy (stdio upstream)

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

Using Source Code:

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

Config reference: deployments/instances/context7-proxy/config.yaml

Relevant Docs

Railway Deployment Tutorial

Complete guide to deploying MCP Server Proxy on Railway platform

MCP Pricing

Pricing for MCP tools

Revenue

View balances, withdraw, and audit revenue history

Service Key

How to obtain and configure SERVICE_KEY

MCP Server

Build a pay‑per‑call MCP server directly using the Payment Kit.