{
  "markdown": "# @getplexa/mcp — Plexa MCP server\n\n![license: MIT](https://img.shields.io/badge/license-MIT-6ee7a8)\n![chains: Base · Polygon · Arbitrum](https://img.shields.io/badge/chains-Base%20%C2%B7%20Polygon%20%C2%B7%20Arbitrum-9aa8f0)\n![x402](https://img.shields.io/badge/payments-x402-aab4f0)\n![MCP](https://img.shields.io/badge/protocol-MCP-c4b5fd)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server that gives any MCP client\n(Claude Desktop, Cursor, your own agent) two economic-safety tools from **[Plexa](https://getplexa.com)** —\nthe x402-native **economic-safety layer for trading agents** — paid per call in USDC, no accounts:\n\n| Tool | Wraps | Price | Returns |\n|---|---|---|---|\n| `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. |\n| `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.) |\n\nIt is a **thin client of the public API** (`https://api.getplexa.com`) — it pays a `402` automatically,\nsigns the USDC authorization **locally** with your wallet, and never sees your key. The liquidity engine\nstays behind the API.\n\n---\n\n## Why\n\nA generic wallet guard answers *\"can I sign this transaction?\"*. It can't answer the **economic**\nquestion an automated trader actually needs: *what price will this swap really fill at under my size,\nand is this token a trap (rug / honeypot / thin liquidity)?* Plexa answers both. This package puts those\nanswers one tool-call away inside any MCP-speaking agent.\n\n---\n\n## Install\n\nNothing to install — point your MCP client at the package via `npx`. It is fetched and run on demand.\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):\n\n```json\n{\n  \"mcpServers\": {\n    \"plexa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@getplexa/mcp\"],\n      \"env\": {\n        \"PLEXA_BASE_URL\": \"https://api.getplexa.com\",\n        \"AGENT_WALLET_KEY\": \"0x<your funded wallet private key>\",\n        \"CHAIN\": \"base\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` (or **Settings → MCP → Add**) — the same `mcpServers` block as above.\n\nRestart the client. You should see the `plexa_quote` and `plexa_pretrade_check` tools available.\n\n---\n\n## Configuration\n\nAll configuration is via environment variables (set in the `env` block of your MCP config):\n\n| Variable | Default | Notes |\n|---|---|---|\n| `PLEXA_BASE_URL` | `https://api.getplexa.com` | The public API. The real URL — not a secret. |\n| `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`. |\n| `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. |\n\n**Funding.** Use a **dedicated, low-balance wallet** with a little USDC on `CHAIN` to pay per call\n(quotes $0.02, checks $0.05). The wallet signs an EIP-3009 USDC authorization per request; Plexa returns\nthe result only after the payment settles on-chain (**settle-before-serve**).\n\n> Your key is a secret. Prefer your MCP client's secret storage if it has one. Never commit it.\n\n---\n\n## How payment works (x402 in MCP)\n\nMCP has no native payment. This server acts as an **x402 client**: it wraps `fetch`, so when Plexa\nreplies `402 Payment Required` it reads the payment requirements, signs a USDC authorization with your\nwallet (locally), and retries. The signed authorization is the only thing that leaves your machine —\n**never the key**. Payment is made on `CHAIN`, so you fund **one wallet on one chain**.\n\nIf no `AGENT_WALLET_KEY` is set, the tools return an honest `402` error explaining a funded wallet is\nneeded — they never fabricate a result.\n\n---\n\n## Example\n\nOnce configured, just ask your agent naturally — it will call the tools:\n\n> *\"Before I buy this token `0x…` on Base, check it with Plexa and get me an executable quote for $500.\"*\n\nThe agent calls `plexa_pretrade_check` (verdict + reasons) and `plexa_quote` (executable price under\n$500), pays $0.05 + $0.02 in USDC automatically, and answers with real on-chain economics.\n\n## What comes back\n\nBeyond `verdict` / `triggers` / `risk_profile` / `liquidityCoverage`, every pre-trade\nresponse carries six blocks of context. Live capture, WETH, **2026-08-20T14:46:29Z**, Base block\n**50223921** — the `note` string each block carries is long and is cut here, nothing else is:\n\n```json\n{\n \"identity\": {\n  \"name\": \"Wrapped Ether\",\n  \"symbol\": \"WETH\",\n  \"decimals\": 18,\n  \"totalSupplyRaw\": \"239296586519181917702210\",\n  \"totalSupply\": 239296.58651918193\n },\n \"valuation\": {\n  \"fdvExecutableUsd\": 543916397.6557496,\n  \"basis\": \"totalSupply(this chain) x executablePrice(at sizeUSD)\"\n },\n \"ownership\": {\n  \"ownerAddress\": null,\n  \"ownerRenounced\": null,\n  \"isMintable\": false,\n  \"creatorAddress\": \"0xe8a3ecea7d6a688ee903173024225357ddf29e93\",\n  \"creatorBalance\": 0.000289172466091074,\n  \"creatorSharePct\": 1.208427041511075e-07\n },\n \"dormancy\": {\n  \"topHolderIdleDays\": null,\n  \"lastTopHolderMoveBlock\": null,\n  \"headBlock\": null\n },\n \"market\": {\n  \"priceUsdSpot\": 2277.76,\n  \"volume24hUsd\": 551324354.8699999,\n  \"marketCapUsd\": 542587444,\n  \"holderCount\": 5223863\n },\n \"sources\": {\n  \"*\": \"measured\",\n  \"risk_profile.concentration\": \"unavailable:holder-axis-produced-nothing\",\n  \"flags.F_CONC\": \"unavailable:holder-axis-produced-nothing\",\n  \"valuation\": \"derived:identity.totalSupply*quote.executablePrice\",\n  \"dormancy\": \"unavailable:holder-axis-produced-no-block\",\n  \"ownership.creatorAddress\": \"derived:sender-of-first-transfer\",\n  \"ownership.isMintable\": \"derived:mint-selector-in-bytecode\",\n  \"market\": \"vendor:dexscreener+goplus\",\n  \"market.priceUsdSpot\": \"vendor:dexscreener\",\n  \"market.volume24hUsd\": \"vendor:dexscreener\",\n  \"market.marketCapUsd\": \"vendor:dexscreener\",\n  \"market.holderCount\": \"vendor:goplus\"\n }\n}\n```\n\n🔴 **`sources` is the map of who said what.** `measured` — ours, read off the chain on\nthis call. `derived:<formula>` — ours, computed from other fields of this same response.\n`vendor:<name>` — somebody else's number, republished and signed as theirs.\n`unavailable:<reason>` — no value, **and the reason why**. That last one is the point:\na missing number that names its own gap cannot be mistaken for a clean result.\n\nTwo numbers that look like duplicates and are not: `valuation.fdvExecutableUsd` is\nTHIS chain's supply at the price your size executes at; `market.marketCapUsd` is the\nvendor's global figure. For a bridged token ours is legitimately smaller.\n\n---\n\n## Notes\n\n- **Client-only.** Talks to the public Plexa API over HTTPS. No service internals ship in this package.\n- **Honest failures.** A non-2xx response or a network error becomes a loud tool error — never a\n  clean-looking empty result. An agent can always tell a failure from a pass.\n- Built on the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol) +\n  [x402](https://x402.org).\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n\nQuestions: **[support@getplexa.com](mailto:support@getplexa.com)** · **[getplexa.com](https://getplexa.com)**\n\n> Informational on-chain data and heuristic economic signals, **not financial advice**. Absence of flags\n> is not a guarantee of safety. Verify independently before trading.\n",
  "bytes": 8160,
  "sha": "3627b7eeba71f705c752f912ae416a0946463676be1770a5dda28dfd20d09d69",
  "repo_slug": "plexa-xyz/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_getplexa_mcp_182e88b5/readme"
}