@getplexa/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:

Tool	Wraps	Price	Returns
plexa_quote	POST /v1/quote	$0.02	Executable fill price under size (not mid/spot), price impact (bps), realizable depth, per-leg route, worst-case slippage, confidence — from canonical on-chain quoters on Base, Polygon & Arbitrum.
plexa_pretrade_check	POST /v1/pretrade/check	$0.05	Two levels. verdict: avoid only when a listed trap is proven on-chain at that block (no pool to exit into · the counter-asset pot is under 5% of your size, and the pot is a hard upper bound on what a sale can return · the token's own trading gate is off), clear otherwise — clear means no provable trap, not "safe". risk_profile: age, holder concentration, liquidity depth incl. exitLiquidityUsd, oracle availability, transfer limits — as data you weigh, not as a rating. Plus reasons, confidence and an executable quote. (Base-only today.)

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

Variable	Default	Notes
PLEXA_BASE_URL	https://api.getplexa.com	The public API. The real URL — not a secret.
AGENT_WALLET_KEY	(none)	Required to pay. Funded wallet private key — pays per call and signs locally. Plexa never receives it. Without it, tools return a clear 402.
CHAIN	base	base | polygon | arbitrum (aliases matic, arb, arbitrum-one and CAIP-2 eip155:8453/137/42161 also work; case is normalized). The chain your wallet is funded on; quotes and payment default to it. plexa_pretrade_check is Base-only today — other chains answer 422.

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.

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: [e-mail] · 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.