Skip to main content
Glama
dbe006

rugguard-mcp

by dbe006
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

rugguard-mcp

MCP server for RugGuard — pre-trade rug-check API for AI agents. Wraps the x402 payment flow so Claude Desktop, Cursor, and other MCP-aware agents can call RugGuard without speaking x402 themselves.

What it does

Three paid MCP tools:

  • scan_token(chain, address) — runs 14 heuristics on Base + 5 on Solana SPL, returns a weighted risk score 0–100, a verdict (safe | low_risk | medium_risk | high_risk | critical | uncertain), and structured red flags (owner renounced, LP locked, honeypot signatures, top10 concentration, mint authority, bytecode similarity to known rugs via MinHash, deployer rug history, etc.). Pays $0.01 USDC on Base behind the scenes.

  • pretrade_check(chain, address, intended_trade_usd, policy) (new in v0.2.0) — the pre-trade firewall. Wraps the same engine as scan_token and overlays a prescriptive block | caution | allow decision plus a clamped max_suggested_exposure_usd, given the agent's risk policy (conservative | balanced | aggressive). Returns a signed JSON report (Ed25519) when the deployment has signing configured — verifiable offline via the rugguard-verify CLI. Same $0.01 USDC price as scan_token.

  • explain_scan(scan_id) — replays a previously-cached scan's full per-heuristic audit trail. Pays $0.005 USDC.

One free MCP resource:

  • rugguard://metrics — live empirical recall + per-chain sample counts, sourced from /v1/metrics. Free, no payment, no signature. Lets an agent (or a human reviewing the integration) audit per-heuristic recall before pointing a funded wallet at the paid tools. No competitor publishes their own miss rate — this is the differentiator made machine-discoverable.

The server holds a dedicated Base-mainnet wallet and signs each EIP-3009 USDC transferWithAuthorization transparently. The agent never sees the payment friction.

Related MCP server: token-rugcheck

Install

pip install rugguard-mcp

Try it without paying (recommended first step)

Before funding a wallet, verify the MCP integration works end-to-end in Claude Desktop / Cursor / your runtime. Launch the server in demo mode:

python -m rugguard_mcp --demo

Or configure your MCP client to launch it that way directly:

{
  "mcpServers": {
    "rugguard": {
      "command": "python",
      "args": ["-m", "rugguard_mcp", "--demo"]
    }
  }
}

(equivalent: set RUGGUARD_MCP_DEMO=1 in the env block of the MCP client config).

In demo mode the three paid tools return canned scenarios deterministically (safe / caution / critical, picked by the last hex char of the address) flagged with "_demo": true so the agent never mistakes them for real data. No wallet, no payment, no network call to /v1/scan or /v1/pretrade/check. The free rugguard://metrics resource still serves the real live recall numbers.

Telemetry (v0.2.5+): demo mode posts an anonymous counter to /v1/demo/ping per tool invocation. Payload: {"tool": "scan_token", "session_id": "<random uuid per process>"}. No wallet, no scanned address, no app-layer IP, no user identifier. Opt out with RUGGUARD_MCP_DISABLE_TELEMETRY=1. The telemetry call is fire-and-forget with a 2s timeout — a network failure never breaks the demo response.

Use this to:

  • Verify the tool drawer shows scan_token, pretrade_check, explain_scan in Claude Desktop / Cursor.

  • Walk through a full scan → decision flow in your agent before committing on-chain funds.

  • Build and test conditional edges / state branches against realistic response shapes.

When you're ready for real scans, drop the --demo flag and follow the First-time setup below.

First-time setup

Generate a dedicated wallet (never reuse your main one):

python -m rugguard_mcp init

This creates ~/.rugguard/wallet.json (mode 600 on POSIX) and prints the address to fund. Send 5–20 USDC on Base mainnet to that address — both Coinbase and Binance support "Network: Base" withdrawals.

Check status:

python -m rugguard_mcp status

Configure your MCP client

Claude Desktop

Edit claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "rugguard": {
      "command": "python",
      "args": ["-m", "rugguard_mcp"]
    }
  }
}

Restart Claude Desktop. The scan_token, pretrade_check, and explain_scan tools appear in the tool drawer.

Cursor / other MCP clients

Same mcpServers shape, point to python -m rugguard_mcp or the rugguard-mcp console script.

Safety

Spending caps (defense in depth against a runaway agent or a compromised remote server):

Cap

Default

Override

Per-session (resets on restart)

$5

RUGGUARD_MCP_SESSION_SPEND_CAP_USD

Rolling 24 h

$10

RUGGUARD_MCP_DAILY_SPEND_CAP_USD

The caps are enforced client-side, before the EIP-3009 signature — even a compromised 402 response can't trick the wallet into overspending.

