{
  "markdown": "# OnChainDiligence — MCP Server\n\n**Accountability infrastructure for consequential autonomous actions.**\nPayments are our first consequential action, not our definition of one.\n\nCurrent wedge: **agent commerce / payments.**\n\n> Know why your agent paid — and verify what happened afterward.\n> Keep your wallet. Keep your payment provider. Add OCD once.\n\nCore primitive: an **OCD Action Receipt**, backed by an **Agent Evidence\ngraph** — Mandate → Evidence → Policy → Decision → Execution →\nObservation/Reconciliation → Verifiable Receipt. Sanctions/company checks\n(Chainalysis, UK Companies House, SEC EDGAR) still exist and are fully\nsupported, but they are **Evidence Providers** — supporting capabilities the\nlifecycle can call on, not what the company is primarily about.\n\nThis repo is the **MCP server** — `mcp.onchaindiligence.com` — one of three\nrails ([HTTP API](https://api.onchaindiligence.com), Bazaar x402 routes, MCP)\nthat all produce the same signed evidence. Part of\n[onchaindiligence.com](https://onchaindiligence.com).\n\n---\n\n## 1. What OnChainDiligence is now\n\nThe original thesis: consequential autonomous actions should leave behind\nevidence that can be independently verified later. The current product wedge\nis agent commerce — an agent proposing, executing, and settling a payment —\nbecause that's where the evidence problem is sharpest and most valuable\ntoday. The same evidence graph (mandate, evidence, policy, decision,\nexecution, independent observation) generalizes beyond payments; payments\nare the first profile it's built for, not a permanent ceiling.\n\nOCD is **not** the wallet, the executor, or the payment provider. It never\nholds funds, never signs a payment, and never overrides your own\nwallet/provider's authorization. It evaluates proposed payments against your\npolicy, independently observes what actually settled, and issues a signed,\nindependently verifiable receipt reconciling the two.\n\n## 2. Agent payment lifecycle\n\n```\nMandate/Intent → Evidence → Policy → Decision → Execution → Observation/Reconciliation → Verifiable Receipt\n\n  inspect_payment (free, deterministic sanity-check)\n        │\n        ▼\n  preflight_payment ($0.01) ──► PREFLIGHT receipt (ALLOW / REQUIRE_APPROVAL / BLOCK)\n        │                         + one-time finalization capability\n        ▼\n  your own wallet/executor authorizes and submits the payment\n        │                         (OCD never holds a key or signs)\n        ▼\n  OCD independently observes settlement on-chain\n        │\n        ▼\n  finalize (free, using the capability) ──► Commerce Receipt\n                                             (execution + settlement, reconciled)\n```\n\nFull write-up: [`docs/PAYMENT_PREFLIGHT.md`](docs/PAYMENT_PREFLIGHT.md) and\n[`docs/COMMERCE_RECEIPTS.md`](docs/COMMERCE_RECEIPTS.md).\n\n## 3. Public/free verification MCP\n\n**`https://mcp.onchaindiligence.com/public/mcp`** — a separate, free,\nunauthenticated MCP surface, deliberately non-transactional. Three tools:\n\n| Tool | What it does |\n|---|---|\n| `inspect_payment` | Deterministic policy comparison only — ALLOW / REQUIRE_APPROVAL / BLOCK. No external lookups, signing, storage, or receipt. |\n| `get_receipt` | Retrieve a public, signed OCD receipt by its exact `receipt_id`. |\n| `verify_receipt` | Check a receipt's proof — VALID, INVALID, or UNVERIFIABLE. |\n\nThis surface **cannot** send payments, custody funds, authorize a wallet,\nreach private operations, or call the paid x402 tools below — it only\ninspects and verifies. No account, API key, or credential of any kind is\nneeded or accepted.\n\n**Live, validated Claude custom connector.** Add it in Claude at\n**Settings/Customize → Connectors → Add custom connector**, paste\n`https://mcp.onchaindiligence.com/public/mcp`, name it `OnChainDiligence`,\nleave authentication as **None** (transport is Streamable HTTP). It has been\nexercised through a real Claude host loop — tool discovery, tool selection,\nand correct interpretation of VALID/receipt content all confirmed. The same\nURL works with any Streamable HTTP MCP client, including ChatGPT's custom\nconnector setup, using the same steps.\n\nTry it against a real example receipt:\n[`OCD-RCP-NB51-QG4S-VCAN-Y57F`](https://onchaindiligence.com/r/OCD-RCP-NB51-QG4S-VCAN-Y57F).\n\n## 4. Paid x402 MCP / Evidence-Provider tools\n\n**`https://mcp.onchaindiligence.com/mcp`** — the paid surface, billed\nper-call in USDC on Base via [x402](https://x402.org). `tools/list` returns\n**nine** tools today: six priced Evidence-Provider/commerce tools, plus the\nsame three free tools from section 3 (also available here for convenience).\n\n| Tool | Description | Price |\n|------|-------------|-------|\n| `preflight_payment` | Evaluate a proposed payment against policy; issues a signed PREFLIGHT receipt + finalization capability. | $0.01 |\n| `screen_wallet` | Screen a wallet address against the Chainalysis on-chain sanctions oracle (US/EU/UN lists). | $0.01 |\n| `screen_name` | Fuzzy-match a person or company against OFAC SDN names and strong aliases. | $0.02 |\n| `verify_uk_company` | UK company lookup: status, type, incorporation, registered address, people with significant control. | $0.05 |\n| `verify_us_company` | Resolve a public US company through SEC EDGAR. | $0.05 |\n| `diligence` | Run wallet and UK-company checks in parallel, without claiming a verified link between them. | $0.05 |\n| `inspect_payment`, `get_receipt`, `verify_receipt` | Same as section 3 — free, no payment required, also reachable here. | free |\n\nPayment mechanics (unpaid call → x402 requirement → agent policy + wallet\nauthorization → paid retry → signed result) are unchanged from before — see\n[§ How payment works](#how-payment-works) below.\n\n*(This corrects [issue #4](https://github.com/Qazza1/onchaindiligence-mcp/issues/4): the README previously said \"five tools\" and didn't mention `preflight_payment`, `inspect_payment`, `get_receipt`, or `verify_receipt`, or that the last three are free.)*\n\n## 5. Commerce SDK\n\nFor a TypeScript application (as opposed to an MCP-connected chat agent),\n[`@onchaindiligence/sdk/commerce`](https://github.com/Qazza1/onchaindiligence-sdk)\norchestrates the full lifecycle in-process — open → preflight → execute →\nobserve/finalize — with the recovery guarantees above built in, rather than\nhand-rolling the MCP/x402 sequence:\n\n```ts\nimport { createCommerceClient, apiPurchasePolicy } from '@onchaindiligence/sdk/commerce'\nimport { NodeFileRecoveryStore } from '@onchaindiligence/sdk/commerce/node'\n\nconst ocd = createCommerceClient({ recovery: new NodeFileRecoveryStore('./ocd-recovery') })\nconst { policy } = apiPurchasePolicy({ maxAmount: '1.00', allowedNetwork: 'eip155:8453', allowedAsset: BASE_USDC })\n\nconst op = await ocd.open({ action: proposedPayment, policy })\nconst evaluation = await op.preflight()\nif (evaluation.kind !== 'allowed') return handleThat(evaluation)\n\nconst execution = await op.execute({ executor: myExecutor }) // your wallet/provider does the signing\nconst result = await op.observeAndFinalize() // safe to retry while kind === 'pending'\n```\n\nSee the SDK repo's README for the full executor list (`X402BaseUsdcExecutor`,\n`PayBoxCommerceExecutor`, `MockCommerceExecutor`) and the still-supported\nEvidence Provider client (`screen`, `screenName`, `verifyCompany`,\n`diligence`) — the SDK covers both.\n\n## 6. Receipts and verification\n\nEvery preflight and commerce receipt is a signed, content-addressed\n`OCD-RCP-XXXX-XXXX-XXXX-XXXX` object. Retrieve one for free with `get_receipt`\n(or `GET /receipts/:receiptId`); check it with `verify_receipt` (or the\n[public verifier](https://onchaindiligence.com/verify)) to get back\n**VALID / INVALID / UNVERIFIABLE**.\n\n- **Online verification** (`verify_receipt`) is a convenience: it fetches\n  OCD's own public key registry and trusts this server to have checked\n  honestly.\n- **Offline verification** is strictly stronger — run the same check\n  yourself against the published\n  [`@onchaindiligence/agent-evidence`](https://github.com/Qazza1/onchaindiligence)\n  package and your own copy of the key registry.\n\nSee section 10 for exactly what VALID does and doesn't mean.\n\n## 7. Current integrations: ChatGPT and Claude\n\nBoth are ordinary Streamable HTTP MCP clients — no special-casing on this\nserver's side. Point either at the free `/public/mcp` endpoint (section 3)\nfor read-only inspection/verification, or the paid `/mcp` endpoint (section\n4) for the full Evidence-Provider/commerce tool set.\n\n- **Claude** — add as a custom connector (see section 3). This has been\n  validated through a real Claude host loop: correct tool discovery, correct\n  tool selection, and correct interpretation of receipt content and VALID's\n  actual scope.\n- **ChatGPT** — register the same URL as a custom MCP connector; ChatGPT\n  calls `tools/list` and `tools/call` exactly like any other client.\n- **Gemini / a custom agent tool loop** — any Streamable HTTP MCP client\n  works unmodified; see [`test/client.ts`](./test/client.ts) for the exact\n  wire format.\n\nNeither integration implies a formal app-store/directory listing beyond what\neach platform's own directory pages state independently of this README.\n\n**The application layer that decides whether to act on a tool's result is\nthe real enforcement boundary — \"the model remembered to call OCD\" is never\na substitute for that.**\n\n## 8. Evidence Providers\n\nSupporting capabilities the lifecycle (or a caller directly) can draw\nevidence from — not the company's primary description:\n\n- **Chainalysis on-chain sanctions oracle** — a free, public smart contract\n  on Ethereum mainnet (`0x40C57923924B5c5c5455c48D93317139ADDaC8fb`), queried\n  read-only via [viem](https://viem.sh). No Chainalysis API key or\n  commercial relationship required; it's a public good reflecting US/EU/UN\n  sanctions lists. The per-call fee covers infrastructure, not the data.\n- **OFAC SDN name screening** — fuzzy match against primary names and strong\n  aliases only; weak AKAs are not screened, per OFAC guidance.\n- **UK Companies House** — official register lookup: status, type,\n  incorporation, registered office, people with significant control.\n- **SEC EDGAR** — public US company/fund resolution by ticker, CIK, or name.\n\nThese checks use the same underlying public-data sources as the\n[HTTP API](https://api.onchaindiligence.com) — separate deployments, so\nresponse-level equivalence is enforced by contract tests, not assumed.\n\n## 9. Architecture\n\n```\nagent (MCP client + x402 wallet, or Claude/ChatGPT as a custom connector)\n      │  Streamable HTTP\n      ▼\nindex.ts ──────────────── Hono app; routes /mcp and /public/mcp\n      │\n      ├── src/server.ts ────── paid handler: preflight_payment + 5 Evidence-\n      │                        Provider tools (x402-gated) + the same 3 free\n      │                        tools registered again for convenience\n      │\n      ├── src/publicMcp.ts ─── free handler: inspect_payment, get_receipt,\n      │                        verify_receipt only. Never imports or\n      │                        delegates to the paid handler.\n      │\n      ├── src/preflight.ts ──── deterministic policy evaluation\n      ├── src/receiptTools.ts ─ get_receipt / verify_receipt primitives,\n      │                         shared by both handlers and the free HTTP\n      │                         route (receiptsRoute.ts)\n      ├── src/chainalysis.ts ── sanctions oracle read (viem, Ethereum mainnet)\n      └── src/companiesHouse.ts ─ UK Companies House lookup\n```\n\n## 10. Security / claim limitations\n\n- **VALID means cryptographic integrity and authenticity of the receipt\n  under the verifier contract — not universal truth of every claim inside\n  it**, and not proof the underlying action succeeded.\n- **An OCD `ALLOW` is a policy comparison, not wallet authorization.** Your\n  own wallet/provider always makes the actual authorization decision.\n- **Settlement does not prove service/merchant delivery.** OCD independently\n  observes that value moved; it does not independently verify that whatever\n  was purchased was actually delivered.\n- **Caller-reported merchant evidence stays labeled as caller-reported** —\n  it is never silently upgraded to independently-observed evidence.\n- OCD is **not** a fraud detector and **not** a compliance guarantee. Its\n  checks are evidence-based tooling; using it does not by itself satisfy any\n  specific law, regulation, or compliance regime.\n- OCD does not claim a partnership, endorsement, or affiliation with any\n  executor, wallet provider, or platform beyond what that party has stated\n  independently.\n- **UNKNOWN and UNVERIFIED are preserved, never quietly resolved.** A\n  receipt that can't confirm something says so rather than defaulting to a\n  clean-looking result.\n\nFound a vulnerability? Report it to **security@onchaindiligence.com**. See\n[onchaindiligence.com/.well-known/security.txt](https://onchaindiligence.com/.well-known/security.txt).\n\n---\n\n## How payment works\n\nPayment rides on [x402](https://x402.org), the open agent-payment standard\nbuilt on HTTP `402 Payment Required`:\n\n1. The agent calls a tool with no payment attached.\n2. The server returns the payment requirements (amount, asset, recipient, network).\n3. The agent signs a USDC payment authorization from its own wallet.\n4. The agent retries the call with the payment in the tool-call `_meta`.\n5. The server verifies and settles via the Coinbase facilitator, runs the check, and returns the result.\n\nThe flow is **non-custodial**: USDC moves directly from the agent's wallet to\nthe recipient. This server never holds funds and runs no billing system —\ndeliberate, given the product is about *not* being a trusted intermediary.\n\n```ts\nconst client = await connectMcp('https://mcp.onchaindiligence.com/mcp')\nconst { tools } = await client.listTools()\n\nconst unpaid = await client.callTool({\n  name: 'screen_wallet',\n  arguments: { address: '0x0000000000000000000000000000000000000000' },\n})\nconst requirement = unpaid.structuredContent.accepts[0]\n// requirement contains the exact amount, USDC asset, Base network and recipient.\n\nconst payment = await createPaymentHeader(agentWallet, 1, requirement)\nconst paid = await client.callTool({\n  name: 'screen_wallet',\n  arguments: { address: '0x0000000000000000000000000000000000000000' },\n  _meta: { 'x402/payment': payment },\n})\n```\n\nThe runnable [`test/client.ts`](./test/client.ts) performs that exact\nsequence with `MCP_SERVER_URL` and `PAYER_PRIVATE_KEY` environment-variable\nplaceholders; it never embeds a wallet key in source. Always read the current\nprice from the unpaid response rather than hard-coding it.\n\n## Two payment rails by design\n\nOnChainDiligence settles two ways, because the agent-payment landscape is\nsplit between two standards:\n\n| | HTTP API | MCP server (this repo) |\n|---|---|---|\n| Protocol | Machine Payments Protocol (Stripe/Tempo) | x402 (Coinbase/Base) |\n| Chain | Tempo | Base mainnet |\n| Currency | pathUSD | USDC |\n| Settlement | session-based | per-call, on-chain |\n\nSame checks, same signed results, different rails for different ecosystems.\n\n## Standard HTTP x402 surface\n\nAlongside the MCP transport, every Evidence Provider check is also available\nto a generic x402 buyer over plain HTTPS, using the x402 **v2** stack\n(CAIP-2 networks, HTTP 402, `X-PAYMENT` header):\n\n| Resource | Price |\n|---|---|\n| `GET /x402/screen/:address` | $0.01 |\n| `GET /x402/screen-name?name=` | $0.02 |\n| `GET /x402/uk-company/:companyNumber` | $0.05 |\n| `GET /x402/us-company?q=` | $0.05 |\n| `GET /x402/diligence?wallet=&company=` | $0.05 |\n| `GET /x402/verdict/:address` | $0.01 |\n\nFree discovery documents: [`/openapi.json`](https://mcp.onchaindiligence.com/openapi.json)\nand [`/.well-known/x402`](https://mcp.onchaindiligence.com/.well-known/x402).\n\nBuyer walkthrough: [`docs/X402_HTTP_BUYERS.md`](docs/X402_HTTP_BUYERS.md).\nWhy the MCP rail is still on x402 v1, and what migrating it would require:\n[`docs/MCP_X402_MIGRATION.md`](docs/MCP_X402_MIGRATION.md).\n\n## Design notes\n\nA few decisions worth explaining, since they reflect real constraints rather\nthan preference:\n\n- **Why Base and not Tempo.** The HTTP API settles on Tempo, so unifying on\n  one chain would have been cleaner. But the `x402-mcp` package hardcodes its\n  network type to `\"base\" | \"base-sepolia\"` — Tempo is not a permitted value.\n  Rather than fork the package or write a custom facilitator, this server\n  settles on Base, and OnChainDiligence accepts two rails. The constraint is\n  documented, not papered over.\n- **The test client is hand-rolled.** `x402-mcp` ships a `withPayment`\n  helper, but it imports an MCP client API (`experimental_MCPClient`) that\n  the `ai` SDK removed in v5. Rather than pin an old `ai` version,\n  `test/client.ts` performs the x402 loop directly on the MCP SDK plus\n  `x402/client`. The server itself doesn't depend on `ai`, so this is a\n  test-only concern.\n- **Public-data clients are currently duplicated.** `chainalysis.ts` and\n  `companiesHouse.ts` began as copies of the HTTP API implementations. They\n  can drift, so the remediation roadmap moves them behind a shared\n  service/package and adds contract tests.\n\n## Running locally\n\nRequires Node 22+.\n\n```bash\nnpm install\ncp .env.example .env   # fill in the values below\nnpm run dev            # serves http://localhost:3000/mcp and /public/mcp\n```\n\nEnvironment variables:\n\n| Variable | Purpose |\n|----------|---------|\n| `COMPANIES_HOUSE_API_KEY` | UK Companies House API key (free). |\n| `SANCTIONS_ORACLE_RPC_URL` | Ethereum RPC for the oracle read. |\n| `X402_RECIPIENT_ADDRESS` | Base address that receives USDC. |\n| `X402_NETWORK` | `base-sepolia` (testnet) or `base` (mainnet). |\n| `CDP_API_KEY_ID` / `CDP_API_KEY_SECRET` | Coinbase Developer Platform keys for the x402 facilitator. |\n| `ATTESTATION_SERVICE_TOKEN` | Server-to-server credential for the API's internal attestation service. Required for signed results; never expose it to browser code. |\n\nTo exercise the full paid loop against the running server:\n\n```bash\n# in .env, also set PAYER_PRIVATE_KEY to a wallet funded with testnet USDC + ETH\nnpm run test:client\n```\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 18137,
  "sha": "255ca70634c9973b926b28e65d272739a755e015c4fd11674c523c6285d0f389",
  "repo_slug": "qazza1/onchaindiligence-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_onchaindiligence_compliance_a084f2f4/readme"
}