x402 전체 프로세스 배포 가이드: AI Agent가 USDC로 귀하의 데이터에 대한 요금을 지불하도록 설정

〇 이 솔루션은 무엇인가

두 계층 프로토콜 모두 필수: 빠짐없이 적용되어야 함MCP AI 에이전트가 귀하의 도구를 인식하고 인터페이스를 통해 호출할 수 있도록 함(발견 계층);x402 에이전트가 데이터를 수신하기 전에 결제하도록 함(정산 계층, Base 메인넷 USDC). 구매자의 지갑에는 USDC만 있으면 됨.ETH가 필요하지 않습니다— gas는 facilitator가 대신 지불합니다(EIP-3009 무가스 승인). 계정 등록, API 키, Coinbase 계정 없이도 수취 가능합니다.

① 준비

• Python 실행이 가능한 서버 한 대(본 사이트는 텐센트 클라우드 2C4G Ubuntu 24.04 환경에서 구동됨)
• 하나 Base 메인넷 USDC 수령 주소(개인 비밀키를 직접 관리하는 주소)
• 도메인 하나 + HTTPS(에이전트 탐지 및 x402 모두 HTTPS 필수)
• 선택 사항: 검증용으로 Base 메인넷 USDC를 소량 충전한 테스트 구매자 지갑

의존성 설치

python3 -m venv venv && source venv/bin/activate
pip install "mcp<2" "x402==2.25.0" web3 httpx

② 서비스 서버 server.py 작성(핵심 골격)

import os
from mcp.server.fastmcp import FastMCP
from x402 import x402ResourceServer
from x402.http import FacilitatorConfig, HTTPFacilitatorClient
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.mcp import create_payment_wrapper
from x402.schemas.config import ResourceConfig

# 1. 链및 facilitator：Base 메인넷 + PayAI（免등록，支持 x402 v2 主网）
NETWORK = os.environ.get("X402_NETWORK", "eip155:8453")
FACILITATOR_URL = os.environ.get("X402_FACILITATOR",
                                 "https://facilitator.payai.network")

# 2. 收款地址：换成你自己의 Base 메인넷地址！别抄示例。
PAY_TO = os.environ.get("PAY_TO") or "0x你의收款地址"

# 3. 定价（按회，USD）
PRICE = {"my_data_tool": "$0.05"}

facilitator = HTTPFacilitatorClient(FacilitatorConfig(url=FACILITATOR_URL))
resource_server = x402ResourceServer(facilitator)
resource_server.register(NETWORK, ExactEvmServerScheme())
resource_server.initialize()
mcp = FastMCP("my-data-service")

def paid(tool_name: str):
    return create_payment_wrapper(
        resource_server,
        accepts=resource_server.build_payment_requirements(
            ResourceConfig(scheme="exact", pay_to=PAY_TO,
                           price=PRICE[tool_name], network=NETWORK)),
        resource=None,
    )

@mcp.tool(name="list_items")          # 무료도구：让 Agent 先看见你有货
def list_items() -> str:
    return '[{"name": "item-a"}]'

@mcp.tool(name="my_data_tool")        # 付费도구
@paid("my_data_tool")
def my_data_tool(item: str) -> str:
    return '{"item": "%s", "price": 1.24}' % item

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8797)

③ systemd 상주 설정

# /etc/systemd/system/x402.service
[Unit]
Description=My x402 paid MCP server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/my-x402
Environment=X402_NETWORK=eip155:8453
Environment=X402_FACILITATOR=https://facilitator.payai.network
Environment=PORT=8797
ExecStart=/opt/my-x402/venv/bin/python server.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
# systemctl daemon-reload && systemctl enable --now x402

④ nginx 역방향 프록시(/mcp)

location ^~ /mcp {
    proxy_pass http://127.0.0.1:8797;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;   # streamable-http 走 SSE，必须关缓冲
    proxy_cache off;
    proxy_read_timeout 300s;
}

⑤ 제로 비용 검증(실제 자금 사용 없이 설득력 있는 검증)

# 零비용验证（不花真钱）：不付款直接调付费도구，应返回 402 支付挑战
curl -s https://你의域名/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'
# 然后에서带 session id 의상태下调 tools/call（不带 X-PAYMENT），
# 响应의 accepts 里应看到：network=eip155:8453、asset=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913、
# payTo=你의地址、amount=50000（=$0.05）

⑥ 실제 자금 검증(USDC 충전 + 블록체인 기반 검증)

# 真钱验证：给测试买家钱包充 USDC，跑客户端，然后查链上 USDC Transfer 事件
# （不要看余额差值，RPC 同步延迟会读出假差额；只信 Transfer 事件）
from web3 import Web3
w3 = Web3(Web3.HTTPProvider("https://base-rpc.publicnode.com"))  # mainnet.base.org 会 429
USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
topic = w3.keccak(text="Transfer(address,address,uint256)").hex()
logs = w3.eth.get_logs({
    "fromBlock": w3.eth.block_number - 3000,
    "toBlock": "latest",
    "address": USDC,
    "topics": [topic,
               "0x" + "0"*24 + buyer[2:].lower(),
               "0x" + "0"*24 + seller[2:].lower()],
})
for lg in logs:
    print(int(lg["data"].hex(), 16) / 1e6, "USDC 已到账")

⑦ 타인이 귀하를 찾을 수 있도록 하기(디스커버리 계층)

• /.well-known/mcp.json 및 /.well-known/x402.json— 머신 리더블 형식의 도구 목록 및 요금표는 사이트 루트 디렉터리에 배치하세요.
• MCP 공식 Registry— GitHub Releases의 mcp-publisher 바이너리(npm에 등록된 동명 패키지가 아님— 해당 도메인은 위조입니다. 도메인 검증은 HTTP 파일 방식으로 진행되며, /.well-known/mcp-registry-auth 경로에 v=MCPv1 기록을 작성하면 되며, DNS 설정을 변경할 필요는 없습니다.
• llms.txt— MCP 엔드포인트 및 결제 방식을 명시하면 AI 크롤러가 자동으로 수집합니다.

우리가 실제로 겪은 7가지 함정(다른 곳에서는 찾아볼 수 없음)

본 문서의 실제 검증 사례(체인상에서 확인 가능)

자주 묻는 질문