Connect Cursor

Cursor exposes MCP server configuration in its IDE settings. The setup mirrors Claude Code: paste a small JSON snippet that points at mcp.txnod.com — either let Cursor handle OAuth via browser auto-discovery, or paste a Personal Access Token for headless / CI use.

Quick start (recommended — OAuth auto-discovery)

When you add https://mcp.txnod.com/api/mcp/transport in Cursor’s MCP servers UI (Settings → MCP) without an Authorization header, Cursor 1.x auto-discovers the TxNod authorization server, opens a browser tab for sign-in (email-OTP or Google), and stores the resulting OAuth tokens locally. Subsequent IDE sessions use cached tokens until they expire or you revoke the client at /account/connected-apps.

{
  "mcpServers": {
    "txnod": {
      "url": "https://mcp.txnod.com/api/mcp/transport"
    }
  }
}

See the MCP OAuth guide for protocol details, token TTLs, and revocation.

Advanced — manual paste (Personal Access Token)

PATs remain useful for CI pipelines (no browser available), shared automation accounts, and operators who prefer not to grant a client browser-based session access.

Mint a token

In the TxNod dashboard go to Developer → Tokens and click New token. Pick the narrowest scopes that fit your usage and a short expiry. The token secret is displayed exactly once at creation; copy it directly into Cursor’s config rather than into a notepad you’ll forget about. The Personal Access Tokens guide covers scope choices.

Add the server in Cursor

Open Cursor’s MCP servers settings UI (Settings → MCP). Add a new server with the JSON config:

{
  "mcpServers": {
    "txnod": {
      "url": "https://mcp.txnod.com/api/mcp/transport",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Replace <YOUR_TOKEN> with the secret you minted. The dashboard’s MCP helper card on the Developer Tokens page renders this exact JSON with the URL pre-filled.

Verify

Restart Cursor (or reload the MCP server connection). The agent panel should list txnod and surface its tool inventory. Common failure modes:

• The PAT secret is misquoted (Cursor’s settings UI escapes JSON; paste, don’t retype).
• The PAT has expired.
• The PAT lacks the scope the requested tool needs (e.g. webhooks:read for get_webhook_events).
• The URL is wrong — make sure it points at https://mcp.txnod.com/api/mcp/transport, not the bare host.

OAuth-mode failures show different symptoms: a browser tab pops up unexpectedly mid-call (auto-discovery / DCR registration failed and the client is retrying the consent flow), or tools start returning 401 invalid_token after a session that previously worked (/account/connected-apps revoke happened, or the access token expired and refresh failed).

21 MCP tools today: 7 read-only + 14 sandbox-mutating. Read tools (list_projects, list_invoices, get_invoice, get_webhook_events, get_orphan_payments, get_rates, quote_amount) only need a :read-scoped PAT. The 14 sandbox tools (sandbox_simulate_*, sandbox_clock_advance, sandbox_reset, sandbox_delete, sandbox_list_wallets) drive the full invoice lifecycle (detect → paid → reverted → re-confirmed) without on-chain spend; they require both the sandbox:simulate PAT scope and a kind='sandbox' project. The server’s assertSandboxProjectKind predicate prevents production projects from ever being a target, with miss-cases collapsed into a uniform not_found. PAT scopes are not constrained to MCP-tool-coverage — :write, webhooks:manage, and admin:all are available for direct partner-API use.

Per-tool scope mapping:

Sandbox tools require the sandbox:simulate scope, which is PAT-only. OAuth’s scope set is structurally fixed at 4 read scopes (projects:read, invoices:read, transactions:read, webhooks:read) — sandbox:simulate is not in it, so OAuth tokens cannot call any sandbox tool (calls return 403 insufficient_scope). To drive sandbox tools from Cursor, switch the connector from OAuth to PAT mode and mint a PAT with sandbox:simulate and a kind='sandbox' target project. 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 chain network implicitly. To list testnet invoices, mint a PAT against a testnet-kind project; production / testnet rows never co-exist within one project.

What to expect in tool responses

The webhook envelope’s mode: 'production' | 'testnet' | 'sandbox' field carries the kind of the emitting project — branch on it if your agent processes both. InvoiceResponse itself no longer carries a network discriminator. Tool responses follow the same shapes the TxNod REST API and SDK use; the Wallets guide covers the TRON activation requirement (an agent calling list_invoices for a TRON-using project may see tron_no_activated_addresses_available errors flowing back from any backing invoice-create attempt). For BSC usdt_bep20 / usdc_bep20 note the 18-decimal trap from supported chains. TON invoices (coin: 'ton' / 'usdt_ton') are memo-chain: every TON invoice for a given operator shares one deposit address and is disambiguated by an 8-hex payment_token in the transaction comment; deposits whose comment is missing or unparseable surface via get_orphan_payments (chain ton) instead of ever reaching invoice.paid — see Supported chains · TON.

Other MCP clients

• MCP OAuth (protocol details) — discovery, registration, PKCE, audience binding, token TTLs, revocation.
• Claude Code — same HTTP transport, same JSON shape.
• Claude Desktop — needs the @txnod/mcp-stdio wrapper because Claude Desktop only speaks stdio.