Asset whitelist: the client refuses to sign for anything other than canonical USDC on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) or Base Sepolia. A malicious 402 trying to redirect to a different EIP-3009-compatible token in your wallet is rejected before signing.

Replay window: EIP-3009 authorizations are bound to a 10-second validBefore window — short enough that a captured payment header can't be replayed against the USDC contract after the legitimate settlement.

Wallet at rest: ~/.rugguard/wallet.json is mode 600 on POSIX (best-effort on Windows — set ACLs manually for production-grade isolation). Treat the file like an SSH key: don't commit it, don't share it.

Configuration

Env var

Default

Purpose

RUGGUARD_API_URL

https://rugguard.redfleet.fr

Override for staging / self-hosted

RUGGUARD_X402_PRIVATE_KEY

unset

Legacy fallback for users who don't want init

RUGGUARD_MCP_WALLET_PATH

~/.rugguard/wallet.json

Move the wallet file elsewhere

RUGGUARD_MCP_SPEND_LOG_PATH

~/.rugguard/spend_log.json

Where the 24 h spend ledger lives

RUGGUARD_MCP_SESSION_SPEND_CAP_USD

5.0

Tighter cap for cautious operators

RUGGUARD_MCP_DAILY_SPEND_CAP_USD

10.0

Tighter cap for cautious operators

Source

This package is the public, slim distribution of the MCP server. The underlying RugGuard API + heuristic engine remain in a private repo. Code in this repo is MIT-licensed and auditable end-to-end — review it before pointing your funded wallet at it.

License

MIT — see LICENSE.

Available Tools

3 tools
explain_scanA

Fetch the per-heuristic audit trail of a previous scan.

Costs $0.005 USDC. Use this when you need to know why a scan returned a specific verdict — e.g. for compliance, post-mortems, or building a user-visible explanation.

Args: scan_id: UUID returned by a prior scan_token call.

Returns: On success: {scan_id, scanned_at, score, verdict, heuristic_results: [...]}. On failure: {error, message}. Same error codes as scan_token.

In demo mode: returns a canned audit trail keyed by the scan_id
suffix (`demo-safe-01`, `demo-caution-01`, `demo-critical-01`).
Unknown scan_ids return a demo-safe trail. Response has `_demo: true`.
ParametersJSON Schema
NameRequiredDescriptionDefault
scan_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses cost, fetch-only nature, success/failure return formats, and demo mode behavior with `_demo: true`. Could mention rate limits or auth but covers key aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured: purpose, cost/usage, arguments, returns, demo mode – all in a few sentences. Front-loaded with purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all necessary aspects for a simple tool: purpose, cost, return format (including error and demo), and source of scan_id. Output schema exists so return details are sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (scan_id) with 0% schema coverage. Description adds value by stating it's a UUID from a prior `scan_token` call, providing source context beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Fetch the per-heuristic audit trail of a previous scan' – a specific verb and resource. Distinguishes from sibling tools 'pretrade_check' and 'scan_token' by its post-scan audit purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use: 'Use this when you need to know *why* a scan returned a specific verdict — e.g. for compliance, post-mortems, or building a user-visible explanation.' Also mentions cost ($0.005 USDC). Does not explicitly state when not to use, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pretrade_checkA

Pre-trade firewall: returns a prescriptive block | caution | allow decision plus a clamped max_suggested_exposure_usd, given a token, a trade size, and the agent's risk policy.

Costs $0.01 USDC on Base via x402 (same price as scan_token). Returns a signed JSON report when the deployment has signing configured — the signature and key_fingerprint fields prove what RugGuard said at the moment of trade, verifiable offline via the rugguard-verify CLI (pip install rugguard-verify) or against GET /v1/pubkey.

Args: chain: base or solana. address: Token contract address (EVM 0x… or Solana base58). intended_trade_usd: Trade size in USD. Used to clamp the returned max_suggested_exposure_usd. Must be > 0 and ≤ $1B. policy: Agent risk tolerance. One of: - conservative — block at medium_risk or worse (score ≥ 51) - balanced — block at high_risk or worse (score ≥ 71) [default] - aggressive — block at critical only (score ≥ 91) An uncertain verdict (sparse data) returns caution in all modes — absence of evidence is not evidence of safety.

