ar-agents is a Mercado Pago Agent Toolkit for the Vercel AI SDK 6. It ships 89 typed tools that an LLM agent can call directly to drive Mercado Pago billing flows: subscriptions, payments, refunds, checkout pro, marketplace OAuth, cuotas (installments), QR in-store, 3DS challenge resolution, point-of-sale devices, webhooks. Sidecar packages cover AFIP/ARCA, WhatsApp Business Cloud, banking (CBU/CVU + BCRA), and shipping (Andreani/OCA/Correo Argentino).

How is this different from the official mercadopago SDK?

The official mercadopago SDK is a thin REST client. It does not ship Vercel AI SDK tool schemas, does not implement webhook HMAC verification with replay protection, does not run on Edge Runtime (Node-only), and does not gate irreversible operations. ar-agents adds all of that on top of the underlying API: 89 typed tools, deterministic idempotency keys derived from inputs, programmatic human-in-the-loop on refund/cancel/delete, npm provenance attestation, Vercel KV adapters via subpath, OpenTelemetry instrumentation. You can use both packages in the same project; ar-agents wraps the underlying API directly without depending on the official SDK.

Does ar-agents work on Edge Runtime?

Yes. The whole package is Web Crypto-based with no node:crypto dependency, so it runs on Vercel Edge Functions, Cloudflare Workers, Deno, and any other V8-isolate runtime. Webhook signature verification, HMAC, and idempotency-key generation all use the Web Crypto API.

What is HITL (human-in-the-loop) in ar-agents?

Eight tools mutate state irreversibly (refund_payment, cancel_subscription, delete_customer_card, etc.). The toolkit accepts a requireConfirmation callback that gates each invocation: the tool function literally will not execute until your callback returns true. This is a programmatic gate, not just an LLM instruction. You can show the user a UI and wait for their explicit approval before any irreversible operation runs.

How does idempotency work?

Every POST request gets an auto-generated idempotency key. For LLM-driven retries, four mutating tools (create_payment, create_subscription, create_payment_preference, refund_payment) use a deterministic key derived from a SHA-256 hash of the meaningful inputs (external_reference, amount, payment_method, etc.). Same inputs produce the same key, so retries return the existing resource instead of double-charging the customer.

Yes. MIT license. No paid tier, no telemetry phone-home, no usage caps. The package is published to npm under the @ar-agents scope with SLSA v1 provenance attestations.

What about AFIP, WhatsApp, banking, shipping?

Sidecar packages cover the rest of the Argentine business stack: @ar-agents/identity (CUIT/CUIL validation + AFIP/ARCA padron lookup with monotributo category and IVA condition), @ar-agents/facturacion (AFIP/ARCA factura electronica via WSFE), @ar-agents/whatsapp (WhatsApp Business Cloud API with HMAC webhook verify and AR phone normalizer), @ar-agents/banking (CBU/CVU validation + BCRA Central de Deudores), @ar-agents/shipping (Andreani, OCA, Correo Argentino), @ar-agents/identity-attest (HMAC-signed verification orchestrator). Each ships independently to npm.

Is there a Model Context Protocol (MCP) server?

Yes. @ar-agents/mcp bundles all 7 ar-agents packages into a single MCP server compatible with Claude Desktop, Cursor, Codeium, Continue, Cline, or any MCP host. Auto-detects which packages to enable from environment variables. Listed on Glama (glama.ai/mcp/servers/ar-agents/ar-agents) and the official MCP Registry (io.github.ar-agents/mcp).

Infraestructura abierta · MIT + CC-BY-4.0

Infraestructura abierta para sociedades de IA.
Hecha en Argentina.

Le da a un agente de IA todo lo que necesita para operar como una empresa argentina: facturar en AFIP, cobrar con Mercado Pago, validar CUITs, registrar trámites. Open-source y lista para usar.

Ver demo (2:30)Leer RFC-001 GitHub

Para developers

17 paquetes npm tipados para Vercel AI SDK 6. Cobrar, validar CUIT, mandar WhatsApp, emitir factura, monitorear el BO.

Ver SDK →

Para reguladores

Audit log forense con HMAC + Ed25519, verificable sin pedir la clave al operador. 1-pager imprimible.

Abrir /auditor →

Para legisladores

Síntesis técnica de los 5 RFCs con texto sugerido cite-by-reference. Para quien esté redactando la ley.

Abrir /legislación →

17

Paquetes en npm

5

RFCs (CC-BY-4.0)

168

Tools tipadas

5

Implementaciones

100/100

Conformidad

Paquete insignia

@ar-agents/mercadopago

89 tools tipadas para Vercel AI SDK 6. Idempotencia determinística, HITL programático en operaciones irreversibles, verificación de webhook HMAC. La pieza más madura del stack, usada en demos productivos y referenciada por el resto del toolkit.

listo

@ar-agents/mercadopago

Cómo se compara

Característica	@ar-agents /mercadopago	mercadopago (oficial)	Stripe Agent Toolkit
Schemas de tools del Vercel AI SDK 6	✓	no	✓ (Stripe)
Argentino-específico (cuotas, ARCA, teléfono AR)	✓	parcial	no
Cantidad de tools	89	REST básico	26 (Stripe)
Webhooks: HMAC + dedup + replay window	✓	solo cliente	✓
Edge Runtime + adapters de Vercel KV	✓	solo Node	opcional
Instrumentación OpenTelemetry	✓	no	no
Idempotencia determinística por default	✓	no	no
HITL programático en ops irreversibles	✓	no	no
Cobertura de MercadoPago	completa	completa	n/a

