@getplexa/mcp — Plexa MCP server

A Model Context Protocol server that gives any MCP client (Claude Desktop, Cursor, your own agent) two economic-safety tools from Plexa — the x402-native economic-safety layer for trading agents — paid per call in USDC, no accounts:

It is a thin client of the public API (https://api.getplexa.com) — it pays a 402 automatically, signs the USDC authorization locally with your wallet, and never sees your key. The liquidity engine stays behind the API.

Why

A generic wallet guard answers "can I sign this transaction?". It can't answer the economic question an automated trader actually needs: what price will this swap really fill at under my size, and is this token a trap (rug / honeypot / thin liquidity)? Plexa answers both. This package puts those answers one tool-call away inside any MCP-speaking agent.

Install

Nothing to install — point your MCP client at the package via npx. It is fetched and run on demand.

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "plexa": {
      "command": "npx",
      "args": ["-y", "@getplexa/mcp"],
      "env": {
        "PLEXA_BASE_URL": "https://api.getplexa.com",
        "AGENT_WALLET_KEY": "0x<your funded wallet private key>",
        "CHAIN": "base"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or Settings → MCP → Add) — the same mcpServers block as above.

Restart the client. You should see the plexa_quote and plexa_pretrade_check tools available.

Configuration

All configuration is via environment variables (set in the env block of your MCP config):

Funding. Use a dedicated, low-balance wallet with a little USDC on CHAIN to pay per call (quotes $0.02, checks $0.05). The wallet signs an EIP-3009 USDC authorization per request; Plexa returns the result only after the payment settles on-chain (settle-before-serve).

Your key is a secret. Prefer your MCP client's secret storage if it has one. Never commit it.

How payment works (x402 in MCP)

MCP has no native payment. This server acts as an x402 client: it wraps fetch, so when Plexa replies 402 Payment Required it reads the payment requirements, signs a USDC authorization with your wallet (locally), and retries. The signed authorization is the only thing that leaves your machine — never the key. Payment is made on CHAIN, so you fund one wallet on one chain.

If no AGENT_WALLET_KEY is set, the tools return an honest 402 error explaining a funded wallet is needed — they never fabricate a result.

Example

Once configured, just ask your agent naturally — it will call the tools:

"Before I buy this token 0x… on Base, check it with Plexa and get me an executable quote for $500."

The agent calls plexa_pretrade_check (verdict + reasons) and plexa_quote (executable price under $500), pays $0.05 + $0.02 in USDC automatically, and answers with real on-chain economics.

What comes back

Beyond verdict / triggers / risk_profile / liquidityCoverage, every pre-trade response carries six blocks of context. Live capture, WETH, 2026-08-20T14:46:29Z, Base block 50223921 — the note string each block carries is long and is cut here, nothing else is:

{
 "identity": {
  "name": "Wrapped Ether",
  "symbol": "WETH",
  "decimals": 18,
  "totalSupplyRaw": "239296586519181917702210",
  "totalSupply": 239296.58651918193
 },
 "valuation": {
  "fdvExecutableUsd": 543916397.6557496,
  "basis": "totalSupply(this chain) x executablePrice(at sizeUSD)"
 },
 "ownership": {
  "ownerAddress": null,
  "ownerRenounced": null,
  "isMintable": false,
  "creatorAddress": "0xe8a3ecea7d6a688ee903173024225357ddf29e93",
  "creatorBalance": 0.000289172466091074,
  "creatorSharePct": 1.208427041511075e-07
 },
 "dormancy": {
  "topHolderIdleDays": null,
  "lastTopHolderMoveBlock": null,
  "headBlock": null
 },
 "market": {
  "priceUsdSpot": 2277.76,
  "volume24hUsd": 551324354.8699999,
  "marketCapUsd": 542587444,
  "holderCount": 5223863
 },
 "sources": {
  "*": "measured",
  "risk_profile.concentration": "unavailable:holder-axis-produced-nothing",
  "flags.F_CONC": "unavailable:holder-axis-produced-nothing",
  "valuation": "derived:identity.totalSupply*quote.executablePrice",
  "dormancy": "unavailable:holder-axis-produced-no-block",
  "ownership.creatorAddress": "derived:sender-of-first-transfer",
  "ownership.isMintable": "derived:mint-selector-in-bytecode",
  "market": "vendor:dexscreener+goplus",
  "market.priceUsdSpot": "vendor:dexscreener",
  "market.volume24hUsd": "vendor:dexscreener",
  "market.marketCapUsd": "vendor:dexscreener",
  "market.holderCount": "vendor:goplus"
 }
}

🔴 sources is the map of who said what. measured — ours, read off the chain on this call. derived:<formula> — ours, computed from other fields of this same response. vendor:<name> — somebody else's number, republished and signed as theirs. unavailable:<reason> — no value, and the reason why. That last one is the point: a missing number that names its own gap cannot be mistaken for a clean result.

Two numbers that look like duplicates and are not: valuation.fdvExecutableUsd is THIS chain's supply at the price your size executes at; market.marketCapUsd is the vendor's global figure. For a bridged token ours is legitimately smaller.

What changed in 0.2.0

A field changed MEANING, not shape. risk_profile.liquidity.exitLiquidityUsd used to be the counter asset sitting in the direct pools. Since 2026-09-20 it is what selling the position returns: the server quotes the sale of the very position the answer prices and reports the proceeds of the best road (never a sum of roads).

Where the previous number lives: liquidityCoverage.exitPoolInventoryUsd — same figure as before, under its own name. liquidityCoverage.exitPotBasis tells you which kind of number the head figure is: position-sale (measured proceeds), second-hop (a counter-asset road) or pool-inventory (the sale could not be quoted this call, so it fell back to the pre-20.09 meaning).

Why it matters: measured on SOGNI, 2026-09-20 — inventory $113,968 against a sale that returns $4,571 for a $5,000 position. A client comparing the OLD pot with its own size overstated the exit by 8.6% of that size. If your code does min(exitLiquidityUsd, size), it now gets the honest number; if you relied on the old semantics, read exitPoolInventoryUsd instead.

Also in this release:

• liquidityCoverage.exitLadderScope and liquidityCoverage.exitReachRoad name the ROAD behind each exit number, so exitLadderStatus: "unsellable" can no longer be read as "this token cannot be sold" — it describes direct Uniswap v4 pools only, while the pot may have been measured via <asset> somewhere else. Measured 2026-09-22 on Base: unsellable across 31 v4 pools while the position sold for $4,735.82 through another venue.
• exitPoolInventoryUsd is no longer an unconditional upper bound: when the v4 sale ladder ran, the v4 share of it is the ladder's REACH, and it never counts the second leg of a two-leg sale.
• Prices are measured with a real trade's gas limit, because some Uniswap v4 hooks set their fee from the gas available to the caller.
• The contract strings in this package (prices, paths, thresholds, verdict vocabulary, the two notes above) are now GENERATED from the Plexa server sources, so they cannot drift from the API.

No field was removed and no response shape changed. The minor version moved because a published field's meaning did.

Notes