monad-mcp

MCP server for the Monad blockchain. Your agent's gateway to balances, transfers, swaps, and DeFi on Monad — with signing handled by a Privy embedded wallet, never by the agent.

Built around a simple shape — stored requests + approval URLs + skill plugins — on Monad mainnet 143 / testnet 10143, with Privy as the wallet provider.

🌐 Landing page + live read-only demo: pareen.github.io/monad-mcp — query real Monad balances in your browser, exactly what the agent sees.

🔌 Connect it — no install, no terminal. In Claude Desktop or ChatGPT, add a custom connector and paste this URL:

https://monad-mcp.fly.dev/mcp

That's the whole setup — read tools (balances, prices, portfolios, token checks) work immediately. Step-by-step for each app: docs/connect-claude.md.

Prefer the terminal? One line in Claude Code:

claude mcp add --transport http monad https://monad-mcp.fly.dev/mcp   # hosted
claude mcp add monad -- npx -y monad-mcp                              # or run it locally

The hosted endpoint runs in split mode: read tools are public (paste the URL, no login — safe to share) and write tools are gated behind a Privy sign-in, returning auth_required until you authenticate. The hosted sign-in path is wired but still being verified end-to-end, so the tested route for transactions is your own Privy-signed instance — see docs/connect-claude.md, docs/FAQ.md for common security/setup questions, and docs/DEPLOY.md.

🧭 Monad ≠ Ethereum: the server ships agent-facing guidance on Monad's quirks (128 KB contracts, gas_limit billing, speculative latest, eth_getLogs caps, FastLane/MEV) as monad://guide/* MCP resources — see docs/building-on-monad.md.

What's in the box

Core tools (work on any address; auth required only where noted):

| Tool | Auth | What it does | |------|------|--------------| | create_user | none | Provision a Privy user + Monad-ready embedded wallet. Self-serve onboarding. | | whoami | required | User id, wallet address, and active session-key grants. | | get_address | required | Returns the connected wallet's address. | | get_balance | optional | Native MON balance. Accepts a 0x address or a .nad name. | | get_token_balance | optional | ERC-20 balance with decimals + symbol. Accepts a .nad name. | | get_portfolio | optional | All canonical token balances × USD prices via DexScreener. Accepts a .nad name. | | get_transaction_history | optional | Recent ERC-20 transfers via RPC log scan + explorer URL. Accepts a .nad name. | | get_tx_receipt | none | Receipt for a tx hash. | | simulate_transaction | optional | Dry-run a call (eth_call), returns return data or revert reason. | | check_token | none | Risk heuristics: canonical-list membership, bytecode, DEX liquidity, pair age. | | resolve_token | none | Symbol/name/alias → token address (canonical list + DexScreener fallback). | | get_token_price | none | USD price from the deepest-liquidity DexScreener pair on Monad. | | list_canonical_tokens | none | Built-in list of well-known Monad tokens. | | resolve_name | none | Nad Name Service (nad.domains): .nad name → address, and address → primary .nad name. | | read_contract | none | Call any view/pure function on any Monad contract (ABI provided inline). | | decode_return_data | none | Decode hex return data against an ABI. | | bridge_quote | optional | LiFi aggregator quote from any chain into Monad. | | poll_request | none | Status of a pending approval request. | | transfer | required | Native MON or ERC-20 transfer. Recipient may be a 0x address or a .nad name. Auto-executes under a session grant, else → approval URL. | | write_contract | required | Send a tx to any contract (any non-view function). | | pay_for_service | required | x402 (HTTP 402) — signs an EIP-3009 USDC authorization via Privy and retries with X-PAYMENT. | | bridge_execute | required | Submit the source-chain tx returned by bridge_quote (Monad sources only). | | grant_session_key | required | Authorize the agent to spend up to N MON without per-tx approvals. | | list_session_keys | required | Show active + recent grants. | | revoke_session_key | required | Cancel a grant immediately. |

Skill plugins (additive, drop in your own under src/plugins/):

• Uniswap (uniswap_quote, uniswap_swap, approve_erc20) — exact-input single-hop swaps on Uniswap v3 (testnet + mainnet).
• Kintsu (kintsu_stake, kintsu_request_unstake, kintsu_claim_unstake, kintsu_position) — liquid staking MON → sMON via Kintsu's ERC-7535 vault. Two-step unstake with batch processing.
• FastLane (fastlane_stake, fastlane_unstake, fastlane_position) — liquid staking MON → shMON via FastLane's shMONAD ERC-4626 vault. Payable native deposit, synchronous redeem (no epoch wait); shMON keeps earning staking + MEV rewards.
• Morpho (morpho_supply, morpho_withdraw, morpho_borrow, morpho_repay, morpho_position, morpho_market) — lending on Morpho Blue's singleton. Caller passes MarketParams inline; plugin derives the market id.
• Kuru (kuru_best_bid_ask, kuru_market_params, kuru_place_limit, kuru_cancel_orders, kuru_market_swap) — fully-on-chain CLOB. Ships with known mainnet markets (MON/USDC, MON/AUSD, WETH/USDC); accepts raw addresses for new ones.

