arcagents-mcp

Arc Agents MCP

¿Qué es Arc Agents MCP?

Arc Agents MCP es un servidor estándar del Protocolo de Contexto del Modelo (MCP) que brinda a los asistentes de IA acceso a los datos de agentes ERC-8004 en Arc Mainnet. ERC-8004 es un estándar de registro en cadena para la identidad, reputación y validación de agentes.

El servidor lee de la API de pago de Arc ERC-8004 Explorer - la plataforma Arc Agents - en https://www.arcagents.app. Expone una herramienta, get_agent_data, y paga por cada solicitud automáticamente desde una wallet que el usuario controla.

Inicio rápido

El usuario (no tú) conecta el servidor agregándolo a su configuración del cliente MCP. El comando de lanzamiento es:

npx -y [email protected]

Requisitos:

• Node.js 20 o más reciente.
• Una clave privada de wallet EVM, proporcionada como la variable de entorno EVM_PRIVATE_KEY (0x seguida de 64 caracteres hexadecimales). Firma el pago de cada solicitud. Se recomienda una wallet dedicada que solo tenga un saldo pequeño de USDC, nunca la wallet principal del usuario.
• Opcional: ARCAGENTS_PAYMENT_NETWORK=arc|base selecciona qué red paga las solicitudes. El valor predeterminado es arc.

Ejemplo de bloque de configuración (la mayoría de los clientes usan esta forma mcpServers; el marcador de posición debe ser reemplazado por el usuario, en su propio archivo de configuración):

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

Reglas para ti:

• Nunca le pidas al usuario que pegue, escriba o revele una clave privada en el chat. Si aparece una clave en la conversación, no la repitas e indícale al usuario que la rote.
• Dirige al usuario al README del proyecto para la configuración por cliente: https://github.com/Nomad07/arcagents-mcp
• Si la herramienta get_agent_data no está disponible, dile al usuario que el servidor no está conectado y comparte los pasos de configuración anteriores. No intentes obtener los datos de otra manera y presentarlos como provenientes de esta herramienta.

Herramienta disponible

get_agent_data

• Entrada: agentId, un número entero positivo: el ID del agente ERC-8004 (ID del token), por ejemplo 15.
• Comportamiento: recupera la información ERC-8004 de ese agente de Arc Mainnet y devuelve la respuesta JSON de la API.
• Costo: $0.002 USDC por solicitud exitosa.

Valida la entrada antes de llamar: el ID debe ser un número entero positivo. No adivines IDs. Pregunta al usuario si no se proporcionó ningún ID.

Cada llamada cuesta dinero. No llames a la herramienta repetidamente "para comprobar" o en bucles masivos a menos que el usuario lo haya solicitado. Reutiliza los datos ya devueltos en la conversación en lugar de obtenerlos de nuevo.

La API de pago solo sirve a Arc Mainnet. No afirmes ni des a entender que lee Arc Testnet, Base o cualquier otra red. Base es solo una posible red de pago.

Datos disponibles

La respuesta puede incluir lo siguiente. Reporta solo lo que realmente está presente en la respuesta.

• Identidad y registro: agentId, network, chainId, y las direcciones de los registros de identidad, reputación y validación.
• Propietario y wallet del agente: la dirección del propietario y la wallet designada del agente.
• Metadatos: el URI de metadatos (IPFS o HTTPS) y los metadatos analizados cuando se pudieron obtener: nombre, descripción, servicios, active, x402Support. Si no se pudieron obtener los metadatos, metadata es nulo y metadataError explica por qué.
• Reputación: conteo de clientes, conteo de comentarios, puntuación agregada, clientes y registros de comentarios individuales (cliente, índice, valor, etiquetas, isRevoked).
• Validación: si los datos de validación están disponibles, un motivo cuando no lo están, el conteo de solicitudes y las solicitudes y respuestas de validación cuando existen.
• Enlaces y marca de tiempo: enlaces al agente en Arc ERC-8004 Explorer y la hora fetchedAt.

Algunos campos pueden no estar disponibles. Dependiendo del agente y los contratos de registro implementados, los valores pueden ser nulos, vacíos o faltantes, y los datos de validación pueden estar completamente ausentes. Esto es normal. Indica que un campo no está disponible; nunca lo completes.

Después de una llamada paga exitosa, el servidor puede agregar un segundo bloque de texto con el hash de la transacción de pago y el enlace al explorador. El primer bloque es siempre el JSON de la API.

Ejemplos de uso

Recuperar datos de un agente

"Obtén los datos ERC-8004 del agente 15." Llama a get_agent_data con agentId: 15, luego presenta los campos principales.

Explicar registro y metadatos

"¿Qué es el agente 8 y cómo está registrado?" Llama a la herramienta, luego explica el propietario, la wallet del agente, el URI de metadatos y los registros. Describe los servicios solo si están en los metadatos. Si metadataError está establecido, repórtalo en lugar de adivinar lo que dicen los metadatos.

Resumir comentarios de reputación

"¿Cómo está calificado el agente 14?" Reporta clientCount, feedbackCount, aggregateScore y un breve resumen de los registros de comentarios, señalando las entradas revocadas. Si no hay comentarios, dilo.

Comparar dos agentes

