Universal Gas Framework MCP Server
The Universal Gas Framework MCP Server enables AI agents to perform gasless cross-chain transactions, paying fees with tokens already held on a supported chain (e.g., USDC on Base) to execute actions on a different destination chain — without needing native gas on the destination. The server never handles private keys; all signing is done locally by the agent.
Discovery & Balance Checking
ugf_get_registry— List supported payment coins (USDC, EURC, $U, USDT, ETH, BNB, MATIC, etc.), chains, and contract/vault addresses.ugf_check_balance— Read an EVM wallet's on-chain balance for any ERC-20 or native token.
Authentication
ugf_get_nonce— Fetch a login nonce for a wallet address.ugf_authenticate— Submit a locally-signed nonce to obtain a JWT.ugf_set_token— Restore a cached JWT to skip re-authentication.
Quoting Routes
ugf_quote— Get a quote for a specific payment coin/chain for a given destination transaction.ugf_smart_quote— Auto-discover the cheapest route by scanning all wallet balances across supported chains.
Payment Construction & Submission
ugf_x402_build_typed_data— Build an ERC-3009 typed-data payload for local signing (x402 flow).ugf_x402_submit_signed— Submit the locally-signed x402 proof to UGF.ugf_vault_build_tx— Build an unsigned EIP-1559 vault payment transaction for local signing and broadcast.ugf_vault_submit_signed— Submit the on-chain vault transaction hash after local broadcast.
Destination Execution — EVM
ugf_evm_wait_sponsorship— Poll until UGF has sponsored the destination EVM transaction.ugf_evm_confirm_user_tx— Confirm the agent-broadcast destination EVM transaction hash.
Destination Execution — Solana
ugf_sol_wait_user_sig_message— Wait for UGF's prepared Solana message bytes for local signing.ugf_sol_submit_user_sig— Submit the locally-produced ed25519 signature.
Destination Execution — Sui
ugf_sui_wait_sponsor_bytes— Wait for UGF to return Suitx_bytesandsponsor_sig.ugf_sui_execute_signed_block— Broadcast the dual-signed (user + sponsor) Sui transaction block.
Status Tracking
ugf_check_status— Single-shot status check for a route by digest.ugf_poll_status— Continuously poll a route until it reaches a terminal state (completed/failed/expired).
Allows gasless transactions on BNB Chain using BNB or stablecoins as payment.
Allows gasless transactions on Ethereum using native ETH or stablecoins as payment.
Allows gasless transactions on Optimism using ETH or stablecoins as payment.
Allows gasless transactions on Polygon using MATIC or stablecoins as payment.
Allows gasless transactions on Solana using SOL or SPL tokens as payment.
Allows gasless transactions on Sui using native coins or custom coins as payment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Universal Gas Framework MCP Server send 50 USDC from Ethereum to Solana, pay with MATIC on Polygon"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: near-hydra-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:
Builds unsigned payloads
Submits the agent's signed proofs
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@betaThat 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 --helpRequires 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@betaCodex 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_blockYour 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 |
| List every supported payment coin + chains + token/vault addresses. |
| Read on-chain balance for any EVM wallet/token/chain. |
Auth
Tool | Purpose |
| Get the login nonce for a wallet address. |
| Submit address + nonce + locally-produced signature → JWT. |
| Restore a cached JWT on a fresh session. |
Quote
Tool | Purpose |
| Explicit route — pick exact payment coin + chain. |
| Auto-discover the cheapest viable route across the agent's balances. |
Pay (self-custody — no signer required)
Tool | Purpose |
| Return ERC-3009 typed-data for x402 payment. Agent signs locally. |
| Submit the agent-produced x402 signature. |
| Return unsigned EIP-1559 vault payment tx. Agent signs + broadcasts locally. |
| Submit the on-chain vault tx hash after the agent broadcasts. |
Execute — EVM destination
Tool | Purpose |
| Wait until UGF has sponsored the destination side. |
| Confirm the agent-broadcast destination tx hash back to UGF. |
Execute — Solana destination
Tool | Purpose |
| Wait for UGF's prepared Solana message bytes. |
| Submit the agent-produced ed25519 user signature. |
Execute — Sui destination
Tool | Purpose |
| Wait until UGF returns |
| Broadcast the dual-signed (user + sponsor) Sui block via Sui RPC. |
Status
Tool | Purpose |
| Single-shot status check for a route digest. |
| Poll until the route reaches a terminal state. |
Environment variables
All optional. Public RPCs are used when not set.
Var | Default | Purpose |
|
| Ethereum mainnet |
|
| Optimism |
|
| BNB chain |
|
| Polygon |
|
| opBNB |
|
| Arbitrum |
|
| Avalanche C-chain |
|
| Base |
|
| 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 |
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@betaInside 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 |
| Payment chain is legacy gas (BNB, opBNB). | Pay from an EIP-1559 chain (Base, Ethereum, etc.) until the upstream SDK ships legacy-tx support. |
| BNB / opBNB blocked client-side for the same reason. | Same workaround as above. |
| Missing JWT. | Call |
| 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. |
| The chain ID you passed isn't in the registry. | Call |
MCP host can't see the tools | npx didn't run / wrong path. | Test in a terminal with |
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
UGF docs (protocol, not this MCP): https://universalgasframework.com
Anthropic MCP spec: https://modelcontextprotocol.io
Available Tools
19 toolsugf_authenticateA
Complete UGF login. Agent signs the nonce from ugf_get_nonce with its private key and passes the signature here. Returns JWT for agent to cache.
Inputs: address (required), nonce (required), signature (required).
ugf_check_balanceA
Read on-chain balance for a wallet on a supported EVM chain. Pass token_address='native' for the chain's native token, or an ERC-20 contract address. Returns the raw balance in atoms (smallest unit) as a decimal string. Stateless RPC read — no keys required.
Inputs: payer_address (required), token_address (required), chain_id (required).
ugf_check_statusB
Poll UGF route status by digest. Returns current status and completion state.
Inputs: digest (required).
ugf_evm_confirm_user_txC
Confirm a user-broadcast destination EVM tx hash back to UGF.
Inputs: digest (required), tx_hash (required).
ugf_evm_wait_sponsorshipB
Wait until UGF sponsorship side is ready for a destination EVM tx. Agent then sends destination tx itself.
Inputs: digest (required), max_attempts, interval_ms.
ugf_get_nonceA
Fetch the UGF login nonce for a wallet address. Agent signs this nonce externally then calls ugf_authenticate.
Inputs: address (required).
ugf_get_registryA
Fetch UGF's live payment token registry. Returns the list of supported payment coins (e.g. USDC, $U, ETH) and the chains each can be paid on, including token + vault contract addresses. Use this to discover viable routes without doing a quote.
Inputs: invalidate_cache.
ugf_poll_statusA
Poll UGF route until completed/failed/expired. Use after payment to confirm execution.
Inputs: digest (required), max_attempts, interval_ms.
ugf_quoteB
Get a UGF quote for a specific payment coin and chain. Checks wallet balance against quote amount and returns whether the agent can proceed.
Inputs: payer_address (required), payment_coin (required), payment_chain (required), dest_chain_id (required), +2 more.
ugf_set_tokenA
Restore a cached UGF JWT on the MCP client. Use this on subsequent sessions to skip re-signing the nonce.
Inputs: jwt (required).
ugf_smart_quoteA
Auto-discover the best payment route. Fetches all wallet balances in parallel, gets quotes for every viable option, and returns ranked choices cheapest first. Agent just provides calldata and destination.
Inputs: payer_address (required), dest_chain_id (required), dest_chain_type (required), tx_object (required).
ugf_sol_submit_user_sigB
Submit a locally-produced Solana user signature to UGF. Pair with ugf_sol_wait_user_sig_message.
Inputs: digest (required), user_sig (required).
ugf_sol_wait_user_sig_messageB
Wait for the Solana user-sig message UGF prepared. Returns {serialized_message: base64}. Agent signs locally with its keypair via nacl.sign.detached, then calls ugf_sol_submit_user_sig.
Inputs: digest (required), max_attempts, interval_ms.
ugf_sui_execute_signed_blockB
Broadcast a dual-signed (user + sponsor) Sui transaction block via Sui RPC. Returns {tx_digest}.
Inputs: tx_bytes (required), user_sig (required), sponsor_sig (required), rpc_url.
ugf_sui_wait_sponsor_bytesA
Wait for UGF to prepare Sui sponsor tx_bytes + sponsor_sig (base64). Agent signs tx_bytes locally with its Sui Ed25519 keypair, then calls ugf_sui_execute_signed_block.
Inputs: digest (required), max_attempts, interval_ms.
ugf_vault_build_txA
Build unsigned EIP-1559 vault payment tx for local signing + broadcast. Returns {to, data, value, chainId, gasLimit, nonce, type, maxFeePerGas, maxPriorityFeePerGas} — all BigInts as strings. Agent signs + broadcasts, then calls ugf_vault_submit_signed.
Inputs: quote (required), payer_address (required).
ugf_vault_submit_signedA
Submit proof of a locally-broadcast vault payment tx. Pair with ugf_vault_build_tx.
Inputs: quote (required), tx_hash (required).
ugf_x402_build_typed_dataB
Build ERC-3009 x402 typed-data payload for local signing. Returns {domain, types, message, nonce, valid_after, valid_before}. Agent signs with signTypedData, then calls ugf_x402_submit_signed.
Inputs: quote (required), payer_address (required).
ugf_x402_submit_signedA
Submit a locally-signed x402 payload to UGF. Pair with ugf_x402_build_typed_data.
Inputs: quote (required), signature (required), nonce (required), valid_after (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
The tools are largely distinct by blockchain (EVM, Solana, Sui) and function (auth, balance, quote, submit). Paired operations like build/submit are clearly linked. Minor ambiguity exists between ugf_check_status and ugf_poll_status, but descriptions clarify that one polls until completion.
All tools start with 'ugf_' and use snake_case. Most follow a verb_noun pattern (e.g., ugf_check_balance, ugf_get_nonce). A few like ugf_authenticate omit the object, and ugf_smart_quote uses an adjective, but the overall pattern is predictable.
With 19 tools covering authentication, registry, balance, quoting, and payment operations across three blockchains plus EVM vault and x402, the count is well-scoped for the server's purpose. Each tool serves a clear role without bloat.
The tool surface covers the full lifecycle: discover (registry, balance), authenticate, quote, execute (per chain), and confirm. Missing are cancellation or withdrawal operations, but core payment workflows are complete.
Maintenance
Related MCP Connectors
Gasless cross-chain for AI agents: 25 nodes incl. Solana & native Bitcoin. One signature, no gas.
Zero-key, non-custodial cross-chain crypto swap aggregator for AI agents: 100+ chains, 15+ providers
Cross-chain token swaps for autonomous agents on Base L2 and partner rails
Non-custodial cross-chain swaps for AI agents: live route quotes and deposit swaps on 40+ chains.
Related MCP Servers
- FlicenseCqualityBmaintenanceEnables AI agents to interact with any EVM-compatible blockchain through natural language, supporting token swaps, cross-chain bridges, staking, lending, governance, gas optimization, and portfolio tracking across networks like Ethereum, BSC, Polygon, Arbitrum, and more.10041 npm44-
- AlicenseNot gradedqualityDmaintenanceEnables cross-chain transactions (swap, send, balance) on 10 blockchains from a single NEAR account, designed for AI agents and humans via MCP.6Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables gasless token swaps across multiple chains using OKX DEX aggregation and Biconomy MEE, allowing users to execute swaps via natural language without needing native gas tokens.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to perform complex crypto operations like cross-chain routing, contract decoding, portfolio management, and anti-rug security checks, returning unsigned transactions for safe signing by the agent.MIT