> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Proxy

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

With [Nuwa MCP Proxy](https://github.com/nuwa-protocol/nuwa/tree/main/nuwa-services/mcp-server-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`](https://www.npmjs.com/package/@nuwa-ai/mcp-server-proxy) - Ready to use without building from source.

<Note>
  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.
</Note>

## Quick start

<Note>
  Before you start: obtain a Service Key for your service DID. See the
  <a href="/build-caps/service-key">Service Key guide</a> and use the copied value as
  <code>SERVICE\_KEY</code>.
</Note>

<Tabs>
  <Tab title="Using NPM Package (Recommended)">
    <Steps>
      <Step title="Install globally">
        ```bash theme={null}
        # Install the published package
        npm install -g @nuwa-ai/mcp-server-proxy

        # Or use without installation
        npx @nuwa-ai/mcp-server-proxy --help
        ```
      </Step>

      <Step title="Create a config.yaml">
        ```yaml theme={null}
        # 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
        ```

        <Tip>
          Not sure where <code>SERVICE\_KEY</code> comes from? Follow the
          <a href="/build-caps/service-key">Service Key guide</a> to generate it via cadop-web.
        </Tip>
      </Step>

      <Step title="Run the proxy">
        ```bash theme={null}
        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)
        ```
      </Step>

      <Step title="Verify the proxied MCP server">
        You can use the [MCP Debug tool](https://test-app.nuwa.dev/cap-studio/mcp) provided by Cap Studio to verify and debug the proxied MCP server.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Build from Source">
    <Steps>
      <Step title="Clone and build">
        For development or customization, you can build from source. Find the full implementation in the [Nuwa Monorepo](https://github.com/rooch-network/nuwa/tree/main/nuwa-services/mcp-server-proxy).

        ```bash theme={null}
        git clone https://github.com/nuwa-protocol/nuwa.git
        cd nuwa/nuwa-services/mcp-server-proxy
        pnpm install
        pnpm build
        ```
      </Step>

      <Step title="Create config and run">
        Create your `config.yaml` (same as above) and run:

        ```bash theme={null}
        export SERVICE_KEY=...
        export UPSTREAM_API_TOKEN=...

        node dist/index.js --config ./config.yaml
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Upstream modes

<Tabs>
  <Tab title="httpStream">
    ```yaml theme={null}
    upstream:
      type: "httpStream"
      url: "https://api.example.com/mcp"
      auth:
        scheme: "bearer"
        token: "${UPSTREAM_API_TOKEN}"
    ```
  </Tab>

  <Tab title="stdio">
    ```yaml theme={null}
    upstream:
      type: "stdio"
      command: ["npx", "-y", "@vendor/your-mcp@latest"]
      env:
        API_KEY: "${UPSTREAM_API_KEY}"
    ```
  </Tab>
</Tabs>

## Preconfigured examples

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

<Tabs>
  <Tab title="Amap proxy (HTTP upstream)">
    **Using NPM Package:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    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`
  </Tab>

  <Tab title="Context7 proxy (stdio upstream)">
    **Using NPM Package:**

    ```bash theme={null}
    # 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:**

    ```bash theme={null}
    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`
  </Tab>
</Tabs>

## Relevant Docs

<CardGroup cols={2}>
  <Card title="Railway Deployment Tutorial" icon="train" href="/tutorials/deploy-mcp-proxy-railway">
    Complete guide to deploying MCP Server Proxy on Railway platform
  </Card>

  <Card title="MCP Pricing" icon="dollar-sign" href="/build-caps/service-pricing">
    Pricing for MCP tools
  </Card>

  <Card title="Revenue" icon="money-bill-wave" href="/build-caps/revenue">
    View balances, withdraw, and audit revenue history
  </Card>

  <Card title="Service Key" icon="key" href="/build-caps/service-key">
    How to obtain and configure SERVICE\_KEY
  </Card>

  <Card title="MCP Server" icon="server" href="/build-caps/mcp-server">
    Build a pay‑per‑call MCP server directly using the Payment Kit.
  </Card>
</CardGroup>