Universal Gas Framework MCP Server

MCP server for Universal Gas Framework. Plug into any MCP-compatible AI host (Claude Desktop, Claude Code, Codex CLI, Gemini CLI, Cursor) and your agent gets typed tools for gasless cross-chain transactions.

What this unlocks

Your agent wants to send tokens on a chain where it has no native gas. Normally that's a dead end — you'd have to bridge or buy gas first. UGF removes that step.

Pay with what you already hold, route the transaction anywhere:

• Stablecoins as gas — USDC, EURC, $U (United Stables), USDT
• Native EVM coins as gas — ETH (on Ethereum / Base / Optimism / Arbitrum), BNB, MATIC, AVAX
• Send to any supported destination — EVM chains, Solana (SOL + SPL), Sui (native + custom coins)
• Cross-chain by default — pay USDC on Base, transaction executes on Sui. Pay $U on BNB, transaction executes on Solana.

The agent only needs balance on one supported chain. UGF prices the route, collects payment, and executes the destination action.

Custody

Private keys never reach this MCP server. The agent signs every payload locally (EIP-712 for x402, EIP-1559 for vault, ed25519 for Solana, Sui Ed25519 for Sui). The server only:

1. Builds unsigned payloads
2. Submits the agent's signed proofs
3. Polls UGF gateway for route status

Verified by CI — private_key, mnemonic, secretKey, Keypair.fromSecretKey, new ethers.Wallet return zero hits in src/.

For UGF protocol details, gateway endpoints, and the value-to-action model, see universalgasframework.com. This README only covers the MCP server.

---

Install

The MCP server runs via npx. No global install needed.

npx -y @tychilabs/ugf-mcp@beta

That command launches it in stdio mode for an AI host. To inspect tools from a terminal:

npx -y @tychilabs/ugf-mcp@beta --tools
npx -y @tychilabs/ugf-mcp@beta --version
npx -y @tychilabs/ugf-mcp@beta --help

Requires Node 18+.

---

Wire into your MCP host

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ugf": {
      "command": "npx",
      "args": ["-y", "@tychilabs/ugf-mcp@beta"]
    }
  }
}

Restart Claude Desktop. The 19 UGF tools become available to Claude.

Claude Code

claude mcp add ugf -- npx -y @tychilabs/ugf-mcp@beta

Codex CLI

~/.config/codex/config.json:

{
  "mcpServers": {
    "ugf": {
      "command": "npx",
      "args": ["-y", "@tychilabs/ugf-mcp@beta"]
    }
  }
}

Gemini CLI

~/.config/gemini-cli/settings.json → same shape under mcpServers.

Cursor / Windsurf / any stdio-MCP host

Use the same command: "npx", args: ["-y", "@tychilabs/ugf-mcp@beta"] pattern in whatever config file the host expects.

---

How this MCP works

┌──────────────────┐        stdio JSON-RPC        ┌──────────────────┐
│  YOUR AI HOST    │ ◄──────────────────────────► │  @tychilabs/     │
│  (Claude / etc.) │     tools/list, tools/call   │  ugf-mcp         │
└──────────────────┘                              └────────┬─────────┘
                                                           │ HTTPS
                                                           ▼
                                                  UGF gateway
                                                  RPC nodes (EVM/Sol/Sui)

The server is stateless and keyless. It:

• discovers what coins/chains are payable (ugf_get_registry)
• reads on-chain balances (ugf_check_balance)
• prices a destination action as a UGF route (ugf_quote, ugf_smart_quote)
• returns unsigned payment payloads or destination-prepared bytes
• accepts your locally-produced signatures and submits proofs to UGF
• polls route status

Signing happens in your agent, not here. This MCP never sees a private key, mnemonic, or password. That's the whole point.

Typical flow (3 steps)

1. quote      → ugf_smart_quote { payer_address, dest_chain_id, dest_chain_type, tx_object }
                returns ranked routes with digest + payment_amount

2. pay        → ugf_x402_build_typed_data  OR  ugf_vault_build_tx
                returns payload your agent signs LOCALLY
                then: ugf_x402_submit_signed  OR  ugf_vault_submit_signed

3. execute    → destination-side helpers for the chain family
                EVM: ugf_evm_wait_sponsorship → broadcast locally → ugf_evm_confirm_user_tx
                Sol: ugf_sol_wait_user_sig_message → sign locally → ugf_sol_submit_user_sig
                Sui: ugf_sui_wait_sponsor_bytes → sign locally → ugf_sui_execute_signed_block

Your agent's LLM orchestrates these calls. The MCP just executes each.

---

Tools (19)

Run npx -y @tychilabs/ugf-mcp@beta --tools for the live list. Summary:

Discovery

Tool	Purpose
ugf_get_registry	List every supported payment coin + chains + token/vault addresses.
ugf_check_balance	Read on-chain balance for any EVM wallet/token/chain.

Auth

Tool	Purpose
ugf_get_nonce	Get the login nonce for a wallet address.
ugf_authenticate	Submit address + nonce + locally-produced signature → JWT.
ugf_set_token	Restore a cached JWT on a fresh session.

Quote

Tool	Purpose
ugf_quote	Explicit route — pick exact payment coin + chain.
ugf_smart_quote	Auto-discover the cheapest viable route across the agent's balances.

Pay (self-custody — no signer required)