Qué incluye

Pagos

create / capture / refund · OAuth marketplace · Checkout Pro · Order Management

Suscripciones

create / get / pause / resume / cancel · planes · tarjetas guardadas

Cuotas

Catálogo de promos AR · cuotas · resolución de challenge 3DS

QR + Point

QR en local · dispositivos Point físicos · Stores + POS

Webhooks

Verificación HMAC · ventana de replay · deduplicación · handle_webhook combo

State

Adapters InMemory + Vercel KV listos · interfaz pluggable

Observabilidad

Trazas OpenTelemetry vía subpath · adapter de audit log · circuit breaker

Seguridad

idempotencia determinística por default · HITL programático en 8 ops irreversibles

Inicio rápido

pnpm add @ar-agents/mercadopago ai zod

import { Experimental_Agent as Agent, stepCountIs } from "ai";
import {
  MercadoPagoClient,
  mercadoPagoTools,
  InMemoryStateAdapter,
} from "@ar-agents/mercadopago";

const mp = new MercadoPagoClient({
  accessToken: process.env.MP_ACCESS_TOKEN!, // TEST- for sandbox, APP_USR- for prod
});

const agent = new Agent({
  model: "anthropic/claude-sonnet-4-6",
  tools: mercadoPagoTools(mp, {
    state: new InMemoryStateAdapter(), // swap for VercelKVStateAdapter in prod
    backUrl: "https://yoursite.com/subscription/done",
  }),
  stopWhen: stepCountIs(8),
});

const { text } = await agent.generate({
  prompt: "Creá una subscription mensual de $1000 ARS para customer@example.com.",
});

Cliente TypeScript zero-dependency para `ar-agents.ar/api/auto-incorporate`, permite que un agente externo (USA-LLC, ChatGPT, Claude, Gemini) auto-incorpore una sociedad-IA argentina en una sola llamada. Devuelve los archivos generados, la URL de deploy en Vercel y la referencia firmada del audit-log.

npm código demo en vivo →

@ar-agents/mcp

v0.10.0

Servidor MCP que bundlea los 16 packages con tools. Una sola instalación en Claude Desktop / Cursor / cualquier host MCP. Auto-detecta qué packages habilitar a partir de env vars.

npm código

Ejemplo de composición: asistente de cobros

whatsapp-hello.ar-agents.ar muestra MP componiéndose con identity, identity-attest y whatsapp en un solo agente. Valida el CUIT contra ARCA, gatea cobros grandes con verificación (WhatsApp OTP), crea la suscripción de MP y responde por WhatsApp.

< $5kcobro directo, sin verificación$5k–$50krequiere trust ≥ 0.3 (whatsapp_otp)$50k–$500krequiere trust ≥ 0.5 (email_magic_link / mp_identity)> $500krequiere trust ≥ 0.7 (auth0 con MFA → 0.85)

Preguntas frecuentes

¿En qué se diferencia del SDK oficial mercadopago?

El SDK oficial mercadopago es un cliente REST básico. ar-agents agrega tool schemas del Vercel AI SDK 6, idempotency keys determinísticas (resistentes a retry de LLM), verificación de webhook HMAC con ventana de replay de 5 minutos, HITL programático en 8 operaciones irreversibles, soporte Edge Runtime via Web Crypto, adapters de Vercel KV, e instrumentación OpenTelemetry. Podés usar ambos packages en el mismo proyecto.

¿Corre en Edge Runtime?

Sí. Todo el package usa Web Crypto, sin dependencia de node:crypto. Corre en Vercel Edge, Cloudflare Workers, Deno, y cualquier runtime V8-isolate. Verificación de webhooks, HMAC, e idempotency keys usan la Web Crypto API.

¿Qué es HITL en operaciones irreversibles?

8 tools modifican estado irreversiblemente (refund_payment, cancel_subscription, delete_customer_card, etc). El toolkit acepta un callback requireConfirmation que bloquea la ejecución hasta que tu código devuelva true. Es un gate programático, no solo instrucciones al LLM.

¿Cómo funciona la idempotency determinística?

Cuatro tools (create_payment, create_subscription, create_payment_preference, refund_payment) derivan la idempotency key de un hash SHA-256 de los inputs relevantes. Mismos inputs → misma key → MP deduplica server-side. Un LLM que reintenta un tool devuelve el recurso existente en vez de cobrar dos veces.

¿Es gratis?

Sí. Licencia MIT. Sin tier pago, sin telemetría, sin límites de uso. Todos los tarballs publicados llevan attestation de provenance npm SLSA v1.

¿Qué hay de AFIP, WhatsApp, banking, shipping?

Packages sidecar cubren el resto del stack argentino: @ar-agents/identity (CUIT + padrón AFIP/ARCA con monotributo + IVA), @ar-agents/facturacion (factura electrónica WSFE), @ar-agents/whatsapp (Business Cloud API), @ar-agents/banking (CBU/CVU + BCRA Central de Deudores), @ar-agents/shipping (Andreani/OCA/Correo Argentino), @ar-agents/identity-attest (orquestador de verificación HMAC). Cada uno se publica independiente.

¿Hay servidor MCP?

Sí. @ar-agents/mcp bundlea los 7 packages en un único servidor MCP compatible con Claude Desktop, Cursor, Codeium, Continue, Cline. Listado en Glama y en el MCP Registry oficial como io.github.ar-agents/mcp.