mcp

@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.

Notes

• Client-only. Talks to the public Plexa API over HTTPS. No service internals ship in this package.
• Honest failures. A non-2xx response or a network error becomes a loud tool error — never a clean-looking empty result. An agent can always tell a failure from a pass.
• Built on the official @modelcontextprotocol/sdk + x402.

License

MIT — see LICENSE.

Questions: support@getplexa.com · getplexa.com

Informational on-chain data and heuristic economic signals, not financial advice. Absence of flags is not a guarantee of safety. Verify independently before trading.