MCP4Acumatica

Aviso: Este proyecto es una integración independiente, construida por la comunidad y no está afiliado, respaldado ni es compatible con Acumatica, Inc. "Acumatica" es una marca registrada de Acumatica, Inc. El uso del nombre y la API de Acumatica es únicamente con fines de interoperabilidad.

Un servidor remoto del 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 en Acumatica controla qué registros pueden acceder. El servidor MCP requiere adicionalmente un rol específico de Acumatica para el acceso, muestra un interstitial de consentimiento y redacta automáticamente los campos sensibles antes de que los datos lleguen al modelo de IA.

Funcionalidades

• 49 herramientas -- 38 consultas de solo lectura + 6 utilidades/detección + 4 de conocimiento del esquema + 1 herramienta de escritura (crear/actualizar cliente, deshabilitada por defecto) (ver Herramientas disponibles)

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

• Acceso basado en roles -- el modelo de seguridad de Acumatica determina lo que cada usuario ve

• Puerta de acceso -- solo los usuarios que puedan leer una Consulta Genérica canario designada pueden conectarse (restringe como prefieras; se recomienda un rol marcador como Acceso MCP)

• Interstitial de consentimiento -- los usuarios deben confirmar el procesamiento de datos de IA antes de acceder a las herramientas

• Redacción de campos sensibles -- SSN, cuentas bancarias, salarios y otros campos de información personal se redactan automáticamente antes de que los datos salgan del servidor

• Límite de velocidad -- 3 solicitudes concurrentes y 40 solicitudes/minuto por usuario por defecto, ambos ajustables desde la consola de administración. Una solicitud que encuentra todos los slots ocupados espera brevemente en lugar de fallar directamente, y un rechazo devuelve un sobre estructurado { error: "rate_limited", retryAfterSeconds, actionRequired } indicando exactamente cuánto tiempo debe esperar la IA en lugar de reintentar en un bucle

• Rechazo de paginación -- las herramientas de listado/consulta devuelven un sobre estructurado { truncated, paginationSupported: false, actionRequired } cuando los resultados alcanzan el límite de registros, indicando a la IA que pida al usuario un filtro más restrictivo en lugar de llamar a la herramienta nuevamente

• Registro de auditoría estructurado -- todas las invocaciones de herramientas, eventos de autenticación y redacciones de campos se registran

• Consola de administración -- interfaz web de administración en /docs/admin para ver registros y gestionar configuraciones en tiempo de ejecución sin redesplegar

• Retención de registros a largo plazo -- almacenamiento de registros respaldado por R2 a través de Cloudflare Logpush con visor de registros con búsqueda

Related MCP server: MCP4Acumatica

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 Workers de pago para Durable Objects)

• Una instancia de Acumatica 2025 R2 con:

  • Una Aplicación Conectada configurada en SM303010 con el flujo Código de Autorización OAuth 2.0 (los alcances se envían por el servidor en la solicitud, no se configuran en la aplicación)

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

  • Una Consulta Genérica MCPAccess (SM208000) -- una GI canario trivial con Exponer vía OData habilitada; la puerta de acceso de inicio de sesión verifica si el usuario puede leerla (ver documentos de Arquitectura para detalles). El nombre de la GI es configurable mediante ACUMATICA_CANARY_GI.

  • Una forma de restringir quién puede leer esa GI -- se recomienda un rol marcador Acceso MCP (SM201005) asignado solo a los usuarios permitidos

Configuración

Hay tres rutas de instalación. Las tres dependen de los mismos requisitos previos en Acumatica (completa esos primero, ver "Configuración en Acumatica" a continuación) independientemente de la ruta que elijas.

Ruta A — Botón Desplegar en Cloudflare (sin terminal)

El botón bifurca este repositorio en tu cuenta de GitHub, lee wrapagler.jsonc, crea automáticamente el espacio de nombres KV y el depósito R2, solicita secretos y despliega. Paso a paso:

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

