@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:

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.

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": "noreply@yourapp.com"
      }
    }
  }
}

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:

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

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.