{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/mcp-x402-logo.png\" alt=\"MCP x402 logo\" width=\"160\" />\n</p>\n\n# MCP x402 — Evidence-Backed Web Verification for AI Agents\n\n[![AllMCPs Verified](https://allmcps.com/api/badge/mcp-x402-evidence-backed-web-verification)](https://allmcps.com/mcp/mcp-x402-evidence-backed-web-verification?verify=b470dbc0-c40c-43b7-b705-c3c789b04402)\n\n## Verify a seller, product, offer, policy, or claim before an agent acts\n\nGive an AI agent a public HTTP(S) page and 1 to 10 concrete conditions. The `verificar_condicoes` tool returns an evidence-based decision for every condition:\n\n- `confirmado` — the page clearly supports the condition.\n- `rejeitado` — the page clearly contradicts the condition.\n- `incerto` — the available page evidence is insufficient.\n\nEach verification includes the final source URL, page title, timestamp, condition-by-condition explanation, quoted evidence when available, a unique `verificationId`, and a SHA-256 `pageHash`.\n\n### Designed for\n\n- AI purchasing and procurement agents;\n- seller, product and offer verification;\n- pre-purchase due diligence;\n- policy and terms checking;\n- commercial automation that requires evidence before taking action.\n\n### Simple x402 integration\n\n- Free preflight validation before payment.\n- `$0.05 USDC` per verification on Base mainnet.\n- No account or subscription required.\n- Available through MCP and HTTP.\n- Ready-to-run buyer included in this repository.\n- Bazaar discovery metadata enabled on the paid HTTP and MCP surfaces.\n\n### Live endpoints\n\n- MCP: `https://mcp-x402-production.up.railway.app/mcp`\n- Free MCP preflight: `POST https://mcp-x402-production.up.railway.app/preflight/mcp`\n- Free verification preflight: `POST https://mcp-x402-production.up.railway.app/preflight/verify-conditions`\n- Paid verification: `POST https://mcp-x402-production.up.railway.app/verify-conditions`\n- Health: `GET https://mcp-x402-production.up.railway.app/health`\n\nThe service also provides paid public URL analysis and general AI consultation through `analisar_url` and `consultar_ia`.\n\n## Live Service\n\n- Base URL: `https://mcp-x402-production.up.railway.app`\n- Health check: `GET /health`\n- MCP endpoint: `POST /mcp`\n- Paid URL analysis: `POST /analyze`\n- Price: `$0.05 USDC` per paid request\n- Network: Base mainnet (`eip155:8453`)\n\n## Production Status\n\n- Production deployment active on Railway\n- x402 version 2 payment flow\n- Base mainnet payments (`eip155:8453`)\n- Paid HTTP endpoints return valid x402 challenges with Bazaar metadata\n- MCP and HTTP payment, execution, settlement, and delivery confirmed on-chain\n- MCP Bazaar metadata advertises the public HTTPS MCP server URL\n- CDP native MCP catalog indexing is not yet claimed as confirmed; upstream tracking: [coinbase/cdp-sdk#764](https://github.com/coinbase/cdp-sdk/issues/764)\n\n## MCP Tools\n\n## Decision verification\n\n### `verificar_condicoes` — $0.05 USDC\n\nA paid decision-verification tool for agents.\n\nGive it a public URL and one or more concrete conditions. It returns a decision based only on evidence extracted from that page:\n\n- `confirmado` — the page clearly proves the condition.\n- `rejeitado` — the page clearly contradicts the condition.\n- `incerto` — the page does not provide enough evidence.\n\nEach result includes the final source URL, page title, verification timestamp, condition-by-condition explanation, and a short quoted proof where available.\n\nExample conditions:\n\n- “The page identifies the seller.”\n- “The product is available in Portugal.”\n- “The page shows a price in euros.”\n- “The document states that the service supports x402.”\n\nThis is designed for agents that need an evidence-based decision before taking the next action.\n\n| Tool | Description | Price |\n| --- | --- | --- |\n| `consultar_ia` | Sends a prompt to the OpenAI Responses API. | $0.02 USDC |\n| `analisar_url` | Fetches and analyzes a public HTTP or HTTPS page. | $0.05 USDC |\n| `verificar_condicoes` | Verifies concrete conditions on a public page and returns evidence-based decisions. | $0.05 USDC |\n\n## Technology\n\n- Node.js and TypeScript\n- Express\n- Model Context Protocol\n- OpenAI Responses API\n- x402 payments\n- viem\n- Cheerio\n- Railway\n\n## Security\n\n- HTTPS provided by Railway\n- Helmet security headers\n- Rate limit of 100 requests per 15 minutes\n- Structured request logs with unique request IDs\n- Host validation and Railway health-check support\n- Restricted OpenAI API key with access only to `/v1/responses`\n- Environment files and secrets excluded from Git\n\n## Environment Variables\n\n### Server\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `OPENAI_API_KEY` | Yes | OpenAI project API key. |\n| `OPENAI_MODEL` | No | OpenAI model. Defaults to `gpt-5-mini`. |\n| `HOST` | No | Listening host. Defaults to `0.0.0.0`. |\n| `PORT` | No | Listening port. Defaults to `3000`. |\n| `RAILWAY_PUBLIC_DOMAIN` | Railway | Automatically supplied by Railway. |\n| `PUBLIC_SERVICE_URL` | No | Canonical public HTTPS origin used in discovery metadata. Railway derives it automatically from `RAILWAY_PUBLIC_DOMAIN`; the production URL is the fallback. |\n| `OBSERVABILITY_SALT` | Recommended | Stable secret salt used only to pseudonymize source/client fingerprints across restarts. |\n\n### Local Buyer\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `EVM_PRIVATE_KEY` | Yes | Private key of the Base mainnet buyer wallet. Never commit this value. |\n| `JOURNEY_ID` | No | Existing correlation ID to reuse; otherwise the buyer generates one. |\n\nExample local `.env.test` file:\n\n```env\nEVM_PRIVATE_KEY=your_private_key_here\n```\n\n## Local Development\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nStart the development server:\n\n```bash\nnpm run dev\n```\n\nBuild the project:\n\n```bash\nnpm run build\n```\n\nStart the compiled server:\n\n```bash\nnpm start\n```\n\n## Health Check\n\nThe health endpoint is public and does not require payment:\n\n```bash\ncurl https://mcp-x402-production.up.railway.app/health\n```\n\n## Railway Log Diagnostics\n\nRailway currently accepts `--since` for historical HTTP logs but rejects\n`--until`. On Windows PowerShell, export a bounded application and HTTP log\nwindow without using the broken flag:\n\n```powershell\n.\\scripts\\export-railway-window.ps1 `\n  -StartUtc \"2026-08-22T16:31:22.401228537Z\" `\n  -EndUtc \"2026-08-23T06:21:18.045229877Z\" `\n  -OutputPrefix \"railway-diagnostic\"\n```\n\nThe script retrieves logs from the lower bound and applies the upper UTC bound\nlocally using ordinal ISO-8601 comparison, which preserves Railway's nanosecond\ntimestamps. It writes raw captures plus bounded `app` and `http` NDJSON files.\n\nAnalyze both bounded files while reading and validating every physical line:\n\n```bash\nnpm run logs:analyze -- \\\n  --since \"2026-08-22T16:31:22.401228537Z\" \\\n  --pretty \\\n  --out railway-diagnostic-report.json \\\n  railway-diagnostic-app.ndjson railway-diagnostic-http.ndjson\n```\n\nThe report includes per-file coverage, empty/valid/invalid line counts,\ntimestamp bounds, separation of `Diogo-*`, `RailwayHealthcheck`, known probes\nor indexers and potentially external traffic, journey reconstruction and funnel\nstopping points. It joins application `railwayRequestId` values to Railway HTTP\n`requestId` values, understands HTTP `clientUa`, groups server-generated journey\nIDs by fingerprint and temporal proximity, and counts only accepted normalized\nfeedback. It deliberately does not treat an isolated `402` as purchase intent\nand does not infer human identity or motivation from request metadata.\n\n\n## Ready-to-Run x402 Buyer\n\nThe repository includes ready-to-run buyers for applications and AI agents. The MCP buyer connects to the live service, validates the x402 payment requirements against Base mainnet USDC and a maximum payment of $0.05, signs the payment, retries the same tool call, and prints the settlement receipt and result.\n\nClone and prepare the buyer:\n\n```bash\ngit clone https://github.com/Diogoup26/mcp-x402.git\ncd mcp-x402\nnpm install\n```\n\nCreate a local `.env.test` file in the project root:\n\n```env\nEVM_PRIVATE_KEY=0xYOUR_64_HEX_CHARACTER_PRIVATE_KEY\n```\n\nNever commit `.env.test` or expose the private key.\n\nBuild the project:\n\n```bash\nnpm run build\n```\n\nThe following commands authorize real x402 payments on Base mainnet:\n\n- `consultar_ia`: $0.02 USDC\n- `analisar_url`: $0.05 USDC\n- `verificar_condicoes`: $0.05 USDC\n\n### HTTP URL Analysis\n\n```bash\nnpm run analyze -- \"https://example.com\" \"Summarize this page.\"\n```\n\n### HTTP Decision Verification\n\n```bash\nnpm run verify -- \"https://example.com\" \"The page identifies the seller.\"\n```\n\n### MCP URL Analysis\n\n```bash\nnpm run mcp:analyze -- \"https://example.com\" \"Summarize this page.\"\n```\n\n### MCP AI Consultation\n\n```bash\nnpm run mcp:consult -- \"Reply only with: MCP OK\"\n```\n\n### MCP Decision Verification\n\n```bash\nnpm run mcp:verify -- \"https://example.com\" \"The page identifies the seller.\"\n```\n\nA successful MCP payment prints:\n\n- `PAGAMENTO MCP: success`\n- the settlement receipt\n- the tool response\n\nThe MCP buyer never prints the private key and rejects any payment that:\n\n- is not on Base mainnet;\n- does not use the configured Base USDC contract;\n- exceeds $0.05 USDC.\n\n## Machine-Readable Payment Continuation\n\nThe discovery document at `GET /.well-known/x402` and every successful free\npreflight response publish a complete continuation sequence. A compatible\nagent no longer has to infer what to do after the first unpaid request:\n\n1. run the free preflight and keep its `x-journey-id`;\n2. send the validated request without a payment signature;\n3. read and verify the `payment-required` requirements;\n4. authorize only the expected network, asset, amount and recipient;\n5. retry the identical request with the x402 payment payload;\n6. verify both delivery and the settlement receipt.\n\nREST metadata recommends `@x402/fetch`; MCP metadata recommends `@x402/mcp`.\nPaid responses also link back to the discovery instructions through\n`x-payment-instructions`. They additionally publish an RFC 8288 `Link` header\nwith the registered `payment` and `help` relations, so generic HTTP agents can\ndiscover the same machine-readable continuation and optional feedback path\nwithout depending on project-specific headers. The flow never requests a\nprivate key, Railway or GitHub credentials, or an OpenAI key.\n\n## Optional Conversion Feedback\n\nEvery paid HTTP or MCP response advertises `x-feedback-endpoint` and the\nallowed normalized reason, stage, and intent values. The free preflight\nresponses include the same information in a `feedback` block. Feedback is\nsubmitted to `POST /feedback`, contains no free text, and never includes a\nprivate key, prompt, URL, page content, or payment payload.\n\nThe three buyers accept:\n\n```text\n--feedback-reason <research_only|no_wallet|unsupported_network|insufficient_funds|spending_not_authorized|price|insufficient_value|integration_error|other>\n--feedback-stage <discovery|preflight|payment|execution|delivery>\n--feedback-intent <research|analyze_page|verify_conditions|general_question|evaluate_service|other>\n```\n\nWhen `--feedback-reason` is supplied without `--feedback-stage`, the stage\ndefaults to `payment` and the buyer does not authorize a payment. The HTTP\nbuyers first receive the unsigned 402 challenge, submit the explicit feedback,\nand stop. The MCP buyer stops after its free preflight and submits the explicit\nfeedback without requiring a wallet.\n\nExample: report that the price stopped an evaluation, without paying:\n\n```bash\nnpm run analyze -- \"https://example.com\" \"Summarize this page.\" --feedback-reason price --feedback-intent evaluate_service\n```\n\nTo submit explicit feedback after a completed delivery, select that stage:\n\n```bash\nnpm run mcp:consult -- \"Reply only with: MCP OK\" --feedback-reason other --feedback-stage delivery --feedback-intent general_question\n```\n\nBuyers automatically submit only `integration_error`, and only for an\nobjectively detected technical failure such as failed discovery/preflight, an\nHTTP 5xx result, a paid MCP tool error, or a missing settlement receipt after\na payment was made. They never infer `price`, `research_only`, `no_wallet`, or\nanother human or commercial motivation.\n\n## Controlled Smoke Test (No Payment)\n\nAfter deployment, validate discovery, preflight, the OpenAPI feedback contract,\nnormalized feedback submission, HTTP 402 challenges and feedback headers, HTTP\nmethod handling, MCP initialization, tool discovery and the MCP x402 challenge:\n\n```bash\nnpm run build\nnpm run smoke\n```\n\nUse `SERVICE_URL` to target another deployment. The test uses one persistent\n`x-journey-id`, sends `User-Agent: Diogo-Smoke/1.2.9`, verifies that the MCP\nx402 challenge advertises the public HTTPS endpoint with `type=mcp` and the\ncorrect `toolName`, and never creates or\nsigns a payment.\n\nThe three payment buyers now perform discovery and a free preflight before the\npaid request, using the same persistent journey ID throughout. Set `JOURNEY_ID`\nto reuse an existing journey; otherwise each buyer creates and prints one.\nThe MCP buyer additionally requires the exact advertised price, Base USDC,\nBase mainnet, and the configured service recipient before it can sign.\n\n## Funnel Observability\n\nThe server emits structured events for MCP tool attempts, x402 challenges,\npayment verification, execution, settlement and final tool outcome. It does\nnot log tool arguments or payment payloads. Settlement logs include the public\nnetwork and transaction identifier so completed purchases can be counted and\ndeduplicated.\n\nRejected MCP requests include safe protocol diagnostics such as method,\ncontent type, `Accept`, JSON-RPC shape and the SDK error classification. All\nevents include the request and journey correlation fields when available.\nCalls to a known paid tool that never reach its payment wrapper additionally\nemit `mcp_pre_payment_rejection`, classified as invalid method, content type,\nJSON-RPC envelope, arguments, transport/protocol rejection, or an otherwise\nunreached handler. Argument values and payment payloads are never logged.\nOpenAI usage events inherit the same request, journey, client, and source\ncorrelation. Railway's `X-Railway-Request-Id`, edge POP, and request-start time\nare also recorded, while client source fingerprints use Railway's stable\n`X-Real-IP` value and remain pseudonymized with `OBSERVABILITY_SALT`.\n\n## Deployment\n\nThe `main` branch is connected to Railway. Every successful push triggers a new deployment. Railway uses:\n\n```bash\nnpm run build\nnpm start\n```\n\nThe deployment health-check path is `/health`.\n\n## License\n\nISC\n",
  "bytes": 14541,
  "sha": "9820b01ea263ea890199b10daea762e240d4cb841898c5aea076b51f3d372732",
  "repo_slug": "diogoup26/mcp-x402",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_diogoup26_mcp_x402_b91ba48b/readme"
}