arcagents-mcp

Arc Agents MCP

O que é Arc Agents MCP?

Arc Agents MCP é um servidor padrão do Model Context Protocol (MCP) que concede a assistentes de IA acesso a dados de agentes ERC-8004 na Arc Mainnet. ERC-8004 é um padrão de registro onchain para identidade, reputação e validação de agentes.

O servidor lê da API paga do Arc ERC-8004 Explorer - a plataforma Arc Agents - em https://www.arcagents.app. Ele expõe uma ferramenta, get_agent_data, e paga por cada requisição automaticamente a partir de uma carteira controlada pelo usuário.

Início Rápido

O usuário (não você) conecta o servidor adicionando-o à sua configuração do cliente MCP. O comando de inicialização é:

npx -y [email protected]

Requisitos:

• Node.js 20 ou mais recente.
• Uma chave privada de carteira EVM, fornecida como a variável de ambiente EVM_PRIVATE_KEY (0x seguido de 64 caracteres hexadecimais). Ela assina o pagamento para cada requisição. Recomenda-se uma carteira dedicada contendo apenas um pequeno saldo de USDC, nunca a carteira principal do usuário.
• Opcional: ARCAGENTS_PAYMENT_NETWORK=arc|base seleciona qual rede paga pelas requisições. O padrão é arc.

Exemplo de bloco de configuração (a maioria dos clientes usa este formato mcpServers; o placeholder deve ser substituído pelo usuário, em seu próprio arquivo de configuração):

{
  "mcpServers": {
    "arcagents": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "EVM_PRIVATE_KEY": "YOUR_EVM_PRIVATE_KEY",
        "ARCAGENTS_PAYMENT_NETWORK": "arc"
      }
    }
  }
}

Regras para você:

• Nunca peça ao usuário para colar, digitar ou revelar uma chave privada no chat. Se uma chave aparecer na conversa, não a repita e informe ao usuário para trocá-la.
• Direcione o usuário para o README do projeto para configuração por cliente: https://github.com/Nomad07/arcagents-mcp
• Se a ferramenta get_agent_data não estiver disponível, informe ao usuário que o servidor não está conectado e compartilhe as etapas de configuração acima. Não tente obter os dados de outra forma e apresentá-los como vindos desta ferramenta.

Ferramenta Disponível

get_agent_data

• Entrada: agentId, um inteiro positivo: o ID do agente ERC-8004 (token ID), por exemplo 15.
• Comportamento: recupera as informações ERC-8004 daquele agente da Arc Mainnet e retorna a resposta JSON da API.
• Custo: $0,002 USDC por requisição bem-sucedida.

Valide a entrada antes de chamar: o ID deve ser um número inteiro positivo. Não adivinhe IDs. Pergunte ao usuário se nenhum ID foi fornecido.

Cada chamada custa dinheiro. Não chame a ferramenta repetidamente "para verificar" ou em loops em lote, a menos que o usuário tenha solicitado. Reutilize dados já retornados na conversa em vez de buscá-los novamente.

A API paga atende apenas a Arc Mainnet. Não afirme ou sugira que ela lê Arc Testnet, Base ou qualquer outra rede. Base é apenas uma possível rede de pagamento.

Dados Disponíveis

A resposta pode incluir o seguinte. Relate apenas o que está realmente presente na resposta.

• Identidade e registro: agentId, network, chainId e os endereços dos registros de identidade, reputação e validação.
• Proprietário e carteira do agente: o endereço do proprietário e a carteira do agente designada.
• Metadados: o URI dos metadados (IPFS ou HTTPS) e os metadados analisados quando puderam ser buscados: nome, descrição, serviços, active, x402Support. Se os metadados não puderam ser buscados, metadata é nulo e metadataError explica o motivo.
• Reputação: número de clientes, número de feedbacks, pontuação agregada, clientes e registros individuais de feedback (cliente, índice, valor, tags, isRevoked).
• Validação: se os dados de validação estão disponíveis, um motivo quando não estão, o número de requisições e as requisições e respostas de validação quando existem.
• Links e timestamp: links para o agente no Arc ERC-8004 Explorer e o horário de fetchedAt.

Alguns campos podem estar indisponíveis. Dependendo do agente e dos contratos de registro implantados, valores podem ser nulos, vazios ou ausentes, e dados de validação podem estar totalmente ausentes. Isso é normal. Diga que um campo está indisponível; nunca o preencha.

Após uma chamada paga bem-sucedida, o servidor pode adicionar um segundo bloco de texto com o hash da transação de pagamento e o link para o explorador. O primeiro bloco é sempre o JSON da API.

Exemplos de Uso

Recuperar dados de um agente

"Obtenha os dados ERC-8004 do agente 15." Chame get_agent_data com agentId: 15, depois apresente os campos principais.

Explicar registro e metadados

"O que é o agente 8 e como ele está registrado?" Chame a ferramenta, depois explique proprietário, carteira do agente, URI de metadados e registros. Descreva serviços apenas se eles estiverem nos metadados. Se metadataError estiver definido, relate-o em vez de adivinhar o que os metadados dizem.

Resumir feedback de reputação

"Como o agente 14 é avaliado?" Relate clientCount, feedbackCount, aggregateScore e um breve resumo dos registros de feedback, observando entradas revogadas. Se não houver feedback, diga isso.

Comparar dois agentes

"Compare o agente 1 e o agente 8." Faça uma chamada por ID (duas requisições pagas; informe o usuário), depois compare os mesmos campos lado a lado. Se um campo existir para um agente mas não para o outro, diga isso, em vez de tratar dados ausentes como zero.

Identificar informações ausentes

"O que não sabemos sobre o agente 22?" Após a chamada, liste os campos que são nulos, vazios ou marcados como indisponíveis, como metadata, validation.available e seu reason. Declare claramente que estão indisponíveis e não infira valores.

Ao responder, distinga o que a API retornou de sua própria interpretação e mencione que os dados vêm da Arc Mainnet a partir de fetchedAt.

Pagamentos

• Protocolo: x402 versão 2, esquema exact (uma autorização de transferência EIP-3009), liquidada através do facilitador Ultravioleta DAO.
• Preço: $0,002 USDC (2000 unidades atômicas, 6 decimais) por requisição bem-sucedida. Não há assinaturas ou taxas mensais.
• Redes de pagamento suportadas:
  • Arc Mainnet (eip155:5042), a padrão
  • Base Mainnet (eip155:8453)
• Como funciona: o desafio de pagamento da API lista as opções aceitas. O servidor seleciona exatamente uma, correspondendo a ARCAGENTS_PAYMENT_NETWORK, e paga diretamente ao destinatário especificado por esse requisito de pagamento. Ele verifica o token, o valor e o domínio de assinatura antes de assinar. Ele nunca muda para a outra rede após uma falha.
• Suporte ao protocolo de pagamento: x402 apenas. Não descreva nenhum outro protocolo de pagamento, incluindo MPP, como suportado.
• A carteira pagadora precisa de USDC na rede selecionada. O usuário não precisa de tokens de gás nativos para o pagamento.

Segurança de Pagamento e Tratamento de Erros

• Nunca peça ao usuário para divulgar sua chave privada e nunca inclua uma em chamadas de ferramenta, arquivos ou mensagens.
• Nunca repita uma requisição paga criando um novo pagamento quando o resultado anterior for incerto. Não tente contornar erros alterando redes, carteiras ou configurações no meio de uma requisição.
• O servidor salva o estado de pagamento pendente localmente (em ~/.arcagents-mcp, ou ARCAGENTS_STATE_DIR) antes de enviar um pagamento assinado. Se uma requisição for interrompida, perguntar novamente pelo mesmo ID de agente a retoma: o servidor reenvia o pagamento assinado idêntico e não assina um novo. Isso também funciona após o servidor MCP reiniciar.
• 503, timeout ou resposta incompleta significa que pode não haver resultado final ainda. Relate isso ao usuário, respeite qualquer valor Retry-After e, após esse atraso, chame get_agent_data novamente com o mesmo agentId. O servidor retoma o mesmo contexto de pagamento em vez de pagar duas vezes. Não repita em loop apertado.
• Conflito 409 (a autorização já foi usada ou pertence a outra requisição) não deve acionar uma nova autorização. Relate o reason na resposta conforme fornecido: authorization_already_settled significa que o facilitador relata que a autorização já foi usada com seu pagamento confirmado; receipt_request_conflict significa que pertence a outra requisição, e a API não informa se esse pagamento foi liquidado. Não adivinhe qual. O servidor mantém o pagamento assinado existente e não criará um novo para esse ID de agente.
• 402 após pagamento significa que a API não aceitou o pagamento. Relate o motivo fornecido na resposta. É uma resposta final, portanto, perguntar novamente inicia uma nova requisição.
• 500 significa que a liquidação falhou ou não pôde ser confirmada. Não assine ou solicite um novo pagamento; informe o usuário e repasse qualquer hash de transação na resposta. Perguntar novamente pelo mesmo ID de agente apenas reenvia o mesmo pagamento assinado.
• 404 significa que o ID do agente não foi mintado na Arc Mainnet; a requisição não é cobrada.
• Uma mensagem como "outro processo já detém um pagamento assinado não resolvido" é um conflito temporário. Apenas um processo pode reivindicar e enviar um pagamento para uma requisição, e o processo concorrente não envia nada. Pergunte novamente mais tarde; o pagamento existente é reutilizado.
• Não afirme que uma requisição foi gratuita, não paga ou não cobrada quando seu resultado de pagamento for incerto. Diga que o resultado não pôde ser determinado e o que a resposta afirma.
• Não invente dados de agente, hashes de transação, saldos ou resultados de pagamento. Se a ferramenta retornar um erro, cite o erro e sua orientação em vez de parafraseá-lo em algo mais otimista.

Limitações

• Os dados da API paga cobrem apenas agentes da Arc Mainnet.
• A testnet está disponível na interface do Arc ERC-8004 Explorer, mas não através da API paga ou deste servidor MCP.
• Os dados de validação dependem da disponibilidade do registro e podem estar ausentes.
• Atividade do agente não está disponível atualmente através desta API.
• A ferramenta retorna dados para um ID de agente por chamada; não há endpoint de busca, listagem ou lote.
• As respostas refletem o momento de fetchedAt e não são atualizadas ao vivo.

Recursos

• Arc ERC-8004 Explorer: https://www.arcagents.app
• Especificação OpenAPI: https://www.arcagents.app/api/openapi.json
• Repositório MCP (configuração para cada cliente, configuração, solução de problemas): https://github.com/Nomad07/arcagents-mcp