Configurar MCP

Instale e configure o servidor MCP do IronWallet para Cursor, Claude Code, ChatGPT e outros clientes MCP.

O servidor MCP do IronWallet (@ironwallet/mcp-server) fornece aos agentes de IA uma carteira de criptomoedas não custodial no seu computador. As frases de recuperação (seed phrases) são geradas e criptografadas localmente — elas nunca saem desta máquina e nunca passam pelo agente, pelo LLM ou pelos backends do IronWallet. Os agentes podem verificar saldos, exibir códigos QR de depósito, transferir tokens e realizar trocas (swaps) em 12 redes: Ethereum, BSC, Polygon, Base, Arbitrum, Optimism, Avalanche, Tron, Bitcoin, Solana, XRP e TON.

Não há interface de confirmação por transação — assim que você pede ao agente para enviar ou trocar, ele pode assinar e transmitir sem perguntar novamente. Use uma carteira quente (hot wallet) dedicada com saldo limitado, nunca sua carteira principal.

Requisitos: Node.js 20+ (npx). Apenas Desktop / stdio.

Recursos

Não custodial, assinatura local

As frases de recuperação permanecem criptografadas no host (permissões de arquivo apenas para o proprietário). As transações são assinadas nesta máquina; nenhuma ferramenta aceita ou retorna uma seed.

Carteiras no navegador local

Crie carteiras com create_wallets (retorna uma backup_url), ou importe e faça backup através do open_wallet_manager — uma página de loopback em 127.0.0.1 que é encerrada após 15 minutos de inatividade. Os segredos aparecem apenas nessa página do navegador, nunca no chat.

Transferências com estimativas de taxa

estimate_transfer visualiza a taxa sem transmitir; send_transfer assina localmente e envia; get_operation_status verifica o resultado. O servidor pode reduzir ligeiramente o valor para que a taxa caiba no saldo — a resposta indica quando isso acontece.

Trocas (swaps) baseadas em catálogo

list_swap_networks e list_swap_assets fornecem o catálogo de venda/compra para que o agente nunca invente endereços de token. estimate_swap cota, execute_swap executa em uma cotação nova, get_swap_status verifica o status.

Códigos QR de depósito

get_deposit_qr retorna um PNG para o chat mais um fallback de qr_url local.

Limites de gastos opcionais

Política por carteira via set_wallet_policy: readOnly, maxPerTxUsd e uma lista de permissão de destinatários. Desativado por padrão; aplica-se a envios e trocas. IW_READ_ONLY=true torna todo o servidor somente leitura.

Instalação

Opção 1: npx (recomendado)

Use npx para executar o servidor sem instalação global. Isso garante que você sempre use a versão mais recente.

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

O primeiro lançamento pode levar cerca de 30 segundos enquanto as dependências são instaladas. Se o seu cliente MCP expirar o tempo limite, execute o comando uma vez em um terminal para aquecer o cache e reconecte.

Opção 2: Instalação global

Instale o pacote globalmente para uma inicialização mais rápida e execute ironwallet-mcp.

npm install -g @ironwallet/mcp-server@latest

Guias de configuração

Apenas para desktop

Cada cliente possui uma URL estática dedicada (por exemplo, /ai/introduction/vscode/). Todos os comandos de instalação abaixo também estão incluídos nesta página — sem abas, nada escondido atrás de cliques.

Cursor

Mais recomendado

Abrir no Cursor

Instale uma vez. Depois disso, as ferramentas de carteira estarão disponíveis em todos os chats. Você também pode colar isso em ~/.cursor/mcp.json e reiniciar o Cursor.

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Reinicie o Cursor após a instalação para que o PATH inclua o npx.

Página independente para Cursor — uma requisição HTTP retorna apenas este guia.

Claude Code

Abrir no Claude Code

Execute estes comandos em ordem:

1claude plugin marketplace add ironwallet/ironwallet-agent-kit

2claude plugin install ironwallet-mcp@ironwallet

Após a instalação do plugin, aguarde cerca de 45 segundos e inicie um novo chat para que as ferramentas sejam carregadas.

Ou aponte o Claude Code diretamente para o servidor stdio:

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Página independente para Claude Code — uma requisição HTTP retorna apenas este guia.

VS Code

Abrir no VS Code

Abre o VS Code e registra o servidor MCP local. Você também pode adicionar isso às suas configurações de MCP do VS Code (usuário ou workspace).

2 "mcp": {

3 "servers": {

4 "ironwallet": {

5 "type": "stdio",

6 "command": "npx",

7 "args": ["-y", "@ironwallet/mcp-server"]

8 }

9 }

10 }

11}

Página independente para VS Code — uma requisição HTTP retorna apenas este guia.

ChatGPT

Abrir no ChatGPT

Execute estes comandos em ordem e reinicie para que as ferramentas MCP fiquem disponíveis.

1codex plugin marketplace add ironwallet/ironwallet-agent-kit

2codex plugin add ironwallet-mcp@ironwallet

Ou aponte o ChatGPT diretamente para o servidor stdio:

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Página independente para ChatGPT — uma requisição HTTP retorna apenas este guia.

Outros clientes

Use o transporte stdio. Aponte seu cliente MCP para:

2 "mcpServers": {

3 "ironwallet": {

4 "command": "npx",

5 "args": ["-y", "@ironwallet/mcp-server"]

6 }

7 }

Página independente para Outros clientes — uma requisição HTTP retorna apenas este guia.

Primeira execução e configuração da carteira

Não há login nem conta. No primeiro lançamento, o servidor gera seus segredos locais — uma chave de API de retransmissão, um segredo de encapsulamento de keystore e um ID de dispositivo — em ~/.ironwallet-mcp/ com permissões apenas para o proprietário. Nada a configurar.

Para começar a usar uma carteira:

Consentimento. Antes de criar ou importar uma carteira, o agente mostra o aviso de isenção de responsabilidade do MCP no chat e registra sua aceitação (accept_mcp_consent), ou você pressiona Continuar no gerenciador de carteiras.

Criar ou importar. create_wallets retorna nomes e endereços de carteira mais uma backup_url — abra-a em seu navegador para visualizar e fazer backup da frase de recuperação. Para importar uma carteira existente ou fazer um backup posteriormente, use open_wallet_manager. A frase de recuperação é digitada ou exibida apenas na página do navegador local, nunca no chat.

Financie a carteira. Peça ao agente um código QR de depósito (get_deposit_qr) ou um endereço (list_wallets) e envie uma pequena quantia. Mantenha o saldo limitado — esta é uma carteira quente.

Dados em disco

O servidor mantém seu estado em ~/.ironwallet-mcp/ (substituível com IW_KEYSTORE_DIR):

o keystore criptografado com as seeds da sua carteira,

o segredo de encapsulamento, a chave de API de retransmissão e o ID do dispositivo,

logs de diagnóstico em logs/ (o material da seed nunca é registrado).

Aviso: não exclua este diretório para "resetar" o servidor.

Ele contém as chaves criptografadas dos seus fundos. Se você removê-lo sem ter feito backup da frase de recuperação no gerenciador de carteiras, os fundos serão perdidos. Seu backup é a frase de recuperação, não estes arquivos.

Qualquer pessoa com o keystore e o segredo de encapsulamento controla os fundos, portanto, trate o diretório como sensível.

Variáveis de ambiente

A maioria dos usuários não precisa definir nenhuma variável de ambiente. O servidor gera e armazena tudo o que precisa no primeiro lançamento. As seguintes estão disponíveis para uso avançado:

Variável

Descrição

Padrão

IW_READ_ONLY

Rejeita send_transfer e execute_swap em todo o processo. Distinto da policy.readOnly por carteira

false

IW_KEYSTORE_DIR

Diretório do keystore

~/.ironwallet-mcp

IW_PASSPHRASE

Substitui o segredo de encapsulamento do keystore

generated locally

IW_RELAY_API_KEY

Substitui a chave de API de retransmissão

generated UUID

IW_HTTP_TIMEOUT_MS

Tempo limite geral de HTTP

15000

IW_HTTP_FORWARD_TIMEOUT_MS

