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:

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@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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Universal Gas Framework MCP Server

What this unlocks

Custody

Install

Wire into your MCP host

Claude Desktop

Claude Code

Codex CLI

Gemini CLI

Cursor / Windsurf / any stdio-MCP host

How this MCP works

Typical flow (3 steps)

Tools (19)

Discovery

Auth

Quote

Pay (self-custody — no signer required)

Execute — EVM destination

Execute — Solana destination

Execute — Sui destination

Status

Environment variables

Where to set them

Security model

Examples

List supported coins from your terminal

Inside Claude Desktop (after wiring config above)

Troubleshooting

Versioning

License

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages