Metadata-Version: 2.4
Name: sentinel-mcp
Version: 1.0.1
Summary: SENTINEL MCP server — pre-execution transaction safety oracle for AI agents, paid autonomously via x402 on Base
Author-email: SENTINEL <iv@sentinel-agent.dev>
License: MIT
Project-URL: Homepage, https://sentinel-agent.dev
Project-URL: Documentation, https://sentinel-agent.dev/llms.txt
Project-URL: Methodology, https://sentinel-agent.dev/methodology
Project-URL: Stats, https://sentinel-agent.dev/stats
Keywords: mcp,model-context-protocol,x402,coinbase,ai-agent,security,web3,claude
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: eth-account>=0.13.0

# sentinel-mcp

<!-- mcp-name: io.github.teodorofodocrispin-cmyk/sentinel-mcp -->

MCP (Model Context Protocol) server for [SENTINEL](https://sentinel-agent.dev) — a
pre-execution transaction safety oracle for autonomous AI agents. Lets any
MCP-compatible client (Claude Desktop, Cursor, Windsurf, or any other agent that
speaks MCP) check whether a transaction is safe to sign, *before* signing it,
and pays for the check autonomously via [x402](https://x402.org) — no human in
the loop, no API key, no subscription.

**Independent, standalone package.** Distributed via PyPI and the official
[MCP Registry](https://modelcontextprotocol.io/registry/about) (plus downstream
aggregators: mcp.so, glama.ai, smithery.ai) — not tied to any single agent
framework or requiring anyone's approval to use.

## What it checks

- Contract security (honeypots, hidden owner/mint functions, active blacklist
  functions, proxy patterns, etc.) — via GoPlus
- A real buy/sell simulation against the token's live DEX pair — via honeypot.is
- Transaction simulation (does the call actually succeed) — via Alchemy
- Prior history: has this exact contract been flagged before, by any other agent?
- Deployer wallet track record (transaction count as a freshness signal)
- For ambiguous cases: a second opinion from an LLM council (Claude + GPT-4o-mini)

Returns a `SAFE` / `UNSAFE` / `UNKNOWN` verdict, a 0–100 risk score, and a
cryptographically signed (ed25519) receipt.

## Install

```bash
pip install sentinel-mcp
```

## Configure

Set an environment variable with a Base wallet's private key (holding USDC on Base):

```bash
export AGENT_WALLET_PRIVATE_KEY="0x..."
```

## Use with Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "sentinel": {
      "command": "sentinel-mcp",
      "env": {
        "AGENT_WALLET_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

## Use with any other MCP client

```bash
sentinel-mcp
```

Runs over stdio, the standard MCP transport for local server processes.

## Cost

$0.005 USDC per check, on Base mainnet, paid automatically via x402 from the
configured wallet. No trial, no free tier — the price itself is the friction,
by design.

## Links

- [Live methodology](https://sentinel-agent.dev/methodology) — exactly how a
  verdict is computed, published and machine-readable.
- [Aggregate stats](https://sentinel-agent.dev/stats) — track record across all
  callers, updated live.
- [Report an outcome](https://sentinel-agent.dev/v1/outcome) — free endpoint to
  report back what actually happened after acting on a verdict.

## Related

- [`sentinel-agentkit-provider`](https://pypi.org/project/sentinel-agentkit-provider/)
  — the same safety check as a Coinbase AgentKit action provider.

## License

MIT