Tempo limite para chamadas de transmissão. Um tempo limite do cliente nem sempre significa que a operação falhou — verifique o status

60000

IW_LOG_ENABLED

Diagnóstico JSONL para um arquivo de log (0 para desativar)

IW_LOG_LEVEL

debug / info / warn / error

info

Segurança

As seeds nunca saem desta máquina. Elas são criptografadas em repouso e nunca aparecem nos resultados das ferramentas, no chat do agente, nos logs ou nas solicitações de backend. Nenhuma ferramenta aceita ou retorna uma seed — a importação e o backup ocorrem apenas no navegador local.

O agente pode mover fundos sem perguntar novamente. Não há interface de confirmação por transação; sua mensagem no chat é a autorização. Transferências e trocas são irreversíveis após a transmissão.

Limites opcionais. Política por carteira (readOnly, maxPerTxUsd, lista de permissão de destinatários) via set_wallet_policy e IW_READ_ONLY=true em todo o servidor. Ambos estão desativados por padrão.

Apenas carteira quente. Não importe sua carteira principal ou de poupança. Qualquer pessoa com o keystore e o segredo de encapsulamento controla os fundos; uma seed vazada não pode ser revogada.

Tempo limite não é falha. Verifique get_operation_status / get_swap_status antes de tentar novamente um envio ou troca.

Todas as solicitações de backend usam HTTPS; arquivos de segredos locais usam permissões apenas para o proprietário (Unix 0600, ACL NTFS no Windows).

Divulgação de vulnerabilidades: SECURITY.md.

Testes

Teste o servidor diretamente usando o inspetor MCP. Isso abre uma interface web interativa onde você pode testar chamadas de ferramentas sem um assistente de IA.

npx @modelcontextprotocol/inspector npx -y @ironwallet/mcp-server

Solução de problemas

O cliente MCP expira o tempo limite na primeira inicialização

npx baixa o pacote na primeira execução, o que pode levar cerca de 30 segundos.

Execute npx -y @ironwallet/mcp-server uma vez em um terminal para aquecer o cache e reconecte.
Ou instale globalmente: npm install -g @ironwallet/mcp-server@latest.

As ferramentas não aparecem no cliente

Verifique se o Node.js 20+ está instalado: node --version.
Reinicie o cliente após a instalação para que o PATH inclua o npx.
Após a instalação de um plugin (Claude Code / ChatGPT), inicie um novo chat para que as ferramentas carreguem.
Verifique se o arquivo de configuração contém JSON válido e reinicie o cliente.
Teste o servidor manualmente com o inspetor MCP (veja Testes).

`create_wallets` retorna `needs_consent`

O aviso de isenção de responsabilidade do MCP ainda não foi aceito. Peça ao agente para mostrar o aviso completo e confirme (accept_mcp_consent), ou abra o gerenciador de carteiras e pressione Continuar.

Uma transferência ou troca expirou o tempo limite

Um tempo limite não é uma falha — a transação pode já ter sido transmitida. Verifique get_operation_status (transferências) ou get_swap_status (trocas) antes de tentar novamente. Nunca reenvie cegamente.

Um envio ou troca é rejeitado

Verifique list_wallets → policy: readOnly ou uma lista de permissão de destinatários pode estar bloqueando a operação. { enabled: false } significa sem limites.
maxPerTxUsd falha de forma segura: se nenhuma taxa em USD estiver disponível para o ativo, a operação é rejeitada.
Verifique se o servidor está sendo executado com IW_READ_ONLY=true.

Configurar MCP

Recursos

Instalação

Guias de configuração

Cursor

Claude Code

VS Code

ChatGPT

Outros clientes

Primeira execução e configuração da carteira

Dados em disco

Variáveis de ambiente

Segurança

Testes

Solução de problemas

O cliente MCP expira o tempo limite na primeira inicialização

As ferramentas não aparecem no cliente

create_wallets retorna needs_consent

Uma transferência ou troca expirou o tempo limite

Um envio ou troca é rejeitado

Relacionado

`create_wallets` retorna `needs_consent`