Um servidor MCP de carteira Bitcoin para L1 e L2

Neste fim de semana, reuni um servidor MCP para uma carteira Bitcoin: ferramentas que os agentes de IA podem chamar através do Model Context Protocol. O repo expõe 93 ferramentas na Camada 1 e na Camada 2. Um mnemônico orienta ambas.

Anteriormente, fui gerente geral da Leather, uma carteira criptografada que também oferece suporte a Bitcoin e Stacks. Na Leather, vi que as carteiras de autocustódia voltadas para humanos atingiam principalmente pessoas dispostas a absorver a atenção e a complexidade (por exemplo, degens e desenvolvedores). Isso significava higiene fundamental, conscientização de taxas, fluxos de confirmação e muito mais. A carga cognitiva manteve estreito o mercado real endereçável.

As carteiras Agentic mudam isso. Quando a interface principal são agentes que raciocinam e executam dentro da política, o usuário aprova apenas o que importa. O atrito diminui e cresce o conjunto de pessoas que praticamente conseguem segurar as próprias chaves.

As mesmas duas cadeias. Superfície diferente.

O que o servidor expõe (L1 e L2 em uma superfície)

O servidor é um processo MCP único. Os clientes enviam nomes de ferramentas e argumentos JSON por stdio e recebem resultados estruturados. Ações destrutivas (envio, assinatura e transmissão, implantação) suportam dry_run e não são transmitidas por padrão. O servidor nunca retorna chaves ou mnemônicos.

Camada 1 (Bitcoin)

Bitcoin principal:

Derivação de endereços para P2PKH, P2SH-P2WPKH, P2WPKH e P2TR com chaves públicas e caminhos.
Contas com saldos por tipo de endereço (mempool.space para dados UTXO); saldo da carteira e preços BTC (USD, EUR).
Envios únicos e multi-destinatários (valor em BTC ou EUR); pré-visualize a transferência com estimativa de taxa antes de enviar.
Varredura (envio máximo) e consolidação UTXO.
Sinal PSBT, decodificação e sinal de lote; assinatura e verificação de mensagens (legado ECDSA e BIP-322).
Camadas de taxas de mempool.space e estimativa de taxas por contagem de entrada/saída e tipo de endereço.
Listagem UTXO com filtros (tipo de endereço, valor mínimo, somente confirmado) e detalhes por UTXO.

Ordinais e inscrições:

Listar inscrições com paginação; detalhes da inscrição (gênese, tipo de conteúdo, sat ordinal, raridade, localização).
Enviar inscrições (UTXO completo ou dividido para que apenas o intervalo sat da inscrição vá para o destinatário).
Extrair ordinais de UTXOs mistos; recuperar BTC do endereço ordinais (varrer UTXOs sem inscrição); recupere os ordinais que chegaram ao endereço de pagamento de volta ao endereço principal.
Crie inscrições únicas ou em lote com estimativas de taxas de confirmação/revelação.

Transações e gerenciamento de carteira:

Histórico de transações para BTC e Stacks; status para um único tx.
Acelerar BTC pendentes via RBF; cancelar BTC pendente (envio de RBF para si mesmo).
Configuração de rede e endpoints de API; alternar rede principal/rede de teste; adicione rede personalizada.
Liste todos os nomes e descrições de ferramentas suportadas.

Ledger (aplicativo Bitcoin):

Obtenha endereços BTC de um dispositivo Ledger conectado.
Assine PSBT com o aplicativo Ledger Bitcoin.

Camada 2 (pilhas)