Tool	Purpose
ugf_x402_build_typed_data	Return ERC-3009 typed-data for x402 payment. Agent signs locally.
ugf_x402_submit_signed	Submit the agent-produced x402 signature.
ugf_vault_build_tx	Return unsigned EIP-1559 vault payment tx. Agent signs + broadcasts locally.
ugf_vault_submit_signed	Submit the on-chain vault tx hash after the agent broadcasts.

Execute — EVM destination

Tool	Purpose
ugf_evm_wait_sponsorship	Wait until UGF has sponsored the destination side.
ugf_evm_confirm_user_tx	Confirm the agent-broadcast destination tx hash back to UGF.

Execute — Solana destination

Tool	Purpose
ugf_sol_wait_user_sig_message	Wait for UGF's prepared Solana message bytes.
ugf_sol_submit_user_sig	Submit the agent-produced ed25519 user signature.

Execute — Sui destination

Tool	Purpose
ugf_sui_wait_sponsor_bytes	Wait until UGF returns tx_bytes + sponsor_sig.
ugf_sui_execute_signed_block	Broadcast the dual-signed (user + sponsor) Sui block via Sui RPC.

Status

Tool	Purpose
ugf_check_status	Single-shot status check for a route digest.
ugf_poll_status	Poll until the route reaches a terminal state.

---

Environment variables

All optional. Public RPCs are used when not set.

Var	Default	Purpose
RPC_ETH	https://eth.llamarpc.com	Ethereum mainnet
RPC_OP	https://mainnet.optimism.io	Optimism
RPC_BNB	https://bsc-dataseed.binance.org	BNB chain
RPC_POLYGON	https://polygon-rpc.com	Polygon
RPC_OPBNB	https://opbnb-mainnet-rpc.bnbchain.org	opBNB
RPC_ARB	https://arb1.arbitrum.io/rpc	Arbitrum
RPC_AVAX	https://api.avax.network/ext/bc/C/rpc	Avalanche C-chain
RPC_BASE	https://mainnet.base.org	Base
SUI_RPC_URL	https://fullnode.mainnet.sui.io:443	Sui mainnet

Where to set them

Per MCP host config (preferred) — pass through to the spawned process:

{
  "mcpServers": {
    "ugf": {
      "command": "npx",
      "args": ["-y", "@tychilabs/ugf-mcp@beta"],
      "env": {
        "RPC_BASE": "https://base-mainnet.g.alchemy.com/v2/<your-key>",
        "RPC_ETH": "https://eth-mainnet.g.alchemy.com/v2/<your-key>"
      }
    }
  }
}

Local .env.mcp — useful for development. Copy .env.example → .env.mcp, fill in your keys, run the server in the same directory.

---

Security model

Layer	What's here	What's NOT here
MCP source	reads + RPC calls + UGF SDK glue	no key material, no ethers.Wallet, no Keypair.fromSecretKey, no mnemonic, no password
Wire protocol	JSON-RPC over stdio	no remote network listener — the host process pipes stdin/stdout
External calls	UGF gateway + public RPCs	no telemetry, no analytics, no third-party reporting

Verified by a CI grep guard — private_key, mnemonic, secretKey, Keypair.fromSecretKey, new ethers.Wallet must return zero hits in src/.

If you need a host-side wallet that signs for the agent automatically, that's a separate concern. This MCP server is the bridge — it expects a signing-capable client on the host.

---

Examples

List supported coins from your terminal

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ugf_get_registry","arguments":{}}}' \
  | npx -y @tychilabs/ugf-mcp@beta

Inside Claude Desktop (after wiring config above)

Ask:

What UGF payment coins are available on Base?

Claude will call ugf_get_registry and answer.

What's my USDC balance on Base for address 0x...?

Claude calls ugf_check_balance.

Quote a payment of 0.01 USDC on BNB paying gas from my Base USDC. My payer address is 0x...

Claude calls ugf_smart_quote, returns ranked routes. To actually execute, your agent needs to sign — see "How this MCP works" above.

---

Troubleshooting

symptom	likely cause	fix
Provider did not return EIP-1559 fee data	Payment chain is legacy gas (BNB, opBNB).	Pay from an EIP-1559 chain (Base, Ethereum, etc.) until the upstream SDK ships legacy-tx support.
Payment chain X temporarily disabled	BNB / opBNB blocked client-side for the same reason.	Same workaround as above.
Authentication required from gateway	Missing JWT.	Call ugf_get_nonce → sign locally → ugf_authenticate. Cache the returned JWT.
got 0 after a vault broadcast	Gateway indexer lag — the broadcast succeeded but gateway hadn't seen the block yet.	Wait 5–10 seconds and resubmit. The agent orchestrator that ships in our binary product already retries with backoff.
Unsupported payment chain	The chain ID you passed isn't in the registry.	Call ugf_get_registry first to see what's supported.
MCP host can't see the tools	npx didn't run / wrong path.	Test in a terminal with npx -y @tychilabs/ugf-mcp@beta --tools.

---

Versioning

Follows semver. 1.0.0-beta.1 is the first publicly published version. Breaking changes during beta will bump to -beta.N+1. After ~1 week of stable mainnet usage with no incidents, promotes to 1.0.0.

---

License

MIT — see LICENSE.

Links

• npm: https://www.npmjs.com/package/@tychilabs/ugf-mcp
• repo: https://github.com/TychiWallet/ugf-mcp
• issues: https://github.com/TychiWallet/ugf-mcp/issues
• UGF docs (protocol, not this MCP): https://universalgasframework.com
• UGF SDK: https://www.npmjs.com/package/@tychilabs/ugf-sdk
• Anthropic MCP spec: https://modelcontextprotocol.io