# Universal Gas Framework MCP Server

[![npm](https://img.shields.io/npm/v/@tychilabs/ugf-mcp?label=npm)](https://www.npmjs.com/package/@tychilabs/ugf-mcp)
[![license](https://img.shields.io/npm/l/@tychilabs/ugf-mcp)](./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](https://universalgasframework.com). This README only covers the MCP server.

---

## Install

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

```bash
npx -y @tychilabs/ugf-mcp@beta
```

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

```bash
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):

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

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

### Claude Code

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

### Codex CLI

`~/.config/codex/config.json`:

```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:

```json
{
  "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

```bash
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](./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