MCP 위의 Blockchain0x.
모든 MCP 호스트 - Claude Desktop, Cursor, VS Code -에 하나의 구성 블록으로 에이전트 지갑 도구를 제공합니다. 그리고 자신의 도구에 대해 요금을 부과하고 싶을 때는 실제 requirePayment x402 빌더를 사용하세요.
@blockchain0x/mcp 서버는 MCP 호스트에 다섯 개의 에이전트-지갑 도구를 제공합니다: 지갑 읽기, 지갑 목록, 거래 확인, USDC 결제 전송 및 x402 송장 정산. npx @blockchain0x/mcp로 실행하십시오(키는 귀하의 머신에 남아 있습니다) 또는 호스팅된 URL을 가리키십시오. 별도로, 이 패키지는 requirePayment를 내보내어 x402 402 챌린지로 자신의 MCP 도구에 가격을 매길 수 있습니다.
MCP를 통해 지출하십시오. MCP를 통해 청구하십시오.
첫 번째 작업: 에이전트가 호스트 내에서 지갑을 사용하도록 하세요. @blockchain0x/mcp 서버는 @blockchain0x/node SDK에 대한 얇고 상태 비저장 프록시입니다. Claude Desktop, Cursor 또는 VS Code에 다섯 개의 지갑 도구를 노출하며, API 키의 범위, 할당량 및 주기별 한도는 다른 API 호출과 동일하게 백엔드에 의해 시행됩니다. 서버는 키를 보유하지 않으며, 아무것도 저장하지 않습니다.
두 번째 작업: 에이전트가 귀하의 도구를 호출하는 데 요금을 부과하세요. MCP는 도구 호출을 마찰 없이 만들어 주었지만, 서버가 무료로 이그레스, 토큰 및 제3자 API 비용을 소모하는 것은 좋지 않습니다. 402 Payment Required 패턴이 여기에서 정확히 맞습니다. requirePayment는 호스팅된 체크아웃 URL과 함께 구조화된 x402 챌린지를 생성합니다; 도구가 결제되지 않았을 때 이를 반환하고 결제가 정산되면 호출을 허용합니다. x402를 이해하는 클라이언트는 자동으로 결제하며, 나머지는 URL을 인간에게 표시합니다.
실행하는 두 가지 방법. 호스팅된 것에 대한 설치가 필요 없습니다.
npx를 사용하여 stdio를 통해 로컬에서 실행하거나, 호스팅된 스트리머블 HTTP URL에 MCP 호스트를 지정하고 키를 Bearer 토큰으로 전달하세요. 두 가지 모두 호스트의 MCP 구성에 직접 추가됩니다. 로컬 경로는 Node 20+를 요구합니다.
{ "mcpServers": { "blockchain0x": { "command": "npx", "args": ["-y", "@blockchain0x/mcp"], "env": { "BLOCKCHAIN0X_API_KEY": "sk_live_...", "BLOCKCHAIN0X_API_BASE_URL": "https://api.blockchain0x.com" } } } }
{ "mcpServers": { "blockchain0x": { "url": "https://mcp.blockchain0x.com/mcp", "headers": { "Authorization": "Bearer sk_live_..." } } } }
BLOCKCHAIN0X_API_KEY는 귀하의 대시보드에서 가져온 sk_test_ 테스트넷 또는 sk_live_ 메인넷 키입니다; BLOCKCHAIN0X_API_BASE_URL의 기본값은 https://api.blockchain0x.com입니다. 서버는 귀하의 키를 백엔드로 전달하고 아무것도 저장하지 않으므로, 해당 키의 범위와 한도는 에이전트가 할 수 있는 것과 정확히 일치합니다. 노출되는 다섯 가지 도구: get_wallet, list_wallets, get_transaction, send_payment 및 settle_payment_request.
실제 requirePayment 빌더로 도구를 게이트하세요.
requirePayment는 @blockchain0x/mcp의 순수 함수입니다. 도구가 미지급 상태일 때 호출하면 x402 402 챌린지(가격, 귀하의 지갑, 호스팅된 체크아웃 URL)를 생성하고, 그 본문을 표준 MCP 오류 형태로 반환합니다. 이는 귀하의 핸들러를 래핑하지 않으며 누가 지불했는지 추적하지 않습니다 - 그 부분은 귀하의 몫입니다. 이는 헬퍼를 작고 정직하게 유지합니다.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { requirePayment } from "@blockchain0x/mcp"; import { z } from "zod"; const server = new McpServer({ name: "docs-search-mcp", version: "1.0.0" }); server.tool( "search_docs", "Semantic search across our private docs", { query: z.string() }, async ({ query }, extra) => { if (!hasPaid(extra)) { // Mint an x402 402 challenge and hand it back to the caller. const { body } = requirePayment({ amountUsdc: "0.10", payTo: "0xYourWallet", hostedUrl: "https://pay.blockchain0x.com/checkout/abc", }); return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true }; } const results = await runVectorSearch(query); return { content: [{ type: "text", text: JSON.stringify(results) }] }; }, );
에이전트가 search_docs unpaid를 호출하면 402 본문을 받습니다. x402를 사용하는 클라이언트는 이를 자동으로 결제합니다; Claude Desktop과 Cursor는 인간을 위한 체크아웃 URL을 표시합니다. 결제가 완료되면 해당 호출자를 결제된 것으로 표시하고(다음 섹션) 호출이 진행됩니다. MCP 서버보다 일반 HTTP 서버를 선호하십니까? 수신 측 x402 어댑터 - Express의 createX402Middleware, Fastify의 createX402Plugin -는 프레임워크 계층에서 동일한 게이팅을 수행합니다.
웹훅이 도착하면 호출자를 결제 완료로 표시하세요.
결제가 완료되면 Blockchain0x가 귀하의 웹훅 URL에 서명된 payment.received 이벤트를 POST합니다. Node SDK의 webhooks.verify로 이를 검증한 후, 호출자가 귀하가 이미 운영하는 저장소에서 결제된 것으로 기록합니다. 구성할 수 있는 배포된 영수증 캐시는 없으며 - 해당 부분은 귀하가 소유하므로 놀라운 인프라가 없습니다.
import express from "express"; import { webhooks } from "@blockchain0x/node"; const app = express(); // Capture the RAW body. The HMAC is over the exact bytes on the wire. app.use(express.raw({ type: "application/json" })); app.post("/webhooks/payment", (req, res) => { const result = webhooks.verify({ headers: req.headers, rawBody: req.body, // Buffer, raw bytes secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!, }); if (!result.ok) return res.status(400).json({ code: result.code }); if (result.eventType === "payment.received") { // Mark this payer paid however you like - a DB row, a Redis key, your call. markPaid(result.eventId); } res.status(200).send("ok"); });
webhooks.verify는 일정한 시간에 HMAC-SHA256을 수행하고 구분된 유니온을 반환하므로, result.ok에 따라 분기하고 try/catch 없이 원본 본문을 읽습니다. 구문 분석된 복사본이 아니라 원본 본문을 읽으세요, 서명이 정확한 바이트를 포함하기 때문입니다. 발송된 이벤트는 payment.received, payment.sent, wallet.deployed, 및 webhook.test입니다; 귀하의 지갑에 대한 결제는 payment.received입니다. '이 호출자가 지불했다'는 것을 지속하는 위치 - 데이터베이스의 행, Redis 키, 단일 프로세스를 위한 메모리 내 맵 - 는 귀하의 선택입니다.
서버는 공개되어 있으며 무상태입니다. 읽어보십시오.
MCP 서버와 requirePayment builder는 database와 volume이 없는 Node SDK 위의 얇은 pass-through이므로, 감사할 것이 많지 않습니다 - 그것이 핵심입니다. native MCP OAuth 2.1은 예정된 후속 작업이며, pasted-key 경로가 먼저 출시됩니다. 기존 API-key trust model을 그대로 재사용하기 때문입니다.
github.com/tosh-labs/blockchain0x-node전체 도구 목록, scope, 그리고 hosted environment URL은 the docs에 문서화되어 있습니다. 실제 키를 연결하기 전에 테스트할 수 있도록 production과 함께 staging 및 dev hosted endpoint가 제공됩니다.
MCP에 특화된 피해야 할 다섯 가지 함정.
이것들은 유료 MCP 서버를 운영하는 운영자들로부터 나옵니다. 대부분은 캐시 아키텍처 및 MCP 프로토콜의 특정 오류 형식과 관련이 있습니다.
requirePayment는 빌더이며 미들웨어가 아닙니다.
requirePayment는 순수 함수입니다: 호출하면 { status: 402, body }를 반환하고, 도구가 미지급 상태일 때 그 본문을 반환합니다. 이는 귀하의 핸들러를 래핑하지 않으며 누가 지불했는지 추적하지 않으며 이유나 캐시 창 옵션을 받지 않습니다 - 단지 amountUsdc, payTo, hostedUrl, 및 선택적 네트워크와 설명만 받습니다. 결제 상태 추적은 귀하의 작업입니다: 데이터베이스의 행, 귀하의 Redis의 키, 또는 적합한 것을 사용하세요. Blockchain0x는 챌린지 빌더와 정산 웹훅을 제공하며, 영수증 캐시는 제공하지 않습니다.
stdio는 귀하의 키를 귀하의 기계에 유지합니다.
npx와 환경에 BLOCKCHAIN0X_API_KEY를 사용하여 서버를 실행하면 키는 절대 귀하의 박스를 떠나지 않습니다 - 로컬에서 읽히며, 네트워크 헤더로 전송되지 않습니다. 호스팅된 URL는 반대 거래입니다: 설치가 필요 없지만, 키를 Bearer 토큰으로 mcp.blockchain0x.com에 붙여넣습니다. 개발자의 개인 기계에는 stdio를 선택하고, 공유 배포를 위해 호스팅된 것을 선택하세요.
대시보드 전용 표면은 노출되지 않습니다.
서버는 @blockchain0x/node에 대한 얇고 무상태의 프록시입니다. 정확히 다섯 개의 도구를 제공합니다: get_wallet, list_wallets, get_transaction, send_payment, settle_payment_request. 신원 변경, API 키 및 웹훅 CRUD, 인출 및 청구는 API 키 인증 하에 강력하게 차단되며 서버는 SDK를 넘어서는 접근을 하지 않습니다. 이러한 도구를 기대하지 마십시오 - 이는 설계상 대시보드에 존재합니다.
send_payment는 멱등성이 있으며 재시도하지 않습니다.
The send_payment tool wraps payments.create: it auto-mints an Idempotency-Key so a retried call collapses to one transfer, and it does not retry on its own. It can also answer 503 until the chain adapter is wired for your network. If the model gets a 503, do not let it hammer the tool - surface the state and move on. amountWei is USDC base units (6 decimals), so 0.01 USDC is the string "10000".
requirePayment의 amountUsdc는 6자리 소수 문자열입니다.
requirePayment validates amountUsdc as a USDC decimal with at most six fractional digits, so "0.10" is fine and "0.1234567" throws. payTo and hostedUrl are required; network defaults to mainnet. Keep the hostedUrl pointing at a real checkout you control (the pattern is https://pay.blockchain0x.com/checkout/<id>). A malformed amount fails fast rather than minting a broken challenge.