Monad MCP

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

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/ , 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/ 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/ / 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 # int