Reference Implementation: GBLIN On-chain Treasury for AgentKit MCP Extensions

### Language Implementation

- [ ] Python
- [x] TypeScript

### Feature Type

- [ ] Action Provider Template
- [ ] Wallet Provider Template
- [x] Framework Extension
- [ ] Core Requirements
- [ ] Other

### 🚀 The feature, motivation and pitch

## Context

Following the release of `@coinbase/agentkit-model-context-protocol`, AgentKit can now natively consume any MCP server. We've shipped a production-ready MCP server purpose-built for AgentKit-controlled wallets that need to manage treasury and pay x402 invoices on Base mainnet.

## What GBLIN MCP gives AgentKit developers

The server exposes 6 tools, all read-only or calldata-only (the agent's wallet is always the sole signer):

| Tool | Purpose |
|---|---|
| `get_treasury_state` | NAV in USD + basket composition + Crash Shield status |
| `quote_safe_swap` | Preview buy/sell with dynamic slippage buffer |
| `swap_gblin_to_usdc_jit` | **JIT atomic GBLIN→USDC calldata for x402 invoices** |
| `invest_usdc_to_gblin` | Convert USDC earnings into GBLIN treasury (MEV-safe minOut) |
| `analyze_treasury_health` | Balances + gas runway + rebalance recommendation |
| `get_governance_state` | Verify owner == 48h Timelock + pending ops (trust gating) |

## Integration is one config block

```ts
import { MCPClient } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
command: "npx",
args: ["-y", "@gblin-protocol/mcp-server"],
});
const gblinClient = new MCPClient({ name: "agentkit-agent", version: "1.0.0" });
await gblinClient.connect(transport);

// All 6 GBLIN tools now sit alongside AgentKit's native wallet tools
const { tools } = await gblinClient.listTools();

// JIT a $0.50 USDC payment for an x402 invoice in a single atomic tx
const jit = await gblinClient.callTool({
name: "swap_gblin_to_usdc_jit",
arguments: { usdc_needed: "0.50", wallet_address: agentKitWallet.address },
});
// → returns ready-to-broadcast calldata for AgentKit's wallet provider
```

## Why this matters for AgentKit users

1. **Real-time NAV** via Chainlink ETH/USD with 24h staleness guard — agents validate treasury backing before any swap.
2. **Atomic single-tx JIT swaps** via the contract's native `sellGBLINForToken` — no batched UserOps, works on EOAs, ERC-4337 smart accounts, and EIP-7702 delegated EOAs (compatible with every AgentKit wallet provider).
3. **Crash Shield monitoring** — agents can detect when the basket auto-rebalances toward USDC and adjust strategy.
4. **Verifiable governance** — `get_governance_state` returns `owner_is_timelock: true` so agents can gate trust-sensitive actions on whether admin is fully delay-enforced (48h).

## Pitch

We're submitting GBLIN MCP as a **reference implementation** for the AgentKit MCP extension ecosystem — useful as:
- A documentation example for "compose any MCP server with AgentKit"
- An entry in the AgentKit ecosystem / awesome-list of compatible MCP tools
- A real-world DeFi use case for the `@coinbase/agentkit-model-context-protocol` package

Happy to open a docs PR if helpful.

### Alternatives

We considered:

1. **Action Provider** inside AgentKit — would require Coinbase to maintain DeFi-specific code; MCP server keeps the surface decoupled and reusable across Claude Desktop, Cursor, Windsurf, Eliza, and other MCP clients.
2. **Direct Uniswap V3 calls** from the agent — exposes the agent to MEV (no enforced minOut) and requires hardcoding pool fees / paths. GBLIN's native `sellGBLINForToken` is atomic and slippage-protected on-chain.
3. **USDC-only treasury** — flat zero-yield exposure; the whole point of GBLIN is to keep agent capital diversified (cbBTC + ETH + USDC) while preserving instant x402-payment capability via JIT swaps.

### Additional context

## Links

- **MCP Registry URI**: `io.github.gblinproject/gblin-mcp-server`
- **MCP Registry listing**: https://registry.modelcontextprotocol.io/v0/servers?search=gblin
- **NPM package**: https://www.npmjs.com/package/@gblin-protocol/mcp-server
- **Repository**: https://github.com/gblinproject/GBLIN-MCP
- **GBLIN_V5 contract** (Base mainnet): [`0x38DcDB3A381677239BBc652aed9811F2f8496345`](https://basescan.org/address/0x38DcDB3A381677239BBc652aed9811F2f8496345)
- **48h Timelock owner**: [`0x6aBeC8716fFeEcf7C3D6e68255b4797113E8e5Dd`](https://basescan.org/address/0x6aBeC8716fFeEcf7C3D6e68255b4797113E8e5Dd)

## Trust & verification

- All 6 tools are **read-only or calldata-only** — the MCP server never holds keys, never signs, never broadcasts. AgentKit's wallet provider remains the sole signer.
- Calldata returned by `swap_gblin_to_usdc_jit` and `invest_usdc_to_gblin` includes **non-zero `minOut` values computed from on-chain quotes + dynamic slippage** (2.5% normal / 4% during Crash Shield) — no sandwich-attack surface.
- GBLIN_V5 admin is enforced by a **48-hour OpenZeppelin TimelockController** with immutable `MIN_DELAY`. Verifiable on-chain via `get_governance_state`.

## Use case examples

- An agent earns $5 in USDC via x402-paid API calls → calls `invest_usdc_to_gblin` to roll earnings into the diversified index.
- An agent needs to pay a $0.50 x402 invoice but holds 95% in GBLIN → calls `swap_gblin_to_usdc_jit` to atomically free exactly the USDC required, paid in the same block.
- Before any treasury action, the agent calls `get_governance_state` and gates execution on `owner_is_timelock: true`.