evidiq-sentinel-mcp

<p align="center"> <img src="https://raw.githubusercontent.com/evidiq/evidiq/main/assets/evidiq.png" width="88" alt="EVIDIQ" /> </p> <h1 align="center">EVIDIQ Sentinel</h1> <p align="center"><strong>Security preflight for MCP servers and Agent Skills.</strong></p> <p align="center"> Inspect &middot; Score &middot; Sign — verify agent infrastructure before trust, credentials, or funds are exposed. </p> <p align="center"> <a href="https://evidiq.dev">evidiq.dev</a> &middot; <a href="https://evidiq.dev/docs/sentinel">Sentinel Docs</a> &middot; <a href="https://github.com/evidiq/evidiq-sentinel-mcp">Sentinel Repository</a> </p> <p align="center"> <a href="https://mcp.evidiq.dev/sentinel/mcp"><img src="https://img.shields.io/badge/MCP%20Server-Live-6E56CF?style=flat-square" alt="MCP Server" /></a> <a href="https://0g.ai"><img src="https://img.shields.io/badge/0G%20Compute-GLM%205.2%20TEE-00C2A8?style=flat-square" alt="GLM 5.2 via 0G Compute TEE" /></a> <a href="https://www.oklink.com/xlayer"><img src="https://img.shields.io/badge/X%20Layer-USDT0-3CCF4E?style=flat-square" alt="X Layer USDT0" /></a> <a href="https://mcp.evidiq.dev/sentinel/x402"><img src="https://img.shields.io/badge/x402-0.02%20USDT0-2563EB?style=flat-square" alt="x402: 0.02 USDT0" /></a> <a href="https://web3.okx.com/onchainos/dev-docs/payments/service-seller-sdk"><img src="https://img.shields.io/badge/Payments-Official%20OKX%20SDK-121212?style=flat-square&logo=okx&logoColor=white" alt="Official OKX Payment SDK" /></a> <a href="https://www.okx.ai/agents/7584"><img src="https://img.shields.io/badge/OKX.AI-Agent%20%237584%20Listed-121212?style=flat-square&logo=okx&logoColor=white" alt="OKX.AI Agent 7584 listed" /></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-3DA639?style=flat-square" alt="License: MIT" /></a> </p> --- An agent can discover an MCP server or Skill in seconds. Determining whether that service contains hidden instructions, dangerous capabilities, credential exposure, or conflicting behavior should happen before the agent connects to it. **EVIDIQ Sentinel is the security and compliance preflight layer for the agent economy.** It scans remote MCP endpoints, supplied MCP manifests, Agent Skills, and multi-target bundles. Each scan produces a deterministic `PASS`, `REVIEW`, or `BLOCK` verdict, a score from `0–100`, actionable findings, and a signed report. Sentinel can also request a semantic review from **GLM 5.2 through 0G Compute TEE**. That review is advisory: deterministic static rules alone determine the score and verdict. Signed reports can be anchored to 0G Storage on a best-effort basis. ## What it does - **MCP endpoint inspection** — safely introspects a public remote MCP service and evaluates its exposed metadata. - **Manifest analysis** — scans supplied tools, prompts, resources, and capability declarations without executing them. - **Agent Skill review** — examines Skill markdown or an HTTPS source for unsafe instructions and capability mismatches. - **Bundle analysis** — evaluates several targets together for shadowing, conflicts, and cross-service risk. - **Deterministic decisions** — static rules, not model output, produce every score and verdict. - **Verifiable reports** — EIP-191 signatures protect report integrity and support offline verification. - **Optional evidence anchoring** — signed report evidence can be recorded on 0G Storage when configured. - **Pay per scan** — four scan tools cost `0.02 USDT0` each; four discovery and verification tools are free. ## Use it from any agent ```bash # Read the public Skill document curl -s https://mcp.evidiq.dev/sentinel/skill.md # Inspect current x402 requirements curl -s https://mcp.evidiq.dev/sentinel/x402 # Connect the remote MCP server (Claude Code) claude mcp add --transport http evidiq-sentinel https://mcp.evidiq.dev/sentinel/mcp ``` Public endpoints: | Endpoint | Purpose | |----------|---------| | `https://mcp.evidiq.dev/sentinel/mcp` | Remote MCP transport | | `https://mcp.evidiq.dev/sentinel/skill.md` | Agent-readable usage and safety guide | | `https://mcp.evidiq.dev/sentinel/x402` | x402 v2 pricing and payment discovery | | `https://mcp.evidiq.dev/sentinel/health` | Service health | | `https://evidiq.dev/docs/sentinel` | Technical documentation | ## MCP tools ### Paid scans | Tool | Cost | Description | |------|------|-------------| | `scan_mcp_endpoint` | `0.02 USDT0` | Safely introspect and scan a public remote MCP endpoint | | `scan_mcp_manifest` | `0.02 USDT0` | Scan supplied MCP tool, prompt, resource, and capability metadata | | `scan_agent_skill` | `0.02 USDT0` | Scan supplied Skill markdown or content retrieved from an HTTPS URL | | `scan_bundle` | `0.02 USDT0` | Analyze multiple targets together for interactions, shadowing, and conflicts | ### Free preflight and verification | Tool | Cost | Description | |------|------|-------------| | `sentinel_capabilities` | Free | Read service capabilities, supported targets, limits, and pricing | | `validate_scan_target` | Free | Validate a target's format before starting a paid scan | | `estimate_cost` | Free | Return the exact price for a requested paid tool | | `verify_scan_report` | Free | Verify a Sentinel report's EIP-191 signature and integrity | ## How a scan works 1. Sentinel validates target type, URL scheme, payload size, and structural limits. 2. A paid tool must pass the configured x402 gate before scan execution. 3. The target is normalized, sanitized, and analyzed by deterministic security rules. 4. If enabled, GLM 5.2 reviews the sanitized material through 0G Compute TEE. 5. Advisory model observations are kept separate from deterministic scoring. 6. Static findings produce the final `0–100` score and `PASS`, `REVIEW`, or `BLOCK` verdict. 7. Sentinel signs the canonical report with EIP-191. 8. Sentinel attempts a best-effort 0G Storage anchor and returns the report. ## Deterministic rules, advisory intelligence Sentinel deliberately separates decision authority from model-assisted analysis. This prevents nondeterministic output from silently changing a security verdict. The static rules cover risks including: - prompt injection and instruction override; - hidden instructions and tool poisoning; - tool shadowing and cross-service behavior modification; - credential, secret, and sensitive-data exposure; - exfiltration paths and unexpected network behavior; - dangerous file-system, process, or network capabilities; - obfuscation and encoded payloads; - declared-versus-observed capability mismatches; - insecure transport and unsafe remote references; - x402 metadata and payment-flow inconsistencies. When semantic review is enabled, GLM 5.2 can add context and surface ambiguous patterns that deserve human attention. It cannot raise or lower the deterministic score and cannot replace the static verdict. ## Report contract Every completed scan returns a Sentinel report containing: - the normalized scan target and report metadata; - a deterministic score on the `0–100` scale; - one verdict: `PASS`, `REVIEW`, or `BLOCK`; - categorized findings with severity, evidence, and remediation; - an EIP-191 signature over the canonical report; - optional 0G Storage anchor metadata when upload succeeds; - an advisory semantic-analysis trace when enabled and available. Use the free `verify_scan_report` tool to verify signature integrity. A valid signature proves that the signed report has not been altered and identifies the signing address. It does not guarantee that a target remains unchanged after the scan or that every future interaction is safe. The 0G Storage anchor is best effort. A missing anchor does not change the static verdict or invalidate an otherwise valid report signature. ## Pricing and x402 | Operation | Cost | Token | Network | Atomic amount | |-----------|------|-------|---------|---------------| | Any of the four scan tools | `0.02` each | USDT0 | X Layer (`eip155:196`) | `20000` | | Capability, validation, estimate, and verification tools | Free | — | — | — | Sentinel publishes an **x402 v2** challenge using the `exact` scheme. Compatible clients read the `PAYMENT-REQUIRED` response, authorize the requested USDT0 amount, and retry with `PAYMENT-SIGNATURE`. The live discovery response at [`/sentinel/x402`](https://mcp.evidiq.dev/sentinel/x402) is authoritative for the active asset, recipient, amount, and network. ### Official OKX Payment SDK Payment verification and settlement run through the **official OKX Onchain OS Payment SDK**, not a hand-rolled payment stack: | Package | Role | |---------|------| | [`@okxweb3/x402-core`](https://www.npmjs.com/package/@okxweb3/x402-core) | `OKXFacilitatorClient` (HMAC-SHA256 OKX REST auth) and `x402ResourceServer` | | [`@okxweb3/x402-evm`](https://www.npmjs.com/package/@okxweb3/x402-evm) | `ExactEvmScheme` — the EVM `exact` scheme server implementation | The OKX facilitator verifies each authorization and settles it on X Layer; Sentinel keeps ownership of scan routing, pricing, and report signing. Each price is sent to the SDK as an explicit USD₮0 **atomic asset amount** rather than a USD string, so the quoted fee token always matches the token registered for the OKX listing. Settlement completes before any paid scan begins. When the facilitator's own confirmation wait elapses it answers `timeout` even though the transaction it broadcast can still confirm moments later, so Sentinel resolves that state through the facilitator's settlement-status lookup instead of failing the call. Success is only ever reported when the facilitator confirms it. Integration guide: [OKX Onchain OS — integrate via SDK](https://web3.okx.com/onchainos/dev-docs/payments/service-seller-sdk). ## Architecture ```mermaid flowchart TB agent["<b>AI agent</b><br/>MCP client"] request{"Scan request<br/>free or paid?"} agent -->|POST /sentinel/mcp| request free["Free preflight<br/>validate · estimate · verify"] gate["x402 v2 gate<br/>paid scan authorization"] xlayer[("X Layer<br/>USDT0 · eip155:196")] request -->|free helper| free request -->|paid scan| gate gate -. payment rail .-> xlayer subgraph sentinel["EVIDIQ Sentinel trust boundary"] direction TB normalize["1. Normalize & sanitize<br/>protocol · size · depth limits"] rules["2. Deterministic rules engine<br/><b>only score + verdict authority</b>"] report["3. Canonical SentinelReport<br/>findings · remediation · PASS / REVIEW / BLOCK"] sign["4. EIP-191 signature<br/>integrity + signer identity"] normalize --> rules --> report --> sign end free --> normalize gate --> normalize compute[("0G Compute TEE<br/>GLM 5.2 semantic review")] storage[("0G Storage<br/>best-effort evidence anchor")] normalize -. sanitized context .-> compute compute -. advisory context only .-> report sign -. best effort .-> storage response["<b>MCP response</b><br/>signed report + optional anchor metadata"] sign --> response classDef client fill:#312e81,stroke:#a78bfa,color:#ffffff,stroke-width:2px; classDef payment fill:#052e16,stroke:#4ade80,color:#ffffff,stroke-width:2px; classDef sentinel fill:#241b35,stroke:#8b5cf6,color:#ffffff,stroke-width:2px; classDef optional fill:#083344,stroke:#2dd4bf,color:#ecfeff,stroke-width:2px; classDef output fill:#4c1d95,stroke:#c4b5fd,color:#ffffff,stroke-width:2px; class agent,request client; class free,gate,xlayer payment; class normalize,rules,report,sign sentinel; class compute,storage optional; class response output; ``` **Reading the diagram:** solid arrows are required scan-path steps. Dashed arrows are optional or advisory integrations. Only the deterministic rules engine sets the score and `PASS` / `REVIEW` / `BLOCK` verdict; GLM 5.2 adds context to the report but cannot change that decision. An unavailable 0G Storage anchor also does not block a signed report. ## Security boundaries - Sentinel analyzes metadata and supplied content; it does not grant a scanned service trust or execute its advertised tools. - Remote targets and retrieved content remain untrusted input and are subject to protocol, size, and depth limits. - Secret-like values are detected and redacted from report evidence where applicable. - Semantic review receives sanitized scan material and remains advisory. - Deterministic output is canonicalized before signing for consistent integrity checks. - EIP-191 signatures protect report authenticity; they do not certify the target's future behavior. - 0G Storage anchoring is optional and best effort, not a prerequisite for a verdict. - Re-scan a target after manifest, Skill, endpoint, ownership, or deployment changes. - Apply human review before granting credentials, funds, write access, or irreversible authority. ## Verification status Sentinel's GLM 5.2 production inference path through 0G Compute has returned `teeVerified: true`, and real 0G Storage report anchoring has been exercised. These checks verify the respective Compute and Storage paths. They do not turn advisory model output into scoring authority. ### Paid call settled on X Layer A live paid scan against the deployed endpoint completed the full x402 v2 round trip through the official OKX facilitator: | | | |---|---| | Tool | `scan_agent_skill` | | Amount | `0.02 USDT0` (`20000` atomic) on X Layer (`eip155:196`) | | Flow | unpaid call → HTTP 402 + `PAYMENT-REQUIRED` → EIP-3009 signature → `PAYMENT-SIGNATURE` retry → HTTP 200 + `PAYMENT-RESPONSE` | | Settlement tx | [`0x0839c4f2…afb01b`](https://www.oklink.com/xlayer/tx/0x0839c4f2f2dd798e278f3517a88bf2dc7af02150a1c1529b08797db972afb01b) · success | | Result | signed `SentinelReport`, verdict `PASS`, security score `97` | An earlier scan of a payment-gated MCP target settled in [`0xf7cac7c6…e22905`](https://www.oklink.com/xlayer/tx/0xf7cac7c634ec21b5f4e1a8507ef3d1c690d097be90f36d8980d255f7f0e22905) and returned a tool error because that target answers `402` to Sentinel's fetch — the payment path succeeded, the scan target was simply unreachable. Free tools stay ungated and answer `200` without any payment header. EVIDIQ Sentinel is registered as **OKX.AI Agent #7584**. Its public listing is currently under review: [view the agent page](https://www.okx.ai/agents/7584). ## Self-host Requirements: Node.js `22+` and npm. ```bash # From source npm install npm run build npm start ``` Or run the container: ```bash docker build -t evidiq-sentinel . docker run -d --name evidiq-sentinel -p 3000:3000 --env-file .env evidiq-sentinel ``` Local routes: `POST /mcp` · `GET /skill.md` · `GET /x402` · `GET /health` ### Configuration Copy `.env.example` to `.env` and set only the integrations you use: ```bash # Server PORT=3000 HOSTNAME=0.0.0.0 # Official OKX Payment SDK — required for the production payment path. # Create the credentials at https://web3.okx.com/onchainos/dev-portal # All three must be set together; a partial set is rejected at startup. OKX_API_KEY=... OKX_SECRET_KEY=... OKX_PASSPHRASE=... OKX_BASE_URL=https://web3.okx.com # OKX_SYNC_SETTLE=0 # opt out of the facilitator's synchronous confirmation wait # x402 v2 — X Layer mainnet / USDT0 X402_PRICE=20000 X402_ASSET=0x779ded0c9e1022225f8e0630b35a9b54be713736 X402_CHAIN=eip155:196 X402_PAY_TO=0x... X402_DOMAIN_NAME=USD₮0 X402_DOMAIN_VERSION=1 X402_RPC_URL=https://rpc.xlayer.tech X402_SETTLE_KEY=0x... # only used when no OKX credentials are configured # Report signing SENTINEL_PRIVATE_KEY=0x... # Optional GLM 5.2 semantic review through 0G Compute AI_ENABLED=false OG_COMPUTE_API_KEY=... OG_COMPUTE_BASE_URL=https://router-api.0g.ai/v1 OG_COMPUTE_MODEL=glm-5.2 AI_MAX_TOKENS=900 AI_TEMPERATURE=0.1 AI_TIMEOUT_MS=22000 # Optional best-effort 0G Storage anchoring OG_PRIVATE_KEY=0x... OG_STORAGE_RPC=https://evmrpc.0g.ai OG_STORAGE_INDEXER=https://indexer-storage-turbo.0g.ai ``` With `AI_ENABLED=false`, Sentinel runs deterministic static analysis only. If x402 is not configured in a self-hosted deployment, the local discovery endpoint reports that no payment gate is active. Never commit `.env` files, signing keys, settlement keys, API keys, or scanned private material. ## Development ```bash npm install # install dependencies npm run build # compile TypeScript to dist/ npm test # run the test suite once npm run dev # start the local watch server ``` ## Links - **Website** — https://evidiq.dev - **Sentinel documentation** — https://evidiq.dev/docs/sentinel - **Live MCP endpoint** — https://mcp.evidiq.dev/sentinel/mcp - **Agent Skill** — https://mcp.evidiq.dev/sentinel/skill.md - **x402 discovery** — https://mcp.evidiq.dev/sentinel/x402 - **Service health** — https://mcp.evidiq.dev/sentinel/health - **OKX.AI Agent #7584** — https://www.okx.ai/agents/7584 - **OKX Payment SDK guide** — https://web3.okx.com/onchainos/dev-docs/payments/service-seller-sdk - **Settlement proof** — https://www.oklink.com/xlayer/tx/0x0839c4f2f2dd798e278f3517a88bf2dc7af02150a1c1529b08797db972afb01b - **EVIDIQ main repository** — https://github.com/evidiq/evidiq - **EVIDIQ Notary** — https://github.com/evidiq/evidiq-notary-mcp - **EVIDIQ Operator** — https://github.com/evidiq/evidiq-operator - **0G Labs** — https://0g.ai - **x402 Protocol** — https://x402.org ## TypeScript SDK A typed client for the live endpoint lives in [`sdk/index.ts`](sdk/index.ts) — 8 tools (4 free, 4 paid). Free tools answer a bare call; paid tools run the x402 flow automatically (402 challenge → `pay` hook → replay with the `x-payment` header). No key lives in the file. ```ts import { SentinelClient } from "./sdk/index.js"; const client = new SentinelClient(); // endpoint defaults to https://mcp.evidiq.dev/sentinel/mcp // free const caps = await client.callTool("sentinel_capabilities", {}); // paid — settle the 402 challenge via the constructor's pay hook, or omit it // to receive a PaymentRequiredError carrying the full x402 v2 challenge const result = await client.callTool("some_paid_tool", { arg: "value" }); ``` The `pay` hook receives the decoded x402 v2 challenge (`{ x402Version, resource, accepts[] }` — payTo, asset, amount) and returns the value for the `x-payment` header, e.g. an EIP-3009 `transferWithAuthorization` settled via the official OKX SDK. Without a hook, paid calls throw `PaymentRequiredError` so the caller can settle however it wants. ## License MIT © 2026 EVIDIQ — see [LICENSE](./LICENSE). Part of the [EVIDIQ](https://github.com/evidiq/evidiq) trust and execution layer for the AI agent economy.