All write tools across plugins auto-route through a covering session-key grant (see "Session keys" below); otherwise they return an approval URL.

Mainnet-only plugins (Kintsu / FastLane / Morpho / Kuru) are skipped at boot when MONAD_DEFAULT_NETWORK=testnet. Override per-tool with network: "mainnet".

Quickstart

1. Install + configure

git clone https://github.com/you/monad-mcp.git
cd monad-mcp
npm install
cp .env.example .env

Edit .env. Minimum config to do anything useful with write tools:

PRIVY_APP_ID=clxxxxxxxxxxx          # from https://dashboard.privy.io
PRIVY_APP_SECRET=...                # from the same place
PRIVY_VERIFICATION_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"  # optional but recommended

# Where this server is reachable from a browser (used in approval URLs).
PUBLIC_BASE_URL=http://localhost:8787
PORT=8787

# Which Monad network to default to when a tool call omits `network`.
MONAD_DEFAULT_NETWORK=testnet

For the Uniswap plugin, supply contract addresses (verify against the canonical Uniswap deployment for Monad before using):

UNISWAP_MAINNET_QUOTER_V2=0x...
UNISWAP_MAINNET_SWAP_ROUTER_02=0x...
UNISWAP_TESTNET_QUOTER_V2=0x...
UNISWAP_TESTNET_SWAP_ROUTER_02=0x...

2. Privy app setup

In the Privy dashboard:

1. Create an app. Enable embedded wallets under "Wallets".
2. Under "Networks", add Monad mainnet (chainId 143) and/or testnet (chainId 10143) as an EVM chain.
3. Copy the App ID + App Secret into .env.
4. Copy the JWT verification key (PEM-encoded ES256 public key) into PRIVY_VERIFICATION_KEY for fastest token verification. If omitted, the server falls back to JWKS over the network.
5. (Optional) Configure wallet policies (spend limits, allowlists) to gate what the agent can do.

2a. Bootstrap server-side wallet authorization (one-time)

Privy embedded wallets are user-owned by default — the server cannot sign for them. The MCP server needs a P-256 key quorum registered with Privy, attached as an additional_signer on every wallet it provisions. Bootstrap it:

npm run bootstrap:auth-key
# Generates a P-256 keypair, registers it as a Privy key quorum, prints two env vars.
# Paste PRIVY_AUTHORIZATION_PRIVATE_KEY and PRIVY_KEY_QUORUM_ID into .env.

After bootstrap, every create_user call attaches the quorum at wallet creation, and every transfer/swap includes the private key in authorization_context. Important: wallets minted before you set these env vars are stranded — Privy doesn't let you retrofit an additional_signer (updating authorization requires existing authorization). Always bootstrap first.

3. Run

# Stdio mode for Claude Desktop, Cursor, etc.
npm run build
npm start

# HTTP / Streamable HTTP mode for remote MCP clients (Claude Web, ChatGPT).
npm run start:http
# Server listens on http://localhost:8787/mcp

4. Wire it into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json. The --env-file flag loads PRIVY_*, MONAD_*, and PUBLIC_BASE_URL from your .env into the spawned process:

{
  "mcpServers": {
    "monad": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/monad-mcp/.env",
        "/absolute/path/to/monad-mcp/dist/index.js"
      ]
    }
  }
}

You'll also need the HTTP server running (npm run start:http) for the approval flow — the stdio MCP returns approval URLs that point at the HTTP server. See docs/claude-desktop.md for the full dogfood walkthrough (bootstrap, funding, first transfer).

Public reads, no self-hosting: to use the read tools (balances, portfolio, history) without building anything, point Claude Desktop at the hosted endpoint via the mcp-remote shim — "args": ["-y", "mcp-remote", "https://monad-mcp.fly.dev/mcp"]. Writes (transfers/swaps) are gated behind a Privy sign-in; the verified path for them is a self-hosted signer.

5. Try a prompt

What's the balance of 0x000…0000 on Monad testnet?
Send 0.01 MON to 0xabc… on Monad testnet.

For the second prompt the agent calls transfer, hands you a link like http://localhost:8787/approve/<uuid>, and you approve in your browser. The agent polls poll_request and reports the tx hash.

Architecture

agent (Claude / ChatGPT / Cursor)
   │
   │  MCP over stdio OR Streamable HTTP (with OAuth 2.1 bearer)
   ▼
monad-mcp server
   │
   ├── core tools           viem → Monad RPC (mainnet 143 / testnet 10143)
   ├── skill plugins        Uniswap / Kuru / Kintsu / Morpho (additive)
   │
   ├── auth bridge          Privy server SDK (verify access token, resolve embedded wallet)
   │
   └── stored requests      pending tx ↔ approval URL ↔ user signature
                            ▲
                            │
                            └── /approve/:id  →  Privy hosted signing  →  tx hash

Write tools follow the stored request pattern:

1. Tool builds an unsigned { to, value, data } payload and a human-readable summary.
2. Server stores it under a UUID and returns https://your-server/approve/<uuid> to the agent.
3. User opens the URL — page shows the summary + asset diff + signs via their Privy embedded wallet.
4. Server records the tx hash; agent polls poll_request and continues.