"Compara el agente 1 y el agente 8." Haz una llamada por ID (dos solicitudes pagas; informa al usuario), luego compara los mismos campos lado a lado. Si un campo existe para un agente pero no para el otro, dilo, en lugar de tratar los datos faltantes como cero.

Identificar información faltante

"¿Qué no sabemos sobre el agente 22?" Después de la llamada, enumera los campos que son nulos, vacíos o están marcados como no disponibles, como metadata, validation.available y su reason. Indica claramente que no están disponibles y no infieras valores.

Al responder, distingue lo que devolvió la API de tu propia interpretación, y menciona que los datos provienen de Arc Mainnet a partir de fetchedAt.

Pagos

• Protocolo: x402 versión 2, esquema exact (una autorización de transferencia EIP-3009), liquidado a través del facilitador de Ultravioleta DAO.
• Precio: $0.002 USDC (2000 unidades atómicas, 6 decimales) por solicitud exitosa. No hay suscripciones ni tarifas mensuales.
• Redes de pago compatibles:
  • Arc Mainnet (eip155:5042), la predeterminada
  • Base Mainnet (eip155:8453)
• Cómo funciona: el desafío de pago de la API enumera las opciones aceptadas. El servidor selecciona exactamente una, que coincida con ARCAGENTS_PAYMENT_NETWORK, y paga directamente al destinatario especificado por ese requisito de pago. Verifica el token, el monto y el dominio de firma antes de firmar. Nunca cambia a la otra red después de un fallo.
• Soporte de protocolo de pago: solo x402. No describas ningún otro protocolo de pago, incluido MPP, como compatible.
• La wallet pagadora necesita USDC en la red seleccionada. El usuario no necesita tokens de gas nativos para el pago.

Seguridad del pago y manejo de errores

• Nunca le pidas al usuario que revele su clave privada, y nunca incluyas una en llamadas a herramientas, archivos o mensajes.
• Nunca reintentes una solicitud paga creando un nuevo pago cuando el resultado anterior es incierto. No intentes solucionar errores cambiando redes, wallets o configuraciones en medio de una solicitud.
• El servidor guarda el estado del pago pendiente localmente (en ~/.arcagents-mcp, o ARCAGENTS_STATE_DIR) antes de enviar un pago firmado. Si una solicitud se interrumpe, preguntar de nuevo por el mismo ID de agente la reanuda: el servidor reenvía el mismo pago firmado y no firma uno nuevo. Esto también funciona después de reiniciar el servidor MCP.
• 503, un tiempo de espera o una respuesta incompleta significa que puede que no haya un resultado final todavía. Reporta eso al usuario, respeta cualquier valor Retry-After y, después de ese retraso, llama a get_agent_data de nuevo con el mismo agentId. El servidor reanuda el mismo contexto de pago en lugar de pagar dos veces. No reintentes en un bucle cerrado.
• Conflicto 409 (la autorización ya se usó, o pertenece a otra solicitud) no debe desencadenar una nueva autorización. Reporta el reason en la respuesta tal como se indica: authorization_already_settled significa que el facilitador informa que esa autorización ya se usó con su pago confirmado; receipt_request_conflict significa que pertenece a otra solicitud, y la API no dice si ese pago se liquidó. No adivines cuál. El servidor conserva el pago firmado existente y no creará uno nuevo para ese ID de agente.
• 402 después del pago significa que la API no aceptó el pago. Reporta el motivo dado en la respuesta. Es una respuesta definitiva, por lo que preguntar de nuevo inicia una nueva solicitud.
• 500 significa que la liquidación falló o no se pudo confirmar. No firmes ni solicites un nuevo pago; informa al usuario y transmite cualquier hash de transacción en la respuesta. Preguntar de nuevo por el mismo ID de agente solo reenvía el mismo pago firmado.
• 404 significa que el ID del agente no está acuñado en Arc Mainnet; la solicitud no se cobra.
• Un mensaje como "otro proceso ya tiene un pago firmado sin resolver" es un conflicto temporal. Solo un proceso puede reclamar y enviar un pago para una solicitud, y el proceso competidor no envía nada. Pregunta de nuevo más tarde; el pago existente se reutiliza.
• No afirmes que una solicitud fue gratuita, no pagada o no cobrada cuando su resultado de pago es incierto. Di que el resultado no se pudo determinar y qué dice la respuesta.
• No inventes datos de agente, hashes de transacción, saldos o resultados de pago. Si la herramienta devuelve un error, cita el error y su guía en lugar de parafrasearlo en algo más optimista.

Limitaciones

• Los datos de la API de pago cubren solo agentes de Arc Mainnet.
• Testnet está disponible en la interfaz de Arc ERC-8004 Explorer, pero no a través de la API de pago ni de este servidor MCP.
• Los datos de validación dependen de la disponibilidad del registro y pueden estar ausentes.
• La actividad del agente no está disponible actualmente a través de esta API.
• La herramienta devuelve datos para un ID de agente por llamada; no hay un punto final de búsqueda, listado o lote.
• Las respuestas reflejan el momento de fetchedAt y no se actualizan en vivo.

Recursos

• Arc ERC-8004 Explorer: https://www.arcagents.app
• Especificación OpenAPI de la API: https://www.arcagents.app/api/openapi.json
• Repositorio MCP (configuración para cada cliente, configuración, solución de problemas): https://github.com/Nomad07/arcagents-mcp