O mesmo mnemônico deriva chaves Stacks (caminho m/44'/5757'/0'/0/0). Hiro Stacks API para dados em cadeia e transmissão.

Pilhas:

Endereços e chaves públicas; contas com saldo STX, valores bloqueados, nonces.
Saldo incluindo tokens fungíveis e não fungíveis.
Transferência STX (micro-STX) com memorando opcional; pré-visualização da transferência com taxa e verificação de saldo.
Transferências SIP-10 fungíveis e SIP-9 NFT por meio de chamadas contratuais.
Clareza: chamada de função pública, contrato de implantação, chamada somente leitura.
Assinar Stacks serializadas tx (SIP-30), assinar mensagem, assinar dados estruturados SIP-018; estimativa de nonce e taxa.
Atualização de perfil on-chain (schema.org/Person) para nomes BNS.
Consultas de transações com filtros (tipo, intervalo de blocos, não ancorados) e por contrato.
Mempool: lista transações pendentes, estatísticas de mempool, transações descartadas.
Explorador de blocos: blocos recentes, bloco por altura ou hash, empilha blocos para um determinado bloco Bitcoin.
Eventos de contrato: eventos para um contrato ou eventos de ativos para um endereço.
Metadados de token: metadados e titulares SIP-10 e SIP-9.
Informações da rede e saúde/status.

Swaps, DeFi e ponte:

Pares e protocolos suportados (ALEX, Bitflow, Velar).
Cotação de swap (produção estimada, taxa, taxas) para todos os três; execute a troca via ALEX DEX. Bitflow e Velar suportam cotações e descoberta de pares; você pode adicionar execução por meio de SDKs de protocolo (por exemplo, Velar SDK retorna parâmetros de chamada de contrato).
Troque o histórico da atividade na rede.
Saldo sBTC e informações de depósito/saque de ponte.
Empilhamento: status atual do PoX, informações do ciclo (blocos restantes, porcentagem concluída, tempo restante estimado, taxa de participação), iniciar empilhamento individual, revogar delegação.

BNS e dados de mercado:

Pesquisa BNS (nome para endereço), nomes pertencentes ao endereço, registro de nome BNS.
Preços de múltiplos ativos (por exemplo, CoinGecko); histórico de preços para gráficos.
Resumo do portfólio (BTC + STX em USD); todos os ativos e colecionáveis (inscrições, Stacks NFTs).

Ledger (aplicativo Stacks):

Obtenha endereços de Stacks do Ledger.
Assine a transação Stacks com o aplicativo Ledger Stacks.

Segurança e design

⚠️ Este servidor MCP é experimental e não é seguro para fundos significativos. Use apenas com carteiras que você está preparado para perder. Ninguém testou ou auditou o código. Eu trato isso como um artefato de pesquisa para explorar superfícies de carteiras nativas do agente.

As operações destrutivas são padronizadas como dry_run: true. Existem ferramentas de visualização e estimativa para cada caminho de envio. As chaves ficam fora do controle de versão e das respostas da ferramenta. O script de execução carrega .env da raiz do repositório.

Variáveis-chave da carteira (manter segredo, nunca confirmar):

BTC_PRIVATE_KEY — Chave privada Bitcoin codificada em WIF; se definido, tem precedência sobre o mnemônico.
BTC_MNEMONIC — Frase inicial BIP-39; o servidor o utiliza para derivar chaves Bitcoin e Stacks (mesmo mnemônico, caminho m/44'/5757'/0'/0/0 para Stacks).
BTC_MNEMONIC_PASSPHRASE — Senha BIP-39 opcional para usar com BTC_MNEMONIC.

Segurança e limites (env ou .env):

BTC_NETWORK — mainnet ou testnet (padrão testnet).
BTC_MAINNET_ENABLED — Defina isto para permitir envios mainnet (sinalizador de segurança).
BTC_DRY_RUN — Quando definido (padrão), operações destrutivas (envio, assinatura e transmissão, implantação) não são transmitidas; defina-o como false para permitir transações reais.
BTC_MAX_SEND_BTC — Limite opcional no valor de envio em BTC; o servidor rejeita solicitações acima disso.
BTC_MAX_FEE_SATS — Limite opcional de taxa em satoshis por transação.
STX_ACCOUNT_INDEX — Empilha o índice da conta de derivação (padrão 0).
Caso contrário, a configuração determina o nível de taxas (taxa fixa ou nível mempool.space: hora, meia hora, mais rápido).

Como isso se encaixa na minha pilha de agentes

Eu executo agentes em uma arquitetura de três camadas. As camadas são separadas de forma clara para que a memória, o raciocínio e a ação permaneçam no lugar certo.

Camada de verdade: Este é o substrato da memória. Ele contém dados digitados e estruturados: acervos, fluxos, transações, contatos, tarefas e o resto. Na minha configuração, o armazenamento canônico é Neotoma. Utiliza fontes e redutores de eventos, com procedência completa e resolução de entidade. Os agentes lêem isso. Eles nunca escrevem a verdade diretamente. Todas as atualizações fluem através de eventos de domínio produzidos pela camada de execução.

Camada de estratégia: É aqui que residem os objetivos, restrições e táticas. Documentos de estratégia, manuais táticos e manuais de operações estão aqui. Os agentes usam esta camada para raciocinar: eles leem o estado mundial, avaliam prioridades e riscos e produzem decisões e comandos. Estratégia é pura cognição. Sem efeitos colaterais. Estado dentro, decisões fora.

Camada de execução: É aqui que acontecem as ações externas. Ele recebe comandos da camada de estratégia e executa efeitos colaterais por meio de adaptadores: e-mail, calendário, DNS e, neste caso, a carteira Bitcoin e Stacks MCP. O servidor de carteira é um adaptador de execução entre muitos. Nunca altera a camada da verdade. Ele faz tudo (enviar, assinar, trocar) e o resto da pilha registra o que aconteceu por meio de eventos de domínio. Comandos entrando, eventos saindo.

Eu defino e mantenho a estratégia. Os agentes leem a camada de verdade e chamam as ferramentas MCP para execução. Eu não uso UIs criptográficas de apontar e clicar para operações de rotina. Eu só intervenho para aprovar ações que excedam meus limites predefinidos.

No curto prazo, meus casos de uso são pontuais: pagamento de serviços, reequilíbrio de portfólios por meio de solicitações manuais. A longo prazo, quero que esses fluxos sejam automatizados. Os agentes monitorariam, raciocinariam e executariam dentro da política. Eu veria explicações e aprovaria quando necessário.

Como estou abordando a construção

Primeiro, estou fazendo dogfood no servidor em meus próprios fluxos de trabalho. Estou testando cada superfície (envios, PSBTs, ordinais, transferências de pilhas, trocas) gradualmente com pequenas quantidades e simulações.

Eu o conectei na mesma pilha onde já uso camadas de verdade e estratégia. Os agentes podem combinar ações da carteira com calendário, e-mail e dados. Os usuários externos ainda não estão no escopo.

Meu objetivo é validar o formato de uma superfície de carteira de agente e tornar minhas próprias operações de Bitcoin e Stacks orientadas por agente em vez de manuais.

Para executá-lo: clone mcp-server-bitcoin (ou adicione como submódulo em mcp/btc_wallet/), adicione o servidor à sua configuração MCP (use o caminho de script run_btc_wallet_mcp.sh) e use uma carteira de teste com simulação ativada.

Principais conclusões