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.

Related MCP server: Universal Crypto MCP

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

Auth

Quote

Pay (self-custody — no signer required)

Execute — EVM destination

Execute — Solana destination

Execute — Sui destination

Status

Environment variables

All optional. Public RPCs are used when not set.

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

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

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