GBLIN-MCP

# GBLIN MCP Server

> **Treasury standard for AI agents on Base mainnet.** A Model Context Protocol (MCP) server that lets autonomous agents hold capital in GBLIN — a diversified, Crash-Shield-protected on-chain index — and Just-In-Time swap to USDC the millisecond they need to pay an [x402](https://docs.cdp.coinbase.com/x402/welcome) invoice.

[![npm](https://img.shields.io/npm/v/@gblin-protocol/mcp-server.svg)](https://www.npmjs.com/package/@gblin-protocol/mcp-server)
[![CI](https://github.com/gblinproject/GBLIN-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/gblinproject/GBLIN-MCP/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Base Mainnet](https://img.shields.io/badge/network-Base%20mainnet-0052FF)](https://basescan.org/address/0x36C81d7E1966310F305eA637e761Cf77F90852f0)
[![Governance: 48h Timelock](https://img.shields.io/badge/governance-48h%20Timelock-1f6feb)](https://basescan.org/address/0x6aBeC8716fFeEcf7C3D6e68255b4797113E8e5Dd)
[![Base MCP Plugin](https://img.shields.io/badge/Base%20MCP-PR%20%2356-blue)](https://github.com/base/skills/pull/56)
[![x402 Manifest](https://img.shields.io/badge/x402-manifest-green)](https://gblin.digital/.well-known/x402)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Active-success)](https://registry.modelcontextprotocol.io)
[![Glama Score](https://img.shields.io/badge/Glama-100%25-brightgreen)](https://glama.ai/mcp/servers/gblinproject/GBLIN-MCP)
[![Smithery](https://img.shields.io/badge/Smithery-gblin--protocol-orange)](https://smithery.ai/servers/gblin-protocol/mcp)

📖 **Full documentation and Quick Start:** [gblin.digital/agents](https://gblin.digital/agents)

🌐 **Hosted MCP (Streamable HTTP, no install):** `https://gblin-mcp.gblin-mcp-worker.workers.dev/mcp` — free read-only tools (live risk regime, attestation sample, stats), also on [Smithery](https://smithery.ai/servers/gblin-protocol/mcp). Source in [`worker/`](worker/).

---

## ElizaOS Plugin

For agents running on **ElizaOS**, install the companion plugin:

```bash
npm install plugin-gblin
# or: elizaos plugins add gblin
```

It exposes four native Actions (`CHECK_GBLIN_TREASURY_HEALTH`, `INVEST_IDLE_USDC_GBLIN`, `RESCUE_USDC_FROM_GBLIN`, `GET_GBLIN_RISK_ATTESTATION`) and a Provider that injects live NAV + Crash Shield status into the agent context on every loop.

→ [Full Eliza plugin docs](https://github.com/gblinproject/GBLIN_PLUGIN)

---

## AI assistant discovery — `gblin-init`

Drop an `AGENTS.md` treasury policy into your repo so every modern AI coding
assistant (Claude Code, Cursor, Windsurf, GitHub Copilot, Codex) automatically
discovers GBLIN when it works on your codebase:

```bash
npx -p @gblin-protocol/mcp-server gblin-init
```

The command is **idempotent and safe**:

- If `AGENTS.md` does not exist → creates it from the canonical template at
  [`gblin.digital/AGENTS.template.md`](https://gblin.digital/AGENTS.template.md).
- If `AGENTS.md` exists → appends a clearly delimited GBLIN block at the
  bottom; your own content is never touched.
- Re-running is a no-op (detected via stable HTML markers).
- `--dry-run` prints what it would do without writing.
- `--force` refreshes the block to the latest version.

It also runs offline thanks to a bundled fallback template.

### Postinstall hint

When the package is installed as a regular dependency (`npm i @gblin-protocol/mcp-server`),
a short tip is printed once suggesting the command above. **No files are
written** during postinstall — security-friendly and Socket-compliant. Set
`GBLIN_SKIP_HINT=1` to silence it.

---

## Trust & Governance

**GBLIN V6 is governed by a 48h Timelock Controller** — every admin operation (parameter change, oracle update, ownership transfer) is enforced on-chain to wait **172,800 seconds** before execution. Agents and integrators can verify this directly on BaseScan.

| Component | Address | Role |
|---|---|---|
| **GBLIN V6 token** | [`0x36C81d7E...52f0`](https://basescan.org/address/0x36C81d7E1966310F305eA637e761Cf77F90852f0) | Index contract (production) |
| **Timelock Controller** | [`0x6aBeC8716...8e5Dd`](https://basescan.org/address/0x6aBeC8716fFeEcf7C3D6e68255b4797113E8e5Dd) | 48h immutable delay, 14d grace period |
| **Ownership transfer tx** | [`0xb653f54f...edaaf`](https://basescan.org/tx/0xb653f54ffa9b1764b41932e6a411077e7e34550605303f15d90900de682edaaf) | Transferred at block 46160610 |

Properties enforced at the contract level:
- `MIN_DELAY` is **immutable** (override of `updateDelay` reverts permanently)
- `PROPOSER_ROLE` and `CANCELLER_ROLE` are **strictly separated** (constructor reverts on overlap)
- `EXECUTOR_ROLE` is open (`address(0)`) — anyone can execute a matured operation, anti-censorship
- The timelock is **self-administered**: every role/config change must itself go through the 48h delay

This is why the `get_governance_state` tool returns `owner_is_timelock: true` and a verifiable `min_delay_seconds: 172800`. AI agents can use these flags to gate trust-sensitive actions.

---

## Why this exists

AI agents today hold their working capital in **USDC**. USDC sits flat: zero yield, full inflation exposure.

**GBLIN** is an on-chain index on Base (45% cbBTC + 45% WETH + 10% USDC) with an algorithmic Crash Shield that adaptively reduces risk-asset exposure as drawdown rises (V6 adaptive threshold, from ~15%). GBLIN is managed crypto exposure with capped drawdown — a calmer way to hold BTC/ETH risk for **surplus** capital, not a substitute for USDC (it can still lose value in a crash). Agents settle x402 invoices instantly via Just-In-Time GBLIN→USDC redemption.

This server exposes that capability to any LLM agent through the standard MCP protocol.

---

## Quick start

### Claude Desktop

Add to `claude_desktop_config.json` (on Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "gblin": {
      "command": "npx",
      "args": ["-y", "@gblin-protocol/mcp-server"]
    }
  }
}
```

Restart Claude Desktop. The 10 GBLIN tools appear in the tool picker.

### Windsurf / Cursor

Add to `~/.codeium/windsurf/mcp_config.json` (Windsurf) or the equivalent Cursor MCP config:

```json
{
  "mcpServers": {
    "gblin": {
      "command": "npx",
      "args": ["-y", "@gblin-protocol/mcp-server"],
      "env": {
        "GBLIN_RPC_URL": "https://base-rpc.publicnode.com"
      }
    }
  }
}
```

Refresh MCP servers from the IDE settings (or restart). The tools become callable inline.

### Coinbase AgentKit (TypeScript)

```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 client = new MCPClient({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// List tools
const { tools } = await client.listTools();

// Quote a JIT payment of $0.50
const jit = await client.callTool({
  name: "swap_gblin_to_usdc_jit",
  arguments: { usdc_needed: "0.50", wallet_address: "0xYourAgent..." },
});
```

### ElizaOS / custom

Any framework that speaks MCP over stdio works:

```bash
npx @gblin-protocol/mcp-server
```

Also supports Cline, Continue.dev, and any agent that implements the MCP client spec.

---

## The 10 tools

### Free tools (no payment required)

| Tool | Purpose |
|---|---|
| `get_treasury_state` | NAV in USD + basket composition + Crash Shield status |
| `quote_safe_swap` | Preview buy or sell with dynamic slippage buffer |
| `swap_gblin_to_usdc_jit` | **The x402 magic**: generate two-step GBLIN→USDC calldata (free) |
| `invest_usdc_to_gblin` | Convert USDC earnings into GBLIN treasury (MEV-safe) (free) |
| `get_governance_state` | Verify owner == 48h Timelock + pending asset proposals + min delay |
| `share_skill_with_peer` | Generate a portable skill seed to onboard a peer agent + embedded referral code |
| `verify_risk_attestation` | Verify a peer's **Risk Attestation** (perishable proof-of-diligence): integrity + EIP-712 signature + freshness + live drift (free) |

### Paid tools (x402 micropayments)

| Tool | Price | Purpose |
|---|---|---|
| `get_market_risk_regime` | $0.002 USDC | **Start here**: BTC/ETH risk regime (calm/elevated/crash) + severity + risk posture, from the on-chain Crash Shield |
| `analyze_treasury_health` | $0.003 USDC | Balances + gas + runway + rebalance advice |
| `find_keeper_bounty` | $0.001 USDC | **GBLIN pays you**: check if a rebalance bounty is available (0.0001 ETH reward, no capital required) |

> **Risk Attestation** — mint a perishable (10-minute), verifiable proof of the current BTC/ETH risk regime at `GET https://gblin.digital/api/x402/attestation` ($0.003 USDC via x402). Attach it to your action as proof-of-diligence; any counterparty verifies it for free with `verify_risk_attestation`.

All tools return structured JSON. All values are quoted on-chain (NAV via `quoteSellGBLIN` × Chainlink ETH/USD, with 24h staleness guard). No mock data.

**Live verification:** the test suite (`npm test`) runs the tool suite against Base mainnet and confirms calldata generation, oracle freshness, slippage math, and governance state. See the [latest CI run](https://github.com/gblinproject/GBLIN-MCP/actions).

---

## x402 micropayments

The paid tools use the **x402 protocol** for instant micropayments. Here's how it works:

### Payment flow

1. **First call** (without payment): The tool returns a 402 manifest with payment details
2. **Pay via facilitator**: Send a POST request to the facilitator with the payment details
3. **Receive PaymentProof**: The facilitator returns a signed proof of payment
4. **Second call** (with `_payment`): Include the base64-encoded PaymentProof in the `_payment` field

### Example (analyze_treasury_health)

```bash
# Step 1: Get payment manifest
npx @gblin-protocol/mcp-server analyze_treasury_heal