x402 Encontra MCP: Construindo um Servidor de Micropagamentos Autônomo para Agentes de IA

O protocolo de micropagamento HTTP x402 transforma um código de status HTTP 402 padrão em algo que um agente de IA pode realmente usar: um desafio de pagamento legível por máquina, uma nova tentativa assinada e um acerto em cadeia — tudo isso sem uma conta, um cartão de crédito ou um humano no meio. O projeto x402-mcp no GitHub envolve esse protocolo em um servidor de Protocolo de Contexto de Modelo (MCP) de produção, dando a qualquer cliente LLM compatível com MCP (Claude Desktop, Cursor, Windsurf ou um cliente HTTP remoto transmitível) um conjunto de 20 ferramentas para descobrir serviços pagos, sondar desafios 402, pagar por recursos protegidos e até monetizar suas próprias APIs.

Este artigo percorre a arquitetura real desse servidor — referenciando arquivos de origem reais, funções e decisões de design do repositório kwizzlesurp10-ctrl/x402-mcp — e mostra como o fluxo do protocolo x402 se mapeia para chamadas de ferramentas MCP que um agente pode executar autonomamente.

O Protocolo: O que o x402 Realmente Faz

Antes de mergulhar no servidor, vamos cobrir o fluxo x402 no nível do protocolo. O ciclo tem três etapas:

1. Descoberta: Um agente envia uma solicitação HTTP para um recurso. O servidor responde com 402 Pagamento Necessário e um cabeçalho PAYMENT-REQUIRED contendo um objeto PaymentRequired codificado em base64. Este objeto inclui o esquema de pagamento, rede (por exemplo, eip155:8453 para Base Mainnet), o endereço do destinatário, o valor em unidades atômicas de USDC e uma descrição do que está sendo vendido.

2. Autorização: O cliente x402 do agente analisa o desafio, verifica-o em relação às políticas de gasto locais (preço máximo, rede preferida), assina uma carga útil transferWithAuthorization EIP-3009 com sua chave privada e tenta novamente a solicitação original com um cabeçalho PAYMENT-SIGNATURE contendo a carga útil assinada.

3. Liquidação: O servidor encaminha a carga útil assinada para um facilitador (Coinbase CDP para mainnet, x402.org para testnet) que verifica a assinatura e envia a transferência on-chain. Se a liquidação for bem-sucedida, o servidor retorna o conteúdo junto com um cabeçalho PAYMENT-RESPONSE provando que os fundos foram movidos.

A percepção crítica: o agente nunca precisa de uma chave de API, um painel de cobrança ou uma conta pré-financiada com o vendedor. Ele precisa de uma carteira com USDC e da biblioteca cliente x402. É isso.

O Servidor: Arquitetura x402-mcp

O repositório é estruturado em torno de uma aplicação FastAPI (app/main.py) que serve tanto endpoints HTTP quanto um servidor FastMCP (app/mcp_server.py) expondo ferramentas sobre o protocolo MCP. Vamos percorrer os componentes principais.

Registro de Ferramentas MCP (app/mcp_server.py)

O servidor MCP é construído sobre o FastMCP com segurança de transporte configurada para permitir o próprio nome do host da implantação, enquanto mantém a proteção contra reatribuição de DNS habilitada. As ferramentas principais mapeiam diretamente para o fluxo do protocolo x402:

mcp = FastMCP(
    "x402-micropayments",
    instructions=(
        "Servidor MCP para micropagamentos HTTP x402. Descubra serviços pagos, "
        "sonde requisitos de pagamento 402, pague e busque recursos protegidos, "
        "construa/verifique configurações de pagamento do vendedor e atualize para Pro via x402. "
        "Rede de Conformidade de Dados Abertos da Cidade dos EUA: list_us_cities → "
        "get_us_city_property_sample → check_us_city_property (pago). "
        "Meta de comércio incluída em cada resposta."
    ),
    transport_security=_transport_security(),
)

Cada chamada de ferramenta passa por _execute_tool(), que faz duas coisas antes de executar o trabalho real: resolve a identidade do agente e verifica a cota (via quota_store.resolve_agent_id e quota_store.consume_quota), e após a conclusão do trabalho, emite um evento de operações e anexa um objeto meta com a captura instantânea da cota restante. Isso significa que cada resposta de ferramenta carrega metadados comerciais — o agente sempre sabe quantas chamadas de nível gratuito ele ainda tem.

As cinco ferramentas principais de comprador/vendedor são:

• discover_services — consulta o catálogo x402 Bazaar para serviços HTTP pagos, com filtragem opcional por texto de consulta e preço máximo
• get_payment_requirements — sondas qualquer URL em busca de um desafio 402 e decodifica os requisitos de pagamento
• pay_and_fetch — executa todo o fluxo x402: recebe 402, assina, tenta novamente, liquida, retorna conteúdo
• build_seller_requirements — gera um cabeçalho PAYMENT-REQUIRED para vendedores que desejam cobrar por seus próprios endpoints
• verify_payment_payload — verifica a PAYMENT-SIGNATURE de um comprador em relação a um desafio, para vendedores que executam sua própria liquidação

A Camada de Serviços x402 (app/x402_services.py)

Este arquivo de 1.039 linhas é o coração da implementação. Vamos olhar para as decisões de design mais interessantes.

Seleção de facilitador. O servidor suporta dois facilitadores: o facilitador gratuito x402.org (liquida apenas a rede de teste Base Sepolia) e o facilitador Coinbase CDP (liquida a Base Mainnet). A função _use_cdp() verifica se as credenciais do CDP estão configuradas e se a rede solicitada está na lista de redes do CDP:

def _use_cdp(network: str | None) -> bool:
    if not (settings.cdp_api_key_id and settings.cdp_api_key_secret):
        return False
    cdp_nets = {n.strip() for n in settings.cdp_networks.split(",") if n.strip()}
    return bool(cdp_nets.get(network))