The agent never touches a private key. Privy's TEE-backed key custody + wallet policies are the security envelope.

Adding your own skill plugin

Plugins live in src/plugins/<id>/ and export a SkillPlugin:

import type { SkillPlugin } from "../types.js";
import { registerTool } from "../../tools/registry.js";

export const myPlugin: SkillPlugin = {
  id: "myproto",
  name: "MyProto on Monad",
  description: "What it does in one sentence.",
  networks: ["mainnet", "testnet"],
  register(mcp, server) {
    registerTool(mcp, server, myReadTool);
    registerTool(mcp, server, myWriteTool);
  },
};

Register it in src/plugins/index.ts. Write tools just need to construct a { to, value, data } payload and call server.store.create(...) — the approval flow is shared.

Testing

npm test                # vitest unit tests (no network) — 56 tests
npm run test:integration  # integration tests against live testnet RPC + Privy
npm run typecheck
npm run lint

56 unit tests cover the chain config, both stores (requests + grants), tool registry (auth gating, schema validation), every core tool, every session-key surface, and the Uniswap plugin's quote sweep.

The integration suite runs transfer end-to-end on Monad testnet through the Privy server SDK: build → sign → broadcast → poll receipt. Gated on PRIVY_APP_ID, PRIVY_APP_SECRET, PRIVY_AUTHORIZATION_PRIVATE_KEY, PRIVY_KEY_QUORUM_ID, and MONAD_MCP_E2E_USER_ID being set + the wallet being funded; cleanly skips otherwise so it doesn't break CI without secrets.

Security model

• Keys: Privy holds the key in a TEE. The MCP server never sees a private key.
• Authorization to act: every write tool builds a stored request; nothing happens until the user clicks Approve on the approval page.
• Token scope: the OAuth 2.1 bearer in the MCP transport identifies which user; it does not authorize which tx — that's gated by the explicit approval click + Privy wallet policies.
• Stale link defense: stored requests expire after ttl_seconds (default 5 min); expired requests can't be approved.
• CSRF on /reject: rejection is intentionally permissionless — worst case, a stale link can't be re-used. Approval requires a Bearer token tied to the requesting user.

For production, the stored-request and grant stores already support a Postgres backend (set STORE_BACKEND=postgres); still on the hardening list are rate limiting on /approve and /submit, and per-tool spend caps via Privy policies.

Session keys: skipping per-tx approvals

By default every write tool returns an approval URL the user has to click. That's fine for one-shot prompts, fatal for anything agentic ("DCA $100 into MON every Friday", "rebalance my LP weekly"). The fix is grant_session_key:

> Grant the agent up to 0.5 MON for the next 24h to send to 0xabc…

agent calls grant_session_key({
  spend_cap_mon: "0.5",
  ttl_seconds: 86400,
  allowed_targets: ["0xabc..."],
})
→ returns an approval URL. User clicks once.

> Now send 0.01 MON to 0xabc…

agent calls transfer({ to: "0xabc...", amount: "0.01" })
→ no approval URL. Tool returns the tx hash immediately,
  grant remaining: 0.49 MON.

Grants are scoped by:

• spend_cap_mon — total native MON the agent can spend (running total tracked across calls)
• ttl_seconds — grant expiry window (max 30 days)
• allowed_targets — optional recipient/contract allowlist (empty = any)
• allowed_selectors — optional 4-byte function selector allowlist (e.g. 0xa9059cbb = ERC-20 transfer only)

Coverage is checked against every write call; if the grant doesn't cover (wrong target, wrong selector, would exceed cap), the tool falls back to the approval-URL flow. Revoke any time with revoke_session_key.

Limits: v1 tracks native-MON spend cap only. ERC-20 token amounts aren't deducted from the cap — instead, restrict ERC-20 access by listing the token contract in allowed_targets. Per-token spend caps are a v2 add.

End-to-end testing on Monad testnet

# 1. Provision a test user + embedded wallet (one-time, costs a Privy seat).
npm run e2e:create-user
# Prints: user_id, wallet_address, faucet URL. Save user_id to .env.

# 2. Fund the printed wallet at https://testnet.monad.xyz/

# 3. Run the round-trip transfer test.
npm run e2e:transfer
# Builds a transfer through runTool, signs+broadcasts via Privy, waits for receipt.

# 4. Sanity-check Privy creds reach the API.
npm run verify:privy

The e2e script reuses MONAD_MCP_E2E_USER_ID from env so you don't burn a new Privy seat on each run.

What's next

• Browser-first signing path (Privy web SDK in the approval page → no server-side sendTransaction round-trip).
• More plugins — Neverland lending (Aave V3 fork on Monad), additional DEXes/perps.
• Block-explorer integration once Monad's explorer API stabilizes (get_transaction_history will return full decoded history).
• x402 payment support (pay for x402-enabled services).
• Per-token (ERC-20) spend caps on session grants — today's cap is a single native-MON budget per grant.
• Universal contract reader/writer for "talk to any Monad contract" without writing a per-protocol plugin.

License

MIT — see LICENSE.