@ar-agents/mcp

@ar-agents/mcp

One MCP server that bundles the entire @ar-agents/* toolkit: CUIT validation, AFIP/ARCA padron lookup, identity attestation, MercadoPago Payments + Subscriptions + Cuotas, WhatsApp Business: into any MCP host (Claude Desktop, Cursor, Codeium, Continue, Cline, etc.).

What is this

This package is the MCP server wrapper around the @ar-agents/* packages. If you're building agents in Vercel AI SDK 6 directly, you don't need this: install the individual packages. If you want to use the AR toolkit from Claude Desktop, Cursor, Codeium, or any MCP host, this is your one-stop install.

Governance: the art. 102 gate is ON by default

This server moves real money (Mercado Pago), files real taxes (AFIP/ARCA) and can constitute real companies (IGJ). Argentina's Sociedad Automatizada regime (art. 102) makes a human administrator responsible for those acts and bars delegating that supervision. So, by default, this server enforces a governance gate:

• A READ-level tool (e.g. validate_cuit, lookup_cuit_afip, search_payments) always runs: no gate.
• A money / fiscal / legal / irreversible (or unclassifiable) tool is REFUSED unless you wire a human-approval hook. The refusal is a clear MCP error telling you what to do — no money/fiscal/legal tool ever executes silently.

Classification reuses the same @ar-agents/core risk manifest the local agents use (classifyTool / levelRequiresApproval), fed each tool's name, description and sideEffects. The gate runs before the tool executes, so a denied call never touches the network.

Blast radius: the gate is fail-closed, so some READ tools are gated too

Classification is by name (plus description / sideEffects). The unknown class fails closed — and any tool whose name is not a recognized read verb is treated as unknown and is GATED by default-ON. With every registry wired this is roughly 65 of ~145 exposed tools, and it currently includes some genuine read tools whose names don't match the read-verb heuristic:

Category	Read tools currently GATED by default-ON
IGJ registry reads	igj_get_entity, igj_search_entities, igj_get_autoridades, igj_get_domicilios, igj_get_asambleas
Boletín Oficial reads	bo_search, bo_today, bo_get_norma, bo_list_subscriptions
Signature verification reads	firma_inspect_cert, firma_verify_chain, firma_verify_cms_signature, firma_is_onti_issued
AFIP catalog reads	obtener_alicuotas_iva, obtener_tipos_comprobante, obtener_tipos_documento, obtener_tipos_concepto, obtener_tipos_moneda
Shipping reads	trackear_envio, listar_sucursales
Other	lookup_credit_situation, mp_health_check

This is intentional fail-safe behavior (better to gate a read than let an unknown tool move money silently), not a per-tool allowlist of "these are dangerous". To see the exact resolved risk level for every tool in your configuration, run:

ar-agents-mcp doctor

Its GOVERNANCE section lists each exposed tool, its resolved risk level, and whether it is GATED under your current env — so you see the precise blast radius before and after upgrading. To let the gated reads (and any approval-level tool) run, either wire an approve hook (below) or set AR_AGENTS_MCP_ENFORCE=off (ungated — not recommended for autonomous money/fiscal/legal acts). Reclassifying these names as read so they pass while real acts stay gated is a separate, deliberate change to the cross-package risk manifest, tracked outside this release.

Wiring human approval (HITL)

When you embed the server in your own Node app:

import { createServer } from "@ar-agents/mcp";

const { server } = await createServer({
  governance: {
    // Called before any money/fiscal/legal/irreversible/unknown tool.
    // Return true to proceed, false (or throw) to refuse.
    approve: async (toolName, args) => askHumanAdministrator(toolName, args),
    // Optional kill-switch: when it returns true, EVERY tool refuses.
    isHalted: async () => isSocietySuspended(),
  },
});

Opting out (ungated passthrough)

To restore the old behavior where every tool runs without a gate, set:

"env": { "AR_AGENTS_MCP_ENFORCE": "off" }

Resolution order: the explicit createServer({ governance: { enforce } }) option > the AR_AGENTS_MCP_ENFORCE env var > default-ON. The boot summary (printed to stderr) shows the active mode, e.g. governance → enforce=ON (art. 102 gate · NO approve hook → fail-closed DENY).

Kill-switch

Set AR_AGENTS_MCP_HALT=1 (or wire governance.isHalted) to suspend the whole society: every tool, read or not, refuses with a society_suspended error. Default is no halt — behavior is unchanged unless you wire it.

Env var	Default	Effect
AR_AGENTS_MCP_ENFORCE	on	off disables the art. 102 gate (ungated passthrough).
AR_AGENTS_MCP_HALT	unset	1 suspends every tool (society_suspended).

Quick start (Claude Desktop)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ar-agents": {
      "command": "npx",
      "args": ["-y", "@ar-agents/mcp"],
      "env": {
        // All env vars are optional: set the ones for the integrations you need.
        // Without any: only `validate_cuit` (algorithm-only) is available.

        // MercadoPago: enables 21 payment / subscription tools
        "MP_ACCESS_TOKEN": "TEST-...-or-APP_USR-...",
        "MP_BACK_URL": "https://yourapp.com/done",

        // AFIP/ARCA: enables `lookup_cuit_afip` (real padron data)
        "AFIP_CUIT_REPRESENTADO": "20XXXXXXXXY",
        "AFIP_CERT_PEM": "-----BEGIN CERTIFICATE-----\n...",
        "AFIP_KEY_PEM": "-----BEGIN PRIVATE KEY-----\n...",
        "AFIP_ENV": "prod", // or "homo"

        // WhatsApp Business: enables 6 messaging tools
        "WA_ACCESS_TOKEN": "EAA...",
        "WA_PHONE_NUMBER_ID": "...",

        // Identity Attestation: enables 5 verification tools
        "ATTEST_SIGNING_SECRET": "openssl rand -hex 32 result here",
        "BUSINESS_NAME": "Your Company",
        "RESEND_API_KEY": "re_...",                // optional, enables email_magic_link adapter
        "ATTEST_CALLBACK_URL": "https://yourapp.com/api/identity-attest/callback",
        "ATTEST_FROM_EMAIL": "[e-mail]"
      }
    }
  }
}

Restart Claude Desktop. Look for the wrench icon → ar-agents tools should appear.

Quick start (Cursor)

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ar-agents": {
      "command": "npx",
      "args": ["-y", "@ar-agents/mcp"],
      "env": {
        "MP_ACCESS_TOKEN": "TEST-...",
        // ... same env vars as above
      }
    }
  }
}

Restart Cursor. The tools appear in your chat panel's tool picker.

Quick start (any other MCP host)

Same pattern. Anything that supports MCP stdio servers works:

• Codeium: set in Settings → MCP servers
• Continue: ~/.continue/config.json → experimental.modelContextProtocolServers
• Cline: cline_mcp_settings.json

What tools you get

The set of tools depends on which env vars you set. Without any env vars: only validate_cuit (algorithm-only) is registered. With all env vars set:

Source	Tools
@ar-agents/identity (always on)	validate_cuit, lookup_cuit_afip (when AFIP vars set)
@ar-agents/identity-attest (when ATTEST_SIGNING_SECRET set)	list_verification_methods, request_identity_verification, submit_otp_code, check_verification_status, get_attestation
@ar-agents/mercadopago (when MP_ACCESS_TOKEN set)	21 tools: create_payment_preference, create_payment, search_payments, refund_payment, calculate_installments, create_subscription, create_customer, list_customer_cards, list_payment_methods, get_account_info, cancel_payment, capture_payment, list_refunds, get_payment, get_payment_preference, find_customer_by_email, delete_customer_card, pause_subscription, resume_subscription, cancel_subscription, get_subscription_status
@ar-agents/whatsapp (when WA vars set)	6 tools: send_whatsapp_text, send_whatsapp_template, send_whatsapp_media, send_whatsapp_buttons, send_whatsapp_list, mark_whatsapp_read

Total: up to 34 tools for AR agents in one MCP install.

Verifying it works

Run the binary directly to see the registered-tools summary:

npx @ar-agents/mcp
# Outputs to stderr (stdout is reserved for MCP protocol):
#   ar-agents@0.1.0 starting with N tools registered:
#     identity      → validate_cuit + lookup_cuit_afip (AFIP cert configured)
#     mercadopago   → PROD mode · back_url=...
#     whatsapp      → phone_number_id=...
#     identity-attest → whatsapp_otp, email_magic_link

If you see "not configured", check your env vars match what each package expects.

When to use this vs the individual packages

Use this (@ar-agents/mcp)	Use the individual packages
Claude Desktop / Cursor / Codeium user	Building a Vercel AI SDK 6 agent in your own Node app
Want the toolkit available in your IDE	Want fine-grained control over which tools an Agent registers
Don't want to write any code	Already have an Agent({ tools }) setup

The npm packages and the MCP server expose identical functionality: same tool names, same schemas, same behavior. The MCP server is just a different transport.

Troubleshooting

"validate_cuit only": no other tools showing → You haven't set any env vars. Check the env section of your MCP config.

MercadoPago tool calls fail with 401 → Your MP_ACCESS_TOKEN is wrong or expired. Test users in sandbox have their own tokens; don't mix prod/test.

AFIP lookup_cuit_afip returns "not configured" → You set MP_ACCESS_TOKEN but missed AFIP_CUIT_REPRESENTADO + cert vars. Each integration is independent.

Magic-link adapter not registered (identity-attest) → You set ATTEST_SIGNING_SECRET but not RESEND_API_KEY + ATTEST_CALLBACK_URL. The adapter needs both.

Tool names collide → Open an issue at github.com/ar-agents/ar-agents: we'll prefix tool names in v0.2 if collisions become common.

License

MIT: © Nazareno Clemente

Stability

This package is pre-1.0. Per npm convention, 0.x minor versions may include breaking changes. We document every breaking change in CHANGELOG.md under the corresponding minor bump and flag it explicitly. To avoid surprises:

# Pin to exact version (recommended for production):
pnpm add @ar-agents/<package>@<exact-version>

We commit to no breaking changes within a patch version, and we publish 1.0.0 once the public API has stabilized across at least two consecutive minor releases.