convez.ai
MCP Server
TychiWallet

ugf-mcp

TychiWallet/ugf-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for gasless cross-chain transactions — agents pay with stablecoins or any native EVM coin and route to EVM, Solana, or Sui. Self-custody by design.

Instalação

$npx convez-ai TychiWallet/ugf-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Universal Gas Framework MCP Server

npm license

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

ToolPurpose
ugf_get_registryList every supported payment coin + chains + token/vault addresses.
ugf_check_balanceRead on-chain balance for any EVM wallet/token/chain.

Auth

ToolPurpose
ugf_get_nonceGet the login nonce for a wallet address.
ugf_authenticateSubmit address + nonce + locally-produced signature → JWT.
ugf_set_tokenRestore a cached JWT on a fresh session.

Quote

ToolPurpose
ugf_quoteExplicit route — pick exact payment coin + chain.
ugf_smart_quoteAuto-discover the cheapest viable route across the agent's balances.

Pay (self-custody — no signer required)

ToolPurpose
ugf_x402_build_typed_dataReturn ERC-3009 typed-data for x402 payment. Agent signs locally.
ugf_x402_submit_signedSubmit the agent-produced x402 signature.
ugf_vault_build_txReturn unsigned EIP-1559 vault payment tx. Agent signs + broadcasts locally.
ugf_vault_submit_signedSubmit the on-chain vault tx hash after the agent broadcasts.

Execute — EVM destination

ToolPurpose
ugf_evm_wait_sponsorshipWait until UGF has sponsored the destination side.
ugf_evm_confirm_user_txConfirm the agent-broadcast destination tx hash back to UGF.

Execute — Solana destination

ToolPurpose
ugf_sol_wait_user_sig_messageWait for UGF's prepared Solana message bytes.
ugf_sol_submit_user_sigSubmit the agent-produced ed25519 user signature.

Execute — Sui destination

ToolPurpose
ugf_sui_wait_sponsor_bytesWait until UGF returns tx_bytes + sponsor_sig.
ugf_sui_execute_signed_blockBroadcast the dual-signed (user + sponsor) Sui block via Sui RPC.

Status

ToolPurpose
ugf_check_statusSingle-shot status check for a route digest.
ugf_poll_statusPoll until the route reaches a terminal state.

Environment variables

All optional. Public RPCs are used when not set.

VarDefaultPurpose
RPC_ETHhttps://eth.llamarpc.comEthereum mainnet
RPC_OPhttps://mainnet.optimism.ioOptimism
RPC_BNBhttps://bsc-dataseed.binance.orgBNB chain
RPC_POLYGONhttps://polygon-rpc.comPolygon
RPC_OPBNBhttps://opbnb-mainnet-rpc.bnbchain.orgopBNB
RPC_ARBhttps://arb1.arbitrum.io/rpcArbitrum
RPC_AVAXhttps://api.avax.network/ext/bc/C/rpcAvalanche C-chain
RPC_BASEhttps://mainnet.base.orgBase
SUI_RPC_URLhttps://fullnode.mainnet.sui.io:443Sui 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

LayerWhat's hereWhat's NOT here
MCP sourcereads + RPC calls + UGF SDK glueno key material, no ethers.Wallet, no Keypair.fromSecretKey, no mnemonic, no password
Wire protocolJSON-RPC over stdiono remote network listener — the host process pipes stdin/stdout
External callsUGF gateway + public RPCsno 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

symptomlikely causefix
Provider did not return EIP-1559 fee dataPayment 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 disabledBNB / opBNB blocked client-side for the same reason.Same workaround as above.
Authentication required from gatewayMissing JWT.Call ugf_get_nonce → sign locally → ugf_authenticate. Cache the returned JWT.
got 0 after a vault broadcastGateway 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 chainThe 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 toolsnpx 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

Ver o original no GitHub

Bom para

Relacionados