2. Confirm a liguaduras. Se te pedirá que crees espacios de nombres KV dos vecess — una para la iguadura TOKEN_STORE (datos de la aplicación: tokenes, estado OAuth, caché, configuración, sesiones de administración) y otra para OAUTH_KV (usado internamente por la biblioteca OAuth). Es es esperado: son dos iguaduras separadas y nunca comparten claves.

   ⚠️ Da a los dos espacios de nombres nombres diferentes (por ejemplo, mcp4acumatica-app para TOKEN_STORE y mcp4acumatica-oauth para OAUTH_KV). El aprovisionamiento automático de Cloudflare deriva el título predeterminado del nombre del Worker, por lo que ambos campos predeterminan a mcp4acumatica — y crear dos espacios de nombres con el mismo título falla con "Cannot provision a KV Namespace with the title … because it already exists." Si ya te encontraste con ese error, quedó un espacio de nombres a medio terminar: ve a Storage & Databases → KV y elimina el espacio de nombres huérfano mcp4acumatica, luego reintenta con dos nombres distintos. (El aprovisionamiento automático de la GUI de Cloudflare no puede apuntar ambas iguaduras a un solo espacio de nombres, y la configuración no puede preestablecer títulos distintos — por lo tanto, dos espacios de nombres separados con nombres distintos es el camino. Si la GUI sigue fallando, usa una ruta de instalación con terminal a continuación: setup.sh crea un espacio de nombres y enlaza ambas iguaduras a él.)

   Los depósitos R2 (mcp4acumatica-logs, mcp4acumatica-index) se crean de la misma manera, pero sus nombres están fijos en wrapagler.jsonc para que no colisionen.

3. Establece los secretos. Cuando se te solicite, pega:

   • ACUMATICA_CLIENT_ID — de tu Aplicación Conectada (SM303010)

   • ACUMATICA_CLIENT_SECRET — de la misma pantalla

   • COOKIE_ENCRYPTION_KEY — abre la consola del navegador en cualquier página 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 (protege la consola /docs/admin). Genera 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 a Workers Builds y realiza la primera implementación.

