Connect Claude Desktop

Claude Desktop today only speaks the stdio MCP transport — it does not talk HTTP. To bridge it to the TxNod HTTP server, install the published @txnod/mcp-stdio wrapper and point Claude Desktop at it. STDIO is exempt from the OAuth flow per MCP spec §“Protocol Requirements” — env-var PAT is the standards-compliant credential mode for stdio clients. See MCP OAuth — PAT vs OAuth for the full decision matrix.

Install the wrapper

npm install -g @txnod/mcp-stdio

The wrapper exposes a single binary, txnod-mcp-stdio. It reads exactly one environment variable — TXNOD_PAT — and accepts zero command-line flags. The remote URL https://mcp.txnod.com/api/mcp/transport is hard-coded in the wrapper’s source, so an attacker who tampers with your mcpServers config cannot redirect the wrapper to a different host or smuggle in additional credentials.

Mint a token

In the TxNod dashboard go to Developer → Tokens and click New token. Pick scopes that match the tools you’ll call from the desktop client, and a short-ish expiry. The secret is shown once. See the Personal Access Tokens guide for scope details.

Wire Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "txnod": {
      "command": "txnod-mcp-stdio",
      "env": {
        "TXNOD_PAT": "<YOUR_TOKEN>"
      }
    }
  }
}

Replace <YOUR_TOKEN> with the secret you minted. Note that you do not pass the URL or any flags here — the wrapper hard-codes both. Restart Claude Desktop and the txnod server should appear in the MCP panel.

Verify

If a tool call returns 401, the most common cause is TXNOD_PAT being unset or pointing at an expired token. Re-issue the token in the dashboard at Developer → Tokens, paste the new secret into the env block, and restart Claude Desktop.

Per-tool scopes

21 MCP tools today: 7 read-only data tools + 14 sandbox-only simulation tools that mutate state (advance invoices, fire webhooks, reset / delete sandbox projects). Sandbox tools require both the sandbox:simulate PAT scope and a kind='sandbox' project — the server’s assertSandboxProjectKind predicate prevents production projects from ever being targets. Mint a PAT with the narrowest scope set the agent actually needs; leave sandbox:simulate off PATs that only consume read tools. PAT scopes are not limited to MCP-tool-coverage — :write, webhooks:manage, and admin:all are available for direct partner-API use.

Sandbox tools require the sandbox:simulate scope, which is PAT-only. Claude Desktop is PAT-only anyway (the @txnod/mcp-stdio wrapper only accepts a TXNOD_PAT), so this is academic for this guide — but worth flagging because OAuth’s scope set is structurally fixed at 4 read scopes (projects:read, invoices:read, transactions:read, webhooks:read) and never includes sandbox:simulate. The server’s assertSandboxProjectKind predicate also rejects production projects from sandbox tools — a token with the scope cannot drive simulation against a production project.

Tool inputs do not carry a network filter — the project’s kind ('production' | 'testnet' | 'sandbox') is fixed at create time and selects the underlying chain network implicitly. To inspect testnet invoices, mint a PAT scoped to a testnet-kind project (production / testnet rows never co-exist within one project). get_orphan_payments returns unmatched on-chain receipts (TRON activation transactions excluded). get_rates / quote_amount are indicative pricing helpers.

What to expect in tool responses

The webhook envelope’s mode: 'production' | 'testnet' | 'sandbox' field carries the kind of the emitting project. InvoiceResponse no longer includes a network field — the project credential implies the kind. TRON invoices (coin: 'trx' / 'usdt_trc20') require operator-side address pre-activation; partner-side errors carry error_code: 'tron_no_activated_addresses_available' (see Wallets · TRON activation). BSC usdt_bep20 / usdc_bep20 use 18 decimals on-chain — render amount_crypto verbatim. TON invoices (coin: 'ton' / 'usdt_ton') are memo-chain: every TON invoice for a given operator shares the same deposit address and is disambiguated by an 8-hex payment_token in the transaction comment. If a user types the address by hand and forgets the comment, the deposit surfaces via get_orphan_payments (chain ton) instead of ever reaching invoice.paid — see Supported chains · TON.

Other MCP clients

• Claude Code — already speaks HTTP; you do not need this wrapper there.
• Cursor — same.