# mossgate-mcp

a model context protocol (mcp) stdio server that exposes two live paid apis to
any mcp-enabled agent:

- mossgate trust (`https://api.mossgate.dev`) token and wallet risk checks
- rue render (`https://rue.mossgate.dev`) url/html to pdf/png/jpeg

payment is x402 v2, usdc on base. the operator who runs this server funds a
wallet, and every tool call spends a little usdc from it. the wallet signs an
eip-3009 authorization gaslessly, so it needs only usdc, no eth for gas.

## tools

- `token_verdict(address, chain=base)` quick risk verdict for a token contract
- `wallet_profile(address, chain=base)` behavioural risk profile for a wallet
- `token_report(address, chain=base)` full token report
- `render(url|html, format=pdf|png|jpeg)` render a page, returns a base64 file

## install

```sh
cd mcp-server
npm install
```

node 18+ is required.

## fund the wallet

1. create or reuse an evm wallet (any tool that gives a 0x private key).
2. send it usdc on base (contract
   `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`). a few dollars covers many
   calls. no eth is needed, gas is sponsored by the facilitator.
3. export the private key as an env var (never commit it):

```sh
export MOSSGATE_BUYER_PK=0xyourprivatekey
```

optional overrides: `MOSSGATE_RPC` (base rpc url),
`MOSSGATE_TRUST_URL`, `MOSSGATE_RENDER_URL`.

## run standalone

```sh
MOSSGATE_BUYER_PK=0x... node index.js
```

the server speaks mcp over stdio. it is meant to be launched by an mcp client,
not used by hand.

## claude desktop / mcp client config

add this to your mcp client config (for claude desktop:
`~/.config/Claude/claude_desktop_config.json` on linux, or
`~/Library/Application Support/Claude/claude_desktop_config.json` on macos):

```json
{
    "mcpServers": {
        "mossgate": {
            "command": "node",
            "args": ["/absolute/path/to/products/mcp-server/index.js"],
            "env": {
                "MOSSGATE_BUYER_PK": "0xyourprivatekey"
            }
        }
    }
}
```

restart the client. the four tools appear and each call is paid automatically
from the funded wallet.

## verify it starts (no paid calls)

this lists the tools over stdio without touching the apis or spending anything:

```sh
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| node index.js
```

## run without cloning

this package is on npm, so agents and clients can run it via npx with no
clone or install. set the `command` to `npx` and `args` to
`["-y", "mossgate-mcp"]` in the client config:

```json
{
    "mcpServers": {
        "mossgate": {
            "command": "npx",
            "args": ["-y", "mossgate-mcp"],
            "env": {
                "MOSSGATE_BUYER_PK": "0xyourprivatekey"
            }
        }
    }
}
```