5. Actualiza las variables de Acumatica. Después de que finalice el despliegue, abre Workers & Pages → mcp4acumatica → Settings → Variables and Secrets en el panel de Cloudflare y edita:

   • ACUMATICA_URL (p.ej., https://tuempresa.acumatica.com)

   • ACUMATICA_TENANT (tu empresa de inicio de sesión)

   • Opcionalmente ACUMATICA_MAX_RECORDS, ACUMATICA_CANARY_GI, REDACT_PATTERNS, REDACT_SKIP Haz clic en Guardar y Desplegar — Cloudflare redespliega con los nuevos valores.

6. Añade una URI de redirección a tu Aplicación Conectada. Tu worker ya es accesible en https://mcp4acumatica.<tu-cuenta>.workers.dev. Añade https://<ese-host>/callback a las URIs de redirección en la pantalla SM303010 de Acumatica. (Para usar un dominio personalizado en su lugar, consulta "Dominio personalizado" a continuación.)

7. Prueba el despliegue. Visita https://<tu-host>/docs/admin/preflight, inicia sesión con tu ADMIN_SECRET y ejecuta el diagnóstico previo. Verifica la conectividad con Acumatica, el endpoint de descubrimiento OIDC, las credenciales de la aplicación conectada, la ruta del inquilino y la versión de la API del contrato; cualquier error de configuración se señala por su nombre.

Después de esto, Claude puede conectarse (ver "Conectando Claude" a continuación).

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

Si ya tienes git, node y npm, ejecuta:

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

Esto clona el repositorio, instala las dependencias y ejecuta ./setup.sh. El script de configuración solicita los valores de Acumatica que debes proporcionar (URL, inquilino, ID y secreto de cliente de la aplicación conectada), genera automáticamente los secretos criptográficos, crea el espacio de nombres KV y el depósito R2, sube los secretos, despliega y luego ejecuta la verificación previa.

Si prefieres inspeccionar el script primero:

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

Ruta C — Configuración manual (terminal)

1. Clonar e instalar

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

2. Crear espacio de nombres KV

npx wrangler kv namespace create TOKEN_STORE

Nota el ID del espacio de nombres de la sailida — lo pegarás en wrangler.jsonc a continuación. El mismo ID se usa para ambas vinculaciones TOKEN_STORE y OAUTH_KV.

3. Configurationar wrangler

wrangler.jsonc está en el repo como plantilla de despliegue. Edítalo en su lugar y completa:

• El ID del espacio de nombres KV del paso 2 (ambas vinculaciones TOKEN_STORE y OAUTH_KV — mismo ID)

• ACUMATICA_URL — la URL de tu instancia de Acumatica (p.ej., https://tuempresa.acumatica.com)

• ACUMATICA_TENANT — el nombre de la empresa/inquilino de Acumatica

Para mantener tus valores locales fuera de git status (para que aún puedas recibir actualizaciones sin conflictos):

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

4. Stablecer 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. Desplegar

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 en Acumatica

Estos pasos son necesarios independientemente de la ruta de instalación que elijas. No se pueden automatizar — la API de Acumatica no los expone.

Aplicación Conectada (SM303010)

1. En Acumatica: Sistema > Integración > Aplicaciones Conectadas (SM303010).

2. Crea una nueva Aplicación Conectada.

3. Establece el Flujo OAuth 2.0 a Código de Autorización.

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

5. Nota el ID de Cliente y el Secreto de Cliente — los proporcionarás como secretos durante el despliegue.

No hay un campo de alcance que configurar aquí. Los alcances OAuth (api openid profile email offline_access, incluyendo el offline_access que hace que Acumatica emita tokens de actualización) son enviados por el servidor MCP en la solicitud de autorización — no se establecen en la Aplicación Conectada.

Puerta de acceso: Consuta Genérica canario (SM208000, SM201005)

Antes de que un usuario pueda acceder a las herramientas de IA, el flujo de inicio de sesión ejecuta una puerta de acceso: consulta una Consuta Genérica canario trivial a trevés de OData y verifica si el token del usuario puede leerla (200 → permitido, 403 → denegado). El servidor nunca inspecciona la pertenencia a roles de Acumatica — solo pregunta "¿puedes ver esta GI?". Tú restringes quién puede leer la GI canario según prefiera tu modelo de seguridad; se recomienda un rol marcador como la forma más limpia.

1. Crea la GI canario: Sistema > Personalzación > Consuta Genética (SM208000) → crea una GI nombrada McPAccess con cualquier consuta trivial (una sola columna de cualquier tabla está bien). Habilita Exponer vía OData.

2. Restringe quién puede leerla (recomendado: un rol marcador): Sistema > Derechos de Acceso > Roles de Usuario (SM201005) → crea un rol llamado Acceso MCP sin permisos de pantalla, asigna la GI McPAccess solo a ese rol, luego asigna el rol a cada usuario que deba tener acceso al asistente de IA. Cualquier otro mecanismo que controle el acceso de lectura a la GI vía OData también funciona.

El nombre de la GI canario es configurable mediante la variable ACUMATICA_CANARY_GI (predeterminado McPAccess). Edítalo en el panel de Cloudflare (Variables and Secrets) o en wrapagler.jsonc.

Exposición de Consutas Genéricas a la IA (muy recomendado)

Una instancia madura de Acumatica puede tener cientos de Consultas Genéricas, la mayoría construidas para pantallas humanas (cuadrículas de informes amplias, paneles, consultas ad-hoc). Exponerlas todas al asistente satura su contexto y hace que elija la consulta incorrecta — y, peor aún, una GI parametrizada expuesta a través de OData devuelve datos erróneos de forma silenciosa: consultada sin sus parámetros, Acumatica devuelve filas predeterminadas/sin filtrar sin error, lo que el modelo no puede detectar. El control de exposición de GI lo convierte en opt-in: etiquetas las GI que son genuinamente útiles y correctas para que las consulte un agente de IA (ExposedToMCP), y el modelo solo ve esas.

El control está inactivo hasta que lo configures — el servidor se ejecuta, pero sin un registro el asistente no puede descubrir GIs (acumatica_list_generic_inquiries no devuelve nada; un usuario aún puede ejecutar una GI por su nombre exacto). Configurarlo le proporciona al asistente un conjunto seleccionado que puede descubrir de forma segura. Habilitarlo es un proyecto de personalización de Acumatica de una sola vez — incluido en acumatica/, agrega los campos personalizados UsrExposedToMCP / UsrAIDescription (GIDesign) y UsrResAIDescription (GIResult) junto con los cambios en el formulario SM208000 — seguido de las GI de feed MCPGIs / MCPGIFields, acceso de lectura a los feeds para el rol MCP Access, y etiquetar las GI que deseas exponer. Consulta docs/generic-inquiries.md.

Consulta Generic Inquiries para conocer la justificación completa, cómo decidir qué GIs exponer y la configuración paso a paso.

Dominio personalizado (opcional)

El despliegue te proporciona un nombre de host *.workers.dev de forma predeterminada. Para adjuntar un nombre de host con marca:

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

• A través de wrangler.jsonc: descomenta el bloque routes al principio del archivo, edita pattern y zone_name, vuelve a desplegar.

Si cambias los nombres de host, recuerda agregar la nueva https://<host>/callback a las URI de redireccionamiento de tu Aplicación Conectada en SM303010.

Conectando Claude

Claude.ai / Claude Desktop

1. Ve a Settings > Connectors

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

3. En el primer uso, serás redirigido a tu 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 procesamiento de datos de 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 (a través del SDK de Anthropic)

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 registro dinámico de clientes en /register.

Herramientas Disponibles

Núcleo

Financiero / Contabilidad

Inventario y Almacén

Compras

Proyectos

Servicio y Campo

Ventas y CRM

Envío y Cumplimiento

RRHH y Nómina

Actividades de CRM

Utilidad / Descubrimiento

Consejo: Usa acumatica_describe_entity primero para descubrir campos disponibles, luego acumatica_list_entities para buscar/filtrar. Para Consultas Genéricas, usa acumatica_list_generic_inquiries para encontrar nombres de GI y acumatica_describe_inquiry para ver los campos disponibles. Consulta docs/example-prompts.md para patrones de uso.

Documentación

La documentación detallada está disponible en la carpeta docs/:

• Tool Reference -- Especificación completa de las 49 herramientas con parámetros y endpoints

• Example Prompts -- Ejemplos de prompts para Claude y otros clientes MCP organizados por caso de uso

• OData Filtering Guide -- Guía de los parámetros de consulta $filter, $orderby, $select, $expand y $top

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

• Schema Knowledge -- Herramientas de descubrimiento de esquemas fuera de línea para construir integraciones/personalizaciones, y cómo se construye el índice de esquemas

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

• Self-Hosting Guide -- Cómo ejecutar el servidor MCP en Node.js u otras plataformas fuera de Cloudflare

• Upgrading Acumatica -- Pasos a seguir al cambiar o actualizar la versión de Acumatica conectada

Skills

Skills reutilizables de Claude que se incluyen con este repositorio, en skills/:

• acumatica-gi-descriptions -- Proceso de principio a fin para escribir descripciones orientadas a IA para Consultas Genéricas y sus columnas de resultado, basado en los metadatos de diseño de la propia GI (tablas, uniones, condiciones WHERE, columnas) en lugar de adivinarlos a partir de los nombres. Incluye los puntos conflictivos de la plataforma que hacen que el trabajo con metadatos de GI a gran escala falle silenciosamente, una lista de verificación de señales de diseño que vale la pena buscar, y tres scripts para auditoría de truncamiento, informe de diseño y validación de borrador.

Para usarlo, apunta Claude al directorio de skills, o cópialo 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 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 clave-valor de la plataforma (Cloudflare KV en la implementación predeterminada), con alcance a su nombre de usuario. Los tokens se renuevan automáticamente cuando caducan. 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 pueden leer una Generic Inquiry canary designada pueden conectarse. El servidor verifica la legibilidad de GI a través de OData durante el inicio de sesión (no la pertenencia a roles); los usuarios sin acceso ven una página de acceso denegado. Restrinja la GI como desee — un rol marcador MCP Access es la forma recomendada. El nombre de la GI se puede configurar mediante ACUMATICA_CANARY_GI.

• Intersticial de consentimiento. Después de pasar la verificación de acceso, los usuarios deben reconocer que sus datos serán procesados por un modelo de IA externo antes de que la sesión MCP se active.

• Redacción de campos sensibles. Las respuestas de las herramientas se escanean automáticamente en busca de nombres de campos sensibles (SSN, cuentas bancarias, salario, tarjeta de crédito, etc.) y los valores coincidentes se reemplazan con [REDACTED]. Los patrones se pueden configurar mediante las variables de entorno REDACT_PATTERNS y REDACT_SKIP.

• Rechazo 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 restrictivo en lugar de recuperar más registros.

• Registro de auditoría. Todas las invocaciones de herramientas, eventos de autenticación (inicio de sesión exitoso/denegado, consentimiento aceptado) y eventos de redacción de campos se registran como JSON estructurado. Ver con npx wrangler tail.

Portabilidad de plataforma

Si bien la implementación predeterminada está dirigida a Cloudflare Workers, los manejadores de herramientas y las bibliotecas principales 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 implementaciones autogestionadas en Node.js con Redis, SQLite u otros backends de almacenamiento. Consulte la Guía de autogestión para obtener más detalles.

Pila tecnológica

• Entorno de ejecución: Cloudflare Workers + Durable Objects

• MCP: SDK agents (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.