Returns: On success: { scan_id, chain, contract, policy_recommendation: block | caution | allow, policy, risk_score: 0-100, verdict, confidence, reason: [{code, severity}, ...], # top 3 flags max_suggested_exposure_usd: float, # 100% if allow, 20% if caution, 0 if block intended_trade_usd, scanned_at, disclaimer, signature, key_fingerprint # null when signing is unconfigured } On failure: {error, message}. Same error codes as scan_token.

Disclaimer integrity: the disclaimer field is inside the signed bytes. Stripping or rewriting it breaks signature verification by design — a downstream proxy that drops the disclaimer will cause rugguard-verify to reject the report. That is the point.

ParametersJSON Schema
NameRequiredDescriptionDefault
chainYes
policyNobalanced
addressYes
intended_trade_usdYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses cost ($0.01 USDC), signing/verification, disclaimer integrity, and decision logic per policy. No annotations are provided, so the description carries full burden and does so thoroughly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the key output. While comprehensive, it is slightly lengthy but every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and that an output schema exists, the description is complete, covering return values, edge cases (uncertain verdict), and disclaimer integrity. It complements the schema well.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description fully explains each parameter: chain (base/solana), address format, intended_trade_usd constraints, and policy options with defaults. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function as a pre-trade firewall returning a decision (block/caution/allow) and clamped exposure. It distinguishes itself from siblings (scan_token, explain_scan) by its specific pre-trade role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (pre-trade check) and details the policy parameter's behavior. It implies usage context but does not explicitly state when not to use or compare with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

scan_tokenA

Run a pre-trade rug-pull risk scan on a token contract.

Returns a structured risk report. Pays $0.01 USDC on Base behind the scenes via x402. The spend is tracked against per-session and 24 h caps configured in the MCP server — if a cap is breached the call returns a spend_cap_exceeded error WITHOUT signing.

Args: chain: Chain identifier. base for Base mainnet EVM token (14 heuristics). solana for Solana SPL mint (5 heuristics). address: Token contract address — 0x... for EVM, base58 mint address for Solana.

Returns: On success: {score: 0-100, verdict: safe|low_risk|medium_risk|high_risk|critical|uncertain, score_confidence: high|medium|low|insufficient_data, rug_probability_30d: 0.0-1.0, flags: [{code, severity, evidence}, ...], scan_id: uuid for follow-up via explain_scan(...)}. On failure: {error, message}. error is one of missing_credentials, spend_cap_exceeded, payment_failed, request_failed, non_200.

In demo mode (RUGGUARD_MCP_DEMO=1 or `--demo`): returns one of three
canned scenarios deterministically by `address[-1]`. Response has
`_demo: true` — never trade on this. No wallet, no network call.
ParametersJSON Schema
NameRequiredDescriptionDefault
chainYes
addressYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully discloses behavior: payment of $0.01 USDC on Base via x402, per-session and 24h spending caps leading to a spend_cap_exceeded error, demo mode with canned responses, and detailed error types. This covers all critical behavioral aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with 'Args' and 'Returns' sections, front-loading the purpose. It is thorough but not overly verbose; every sentence adds value. A slight trim could be made, but it remains highly effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (payment, caps, demo, multiple chains) and the presence of an output schema, the description covers all necessary aspects: return structure on success and failure, error types, demo behavior, and parameter constraints. It is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description adds essential meaning. It specifies the allowed values for chain ('base' for EVM, 'solana' for SPL mint) and the address format ('0x...' for EVM, base58 for Solana). This goes well beyond the schema's bare property titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Run a pre-trade rug-pull risk scan on a token contract.' It specifies the verb (scan), the resource (token contract), and the output (structured risk report). The mention of returning a risk report distinguishes it from siblings like explain_scan and pretrade_check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context for when to use the tool (pre-trade risk scan), details about payment and spending caps, and error conditions. It does not explicitly exclude usage scenarios or name direct alternatives, but the purpose is clear enough for correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.2.5
    • First observedexplain_scan
    • First observedpretrade_check
    • First observedscan_token
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a clearly distinct purpose: scanning a token, explaining scan results, and providing a prescriptive trade decision. There is no overlap between their functionalities.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case: scan_token, explain_scan, pretrade_check. The naming is predictable and clear.

Tool Count5/5

With 3 tools, the server is tightly scoped to its purpose of token risk scanning and compliance. Each tool earns its place without redundancy or deficiency.

Completeness4/5

The tool surface covers the core workflow (scan, explain, prescriptive decision). Minor gaps exist, such as no ability to update or rescan, but these are not critical for the primary use case.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • token-rugcheck

    AetherCore-Dev
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for real-time Solana token risk analysis. Cross-references RugCheck.xyz, DexScreener, and GoPlus Security to generate three-layer reports: machine verdict → LLM analysis → raw on-chain evidence. Live on Solana mainnet with USDC micropayments ($0.02/audit). Give any AI agent the ability to check if a token is safe before trading.
    2
    MIT

  • onchain-safety-mcp

    aitools420
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that provides AI agents with crypto token safety checks (honeypot, liquidity, rug risk) and alpha signals (smart money buys, fresh rug radar) across PulseChain, Monad, Base, and BSC.
    51 npm
    MIT

  • SENTRA MCP

    SentraMCP
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that detects potential risks in Solana meme tokens using Solsniffer API, helping AI agents avoid rug pulls and unsafe projects.
    MIT