MCP4Acumatica

Descargo de responsabilidad: Este proyecto es una integración independiente creada por la comunidad y no está afiliado a Acumatica, Inc., ni cuenta con su respaldo ni con su soporte. «Acumatica» es una marca comercial registrada de Acumatica, Inc. El uso del nombre y de la API de Acumatica tiene fines meramente de interoperabilidad.

Un servidor remoto de Model Context Protocol (MCP) que conecta Claude con Acumatica ERP 2025 R2. Se ejecuta en Cloudflare Workers con autenticación OAuth por usuario contra tu instancia de Acumatica.

Cada usuario se autentica con sus propias credenciales de Acumatica. Su rol de Acumatica controla qué registros pueden ver. El servidor MCP exige además un rol específico de Acumatica para el acceso, muestra un aviso intermedio de consentimiento y oculta automáticamente los datos sensibles antes de que lleguen al modelo de IA.

Características

• 49 herramientas — 38 consultas de solo lectura + 6 de utilidad/detección + 4 de conocimiento de esquema + 1 herramienta de escritura (alta/actualización de clientes, desactivada por defecto) (ver Herramientas disponibles)

• OAuth por usuario — los usuarios inician sesión con sus credenciales de Acumatica (o con otro de SSO)

• Acceso basado en roles — el modelo de seguridad de Acumatica determina qué ve cada usuario

• Barrera de acceso — solo los usuarios que puedan leer una Generic Inquiry canaria designada pueden conectarse (restríngela como prefieras; un rol marcador como MCP Access es la opción recomendada)

• Aviso de consentimiento — los usuarios deben aceptar explícitamente el procesamiento de sus datos por una IA antes de usar las herramientas

• Ocultación de campos sensibles — SSN, cuentas bancarias, salarios y otros datos personales se ocultan automáticamente antes de que la información salga del servidor

• Limitación de peticiones — por defecto, se permiten 3 peticiones concurrentes y 40 peticiones por minuto y usuario; ambos límites pueden ajustarse desde la consola de administración. Si una petición encuentra todas las plazas ocupadas, espera brevemente a que se libere una en lugar de fallar al instante; un rechazo devuelve una respuesta estructurada { error: "rate_limited", retryAfterSeconds, actionRequired } que le dice a la IA exactamente cuánto tiempo debe esperar, en lugar de reintentar en bucle

• Denegación de paginación — las herramientas de listado/consulta devuelven una respuesta estructurada { truncated, paginationSupported: false, actionRequired } cuando los resultados alcanzan el límite de registros, e indican a la IA que pida al usuario un filtro más específico en lugar de volver a invocar la herramienta

• Registro de auditoría estructurado — todas las invocaciones de herramientas, eventos de autenticación y ocultaciones de campos quedan registradas

• Consola de administración — interfaz web de administración en /docs/admin para consultar los registros y ajustar la configuración en tiempo de ejecución sin volver a desplegar

• Retención prolongada de registros — almacenamiento de logs basado en R2 mediante Cloudflare Logpush, con visor de registros que admite búsqueda

Arquitectura

Claude (claude.ai / Desktop / API)
    |
    v  MCP over streamable-http
+----------------------------------+
|  Cloudflare Worker               |
|  OAuth 2.1 Provider              |
|    /authorize -> Acumatica login |
|    /callback  <- Acumatica       |
|    (access gate + OIDC userinfo) |
|    /consent   -> AI data consent |
|    /token, /register (DCR)       |
|    /mcp -> McpAgent DO (49 tools)|
+---------------+------------------+
                |  Bearer token (per-user)
                v
        Acumatica 25R2 SaaS
        Contract-Based REST API
        Default/25.200.001

Requisitos previos

• Node.js >= 18

• Una cuenta de Cloudflare (plan de pago de Workers para Durable Objects)

• Una instancia de Acumatica 2025 R2 que disponga de:

  • Una aplicación conectada (Connected Application) configurada en SM303010 con el flujo OAuth 2.0 Authorization Code (los alcances los envía el servidor en la petición; no se configuran en la aplicación)

  • Una URI de redirección que apunte al endpoint /callback de tu worker

  • Una Generic Inquiry MCPAccess (SM208000) — una GI canaria trivial con Expose via OData activado; la barrera de acceso del inicio de sesión comprueba si el usuario puede leer en esa GI (ver documentación de la arquitectura para más detalles). El nombre de la GI se puede configurar mediante ACUMATICA_CANARY_GI

  • Una forma de restringir quién puede leer esa GI — un rol marcador MCP Access (SM201005) asignado a los usuarios autorizados es la opción recomendada

Instalación

Existen tres rutas de instalación. Las tres dependen de los mismos prerrequisitos en Acumatica: confirma estos primero (ver «Configuración de Acumatica» más abajo) sea cual sea la ruta y elijas.

Ruta A — Botón «Deploy en Cloudflare» (sin terminal)

El botón crea un fork de este repositorio en tu cuenta de GitHub, resuelve wrangler.jsonc, crea automáticamente el namespace KV y el bucket de R2, te pide los secretos y despliega. Peso a paso:

1. Haz clic en el botón. Cloudflare te pedirá que inicies sesión (o crees una cuenta) y que autorices un fork de GitHub.

2. Confirma los bindings. Cloudflare te pedirá crear los namespaces KV dos veces: una para el binding TOKEN_STORE (datos de la app: tokens, estado de OAuth, caché, configuración, sesiones de administración) y otra para OAUTH_KV (usado internamente por la librería de OAuth). Esto es normal: son dos bindings distintos y nunca comparten claves.

   ⚠️ Pon a los dos namespaces nombres distintos (por ejemplo, mcp4acumatica-app para TOKEN_STORE y mcp4acumatica-oauth para OAUTH_KV). El aprovisionamiento automático de Cloudflare deriva el título por defecto del nombre del Worker, de modo que ambos campos se ponen como mcp4acumatica y crear dos namespaces con el mismo título falla con el error «Cannot plan a KV Namespace intitulado … porque ya existe». Si te aparece ese error, se ha quedado un namespace a medio crear: ve a Storage & Databases → KV, elimina el namespace huérfano mcp4acumatica y vuelve a intentarlo con dos nombres distintos. (El aprovisionamiento gráfico de Cloudflare no puede apuntar ambos bindings a un solo namespace, ni tampoco puede la configuración preasignar títulos distintos; por eso la solución es crear dos namespaces distintos. Si la interfaz gráfica sigue fallando, usa una ruta con terminal de las que aparecen más adelante: setup.sh crea un único namespace y enlaza ambos bindings a él.)

   Los buckets R2 (mcp4acumatica-logs, mcp4acumatica-index) se crean de la misma forma, pero sus nombres estan fijados en wrangler.jsonc para que no colisionen.

3. Pon los secretos. Cuando te lo pida, pega:

   • ACUMATICA_CLIENT_ID — el de tu Connected Application (SM303010)

   • ACUMATICA_CLIENT_SECRET — de la misma pantalla

   • COOKIE_ENCRYPTION_KEY — abre la consola del navegador en la página que quieras y ejecuta:

     [...crypto.getRandomValues(new Uint8Array(32))].map(b => b.toString(16).padStart(2,'0')).join('')

     Copia la cadena hexadecimal de 64 caracteres resultante.

   • ADMIN_SECRET — cualquier contraseña que recuerdes (proteja la consola /docs/admin). Puedes generar una con [...crypto.getRandomValues(new Uint8Array(24))].map(b => b.toString(16).padStart(2,'0')).join('') si no tienes preferencia.

4. Despliega. Cloudflare conecta el fork con Workers Builds y realiza el primer despliegue.

5. Actualiza las variables de Acumatica. When the deployment finishes, open Workers & Pages → mcp4acumatica → Settings → Variables and Secrets and edit:

   • ACUMATICA_URL (por ejemplo, https://yourcompany.acumatica.com)

   • ACUMATICA_TENANT

   • Opcionalmente, ACUMATICA_MAX_RECORDS, ACUMATICA_CANARY_GI, REDACT_PATTERNS, REDACT_SKIP Click en Save and Deploy: Cloudflare volverá a lanzar con los nuevos valores.

6. Añade una URI de redirección a tu Connected Application. Ahora tu worker (es decir, puede alcanzarlo en https://mcp4acumatica.<your-account>.workers.dev. Incluye https://<ese-host>/callback entre las URI de redirección de la pantalla SM303010 de Acumatica. Si prefieres usar un dominio personalizado, ve a «Custom domain».

7. Comprueba el despliegue. Visita https://<tu-host>/docs/admin/preflight, inicia sesión con tu ADMIN_SECRET y ejecuta el diagnóstico preflight. Se comprueba la conectividad con Acumatica, el endpoint de descubrimiento de OIDC, las credenciales de la Connected App, la ruta del tenant y la version del API del contrato; cualquier mala configuración se indica por su nombre.

Después de este punto, Claude ya puede conectarte (ver «Connecting Claude AppConfigurator» más a small).

Ruta B — Instalador de una sola línea (terminal)

Si ya tines git, node y npm, ejecuta:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh | bash

Esto clona el repositorio, Instalar las dependencias y ejecuta ./setup.sh. El script de instalación pedirá los valores de Acumatica que el usuario necesita (URL, tenant, client ID y client secret de la Connected App), genera automáticamente los secretos criptográficos, Crea el namespace de KV y el bucket R2, sube los secretos, despliega y, por fin, ejecuta la comprobación preflight.

Si prefieres inspeccionar primero el script:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh -o install.sh
less install.sh   # read it
bash install.sh   # then run

Ruta C — Instalación manual (terminal)

1. Clona e instala

git clone https://github.com/hallboys/MCP4Acumatica.git
cd MCP4Acumatica
npm install

2. Crea el namespace KV

npx wrangler kv namespace create TOKEN_STORE

Appointment que veas en la salida: la variable ID te servirá dentro de wrangler.jsonc. Se usa el mismo identificador para los dos bindings: TOKEN_STORE y OAUTH_KV.

3. Configura wrangler

wrangler.jsonc se presenta en el repositorio como plantilla de despliegue. Edítalo en el lugar correspondiente y completa lo siguiente:

• El identificador del namespace KV del paso 1 (bindings TOKEN_STORE y OAUTH_KV; el mismo id) * ACUMATICA_URL — la buena URL de tu instancia Achematica (p. ej. https://yourcompany.acumatica.com)

• ACUMATICA_TENANT — el nombre de tu empresa o tu tenant en Acumatica

Para dejar tus valores locales fuera de git status (y poder seguir obteniendo updates del repositorio sin conflictos):

git update-index --skip-worktree wrangler.jsonc

4. Define los secretos

npx wrangler secret put ACUMATICA_CLIENT_ID
npx wrangler secret put ACUMATICA_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY      # use `openssl rand -hex 32`
npx wrangler secret put ADMIN_SECRET                # any password — protects /docs/admin

5. Despliega

npx wrangler deploy

6. Desarrollo local (opcional)

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your Acumatica credentials
npx wrangler dev

Configuración de Acumatica

Estos pasos son obligatorios independientemente de la ruta de instalación elegida. No se pueden automatizar: la API de Acumatica no los expone.

Connected Application (SM303010)

1. En Acumatica: System > Integration > Connected Applications (SM303010).

2. Create a new Connected Application.

3. Define OAuth 2.0 Flow en Authorization Code.

4. Añade una URI de redirección a: https://<tu-worker>/callback (utiliza el hostname * .workers.dev o tu dominio personalizado).

5. Guarda el Client ID y el Client Secret: los aportarás como secretos durante la instalación.

Este no es un campo de alcances (scopes) configurable. Los scopes de OAuth (api openid profile email offline_access, incluido el offline_access que hace que Acumatica emita tokens de renovación), los envía el servidor MCP en la petición de autorización; no se configuran en la Connected Application.

Barrera de acceso: Generic Inquiry canary (SM208000, SM201005)

Antes de que un usuario pueda usar las herramientas de IA, la secuencia de inicio de sesión realiza una bueña de acceso: consulta una Generic Inquiry canaria trivial a través de OData and comprobarces whether user can read. The server never checks role groups; only asks "can you see this GI?".

1. Crea la Generic Inquiry: SM208000 → Generic Inquiry → create a GI named MCPAccess with any simple query (with only one column from any table enough). Enable Expose via OData.

2. Restringe quién puede leer eña GI (recomendado: rol marcador): SM201005 → User Roles → create a role named MCP Access with no permissions at the screen level, assign the MCPAccess GI only to that role, y asigna el rol a cada usuario que deba tener acceso al asistente IA. Cualquier otra mécanisme que controle la lectura de esa GI por OData es válido.

El nombre de la Generic canaria es configurable mediante la variable ACUMATICA_CANARY_GI (por defecto, MCPAccess). Cambiali en el panel Cloudflare (Variables and Secrets) o en wrangler.jsonc.

Generic Inquiry exposure to AI (muy recomendado)

Una instancia madura de Acumatica puede tener cientos de consultas genéricas (Generic Inquiries, GI), la mayoría construidas para pantallas humanas (cuadrículas de informes amplias, paneles, consultas puntuales). Exponerlas todas al asistente satura su contexto y hace que escoja la consulta equivocada —y, peor aún, una GI parametrizada expuesta vía OData devuelve datos erróneos en silencio: al consultarla sin sus parámetros, Acumatica devuelve filas por defecto/sin filtrar con ningún error, algo que el modelo no puede detectar. El control de exposición de GI convierte esto en opt-in: programas con ExposedToMCP las GI que son realmente útiles y correctas para que un agente de IA consulte, y el modelo solo ve estas.

El control está inactivo hasta que lo configures: el servidor se ejecuta, pero sin registro el asistente no puede descubrir GI (acumatica_list_generic_inquiries no devuelve nada; un usuario cualquiera puede ejecutar una GI de todos modos por su nombre exacto). Configurarlo le da al asistente un grupo seleccionado que puede descubrir sin riesgo. Activarlo es un proyecto de personalización único en Acumatica — es decir, junto con acumatica/, es un proyecto de personalización incluido en acumatica/, que añade los campos personalizados UsrExposedToMCP / UsrAIDescription (GIDesign) y UsrResAIDescription (GIResult), además de los cambios en el formulario SM20839; después se crean las GIs de feed MCPGIs / MCPGIFields, se concede acceso de lectura a los feeds para el rol MCP Access y se marcan las GI que se quieren exponer. Ver el artículo Generic Inquiries.

Ver Generic Inquiries para conocer el razonamiento completo, cómo decidir qué GI exponer y le configuración paso a paso.

Dominio personalizado (opcional)

El despliegue te da un hostname *.workers.dev de serie. Para asociarle un dominio con tu marca:

• Mediante el panel de Cloudflare: Workers & Pages → mcp4acumatica → Settings → Domains & Routes → Add. La zona del dominio debe estar en tu cuenta de Cloudflare.

• Mediante wrangler.jsonc: descomenta el bloque routes de la parte superior del archivo, modifica pattern y zone_name, y vuelve a desplegar.

Si cambias el hostname, recuerda añadir la nueva URL https://<host>/callback a los URI de redirección de tu aplicación conectada (Connected Application) en SM303010.

Conectando Claude

Claude.ai / Claude Desktop

1. Ve a Settings > Connectors

2. Haz clic en Add Connector e introduce la URL: https://<your-worker-url>/mcp

3. En el primer uso, serás redirigido a la página de inicio de sesión de Acumatica

4. Si tu cuenta puede leer la GI canary (es decir, se te ha concedido acceso), verás una página de consentimiento que explica el tratamiento de datos para IA

5. Después de aceptar el consentimiento, Claude tendrá acceso a las 49 herramientas

Claude Code (CLI)

claude mcp add acumatica-erp --transport streamable-http https://<your-worker-url>/mcp

API (via Anthropic SDK)

Al usar la API de Anthropic con MCP, apunta el cliente MCP a https://<your-worker-url>/mcp. El servidor es compatible con OAuth 2.1 con Dynamic Client Registration en /register.

Herramientas disponibles

Núcleo

Financiación / Contabilidad

Inventario y almacén

Compras

Proyectos

Conversión y campo

Ventas y CRM

Envío y cumplimiento

RR. HH. y nó tierra

Actividades de CRM

Utilidades / Descubrimiento

Consejo: Use acumatica_describe_entity para descubrir los campos disponibles y luego acumatica_list_entities para buscar o filtrar. En el caso de las consultas genéricas, usa ListView_Categories acumatica_list_generic_inquiries y acumatica_describe_inquiry para ver los campos disponibles antes de ejecutarlas. Consulte: docs/example-prompts.md para ver ejemplos de uso.

Documentación

La documentación completa de este proyecto se encuentra en docs/:

• Referencia de Herramientas — Especificación completa de las 49 herramientas con parámetros y endpoints

• Ejemplos de Prompts — Prompts de ejemplo para Claude y otros clientes MCP organizados por caso de uso

• Guía de filtrado OData — Guía de parámetros $filter, $orderby, $select, $expand y $top

• Generic Inquiries — Por qué las GI están bloqueadas para uso de IA, cuáles exponer y cómo habilitar el registro opt-in

• Conocimiento del Esquema — Herramientas de descubrimiento de esquemas sin despliegue para construir integraciones/customizations, y cómo se genera el índice de esquema

• Arquitectura — Arquitectura detallada, flujo OAuth, modelo de seguridad y decisiones de diseño

• Guía de Autoinstalación — Cómo ejecutar el servidor MCP en Node.js u otras plataformas fuera de Cloudflare

• Actualización de Acumatica — Que hacer al preparar la versión de Acumatica que se conecta

Usos

• acumatica-gi-descriptions — Proceso completo para escribir descripciones orientadas a IA para las Generic Inquiries y sus columnas de resultados, con base en el propio metadata de diseño de la GI (tablas, uniones, condiciones WHERE, columnas) y no adivinando por nombres. Incluye las trampas más comunes que hacen fallar silenciosamente el trabajo con metadatos de GI, una lista de señales de diseño útiles y tres scripts: una para auditar truncados, un briefing de diseño y una validación de borrador.

Para usar un skill, apunta a Claude al directorio correspondiente, o cópia el contenido en tu propio .claude/skills/.

Seguridad

• Sin credenciales almacenadas. El servidor MCP no almacena contraseñas de Acumatica. Utiliza el flujo de código de autorización de OAuth 2.0 -- los usuarios se autentican directamente con Acumatica.

• Tokens por usuario. El token de acceso a Acumatica de cada usuario se almacena en el almacén de clave-valor de la plataforma (Cloudflare KV en el despliegue por defecto), asociado a su nombre de usuario. Los tokens se renuevan automáticamente al caducar. Si un token de actualización caduca, la conexión se reautentica automáticamente en lugar de requerir una reconexión manual.

• Puerta de acceso. Solo los usuarios que puedan leer una Generic Inquiry centinela designada pueden conectarse. El servidor comprueba la legibilidad de la GI mediante OData durante el inicio de sesión (no la pertenencia a roles); los usuarios sin acceso ven una página de acceso denegado. Restringe la GI como quieras -- un rol marcador MCP Access es la forma recomendada. El nombre de la GI se configura mediante ACUMATICA_CANARY_GI.

• Consentimiento. Tras superar la comprobación de acceso, los usuarios deben aceptar que sus datos serán procesados por un modelo de IA externo antes de que se active la sesión MCP.

• Enmascaramiento de campos sensibles. Las respuestas de las herramientas se analizan automáticamente en busca de nombres de campos sensibles (SSN, cuentas bancarias, sueldos, tarjetas de crédito, etc.) y los valores coincidentes se sustituyen por [REDACTED]. Los patrones se pueden configurar mediante las variables de entorno REDACT_PATTERNS y REDACT_SKIP.

• Acceso basado en roles. El rol del usuario en Acumatica determina qué registros puede leer. Si un usuario no tiene acceso a un registro en Acumatica, tampoco podrá acceder a él a través del servidor MCP.

• Solo lectura. Todas las herramientas actuales son consultas de solo lectura. No se crean, modifican ni eliminan todos.

• Límite de peticiones. 3 peticiones simultáneas, 40 peticiones por minuto y un cupo de 1000 registros por consulta por defecto -- todo configurable desde la consola de administración en /docs/admin/settings sin redeploy. Los límites son por usuario y cuentan las llamadas HTTP a Acumatica (no las invocaciones a herramientas). Los rechazos devuelven un sobre estructurado con un retryAfterSeconds exacto y quedan registrados como eventos rate_limit_hit para que veas si los topes son demasiado estrictos.

• Denegación de paginación. Las herramientas de listado/consulta (acumatica_list_entities, acumatica_run_inquiry, acumatica_list_generic_inquiries) no admiten paginación. Cuando una respuesta alcanza ACUMATICA_MAX_RECORDS, la herramienta devuelve un sobre estructurado (truncated: true, paginationSupported: false, actionRequired: "...") que indica a la IA que se detenga y pida al usuario un filtro más reducido en lugar de recuperar más registros.

• Registro de auditoría. Todas las invocaciones a herramientas, los eventos de autenticación (inicio de sesión correcto/denegado, aceptación del consentimiento) y los eventos de enmascaramiento de campos se registran como JSON estructurado. Puedes verlos con npx wrangler sol.

Portabilidad de la plataforma

Aunque el despliegue por defecto apunta a Cloudflare Workers, los manejadores de las herramientas y las librerías centrales son independientes de la plataforma. Una abstracción de almacenamiento (interfaz IKeyValueStore + tipo AppEnv) desacopla la lógica de las herramientas de las API específicas de Cloudflare, lo que permite despliegues autoalojados en Node.js con Redis, SQLite u otros backends de almacenamiento. Consulta la Guía de autoalojamiento para más detalles.

Stack tecnológico

• Runtime: Cloudflare Workers + Durable Objects

• MCP: agents SDK (McpAgent), @modelcontextprotocol/sdk

• Autenticación: @cloudflare/workers-oauth-provider

• Enrutamiento HTTP: Hono

• Lenguaje: TypeScript

• Validación: Zod

Desarrollo

npx wrangler dev       # Start local dev server
npx tsc --noEmit       # Type check
npx wrangler tail      # Stream live logs from deployed worker

Licencia

Apache 2.0 -- Copyright 2026 Hall Boys, Inc.