Configuration Reference

Use this page as a reference after choosing a deployment path. For a first local run, use Quick Start. For Compose service behavior, use Docker Deployment.

Acumatica Connection

These values point the server at the Acumatica tenant and Contract REST endpoint it should use.

ACUMATICA_BASE_URL=https://example.acumatica.com/entity/Default/25.200.001
ACUMATICA_SWAGGER_URL=https://example.acumatica.com/entity/Default/25.200.001/swagger.json
ACUMATICA_SITE_URL=https://example.acumatica.com

ACUMATICA_BASE_URL points to the Contract REST API endpoint.

ACUMATICA_SWAGGER_URL points to the Contract REST API Swagger document.

ACUMATICA_SITE_URL points to the Acumatica site used for OAuth.

Acumatica OAuth

Live Acumatica calls use the current user’s Acumatica OAuth authorization. The redirect URI configured in Acumatica must match the server value exactly.

ACUMATICA_OAUTH_CLIENT_ID=your-client-id
ACUMATICA_OAUTH_CLIENT_SECRET=your-client-secret
ACUMATICA_OAUTH_REDIRECT_URI=http://localhost:5240/oauth/acumatica/callback
ACUMATICA_OAUTH_SCOPE='api offline_access openid'

Use an HTTPS redirect URI for remote or production environments.

MCP Public Endpoint

These values describe the public MCP endpoint that clients use.

ACUMATICA_MCP_PUBLIC_BASE_URL=http://localhost:5240
ACUMATICA_MCP_ALLOWED_ORIGINS=http://localhost:5240
ACUMATICA_MCP_RESOURCE_PATH=/mcp

ACUMATICA_MCP_PUBLIC_BASE_URL must match the public URL clients use.

ACUMATICA_MCP_RESOURCE_PATH defaults to /mcp.

Token Storage

Use Postgres-backed token storage for production-like environments. File storage is only for local development.

ACUMATICA_TOKEN_STORE_PROVIDER=Postgres
ACUMATICA_POSTGRES_CONNECTION_STRING='Host=localhost;Port=5432;Database=acumatica_mcp;Username=acumatica_mcp;Password=change-me'
ACUMATICA_TOKEN_ENCRYPTION_KEY_BASE64='<32-byte-base64-key>'
ACUMATICA_TOKEN_ENCRYPTION_KEY_ID=prod-2026-05

Generate a token encryption key:

openssl rand -base64 32

Local development file storage:

ACUMATICA_TOKEN_STORE_PROVIDER=File
ACUMATICA_ALLOW_PLAINTEXT_FILE_TOKEN_STORE=true

Do not use plaintext file token storage for production.

Contract API Allowlists

Writes, deletes, attachments, and actions are denied unless allowlisted. Keep these values scoped to the first approved workflow.

ACUMATICA_ALLOWED_WRITE_ENTITIES=Lead,SalesOrder
ACUMATICA_ALLOWED_DELETE_ENTITIES=
ACUMATICA_ALLOWED_ATTACHMENT_ENTITIES=Customer,SalesOrder
ACUMATICA_ALLOWED_ACTION_ENTITIES=
ACUMATICA_ALLOWED_ACTIONS=SalesOrder/SalesOrderCreateShipment

Values can be comma, semicolon, or space separated.

Wildcard values are supported:

ACUMATICA_ALLOWED_WRITE_ENTITIES='*'

Use wildcard destructive allowlists only in short-lived sandbox QA.

Entity OData v4

Enable Entity OData v4 only when the workflow needs read access through that Acumatica service. Limit access to approved entities or namespaces.

ACUMATICA_ENABLE_ENTITY_ODATA_V4_TOOLS=true
ACUMATICA_ENTITY_ODATA_V4_SERVICE_URL=https://example.acumatica.com/odatav4/CompanyName
ACUMATICA_ALLOWED_ENTITY_ODATA_V4_ENTITIES='PX.Objects.SO.*,Customer'
ACUMATICA_ENTITY_ODATA_V4_DEFAULT_TOP=10
ACUMATICA_ENTITY_ODATA_V4_MAX_TOP=1000
ACUMATICA_ENTITY_ODATA_V4_MAX_FILTER_LENGTH=2048
ACUMATICA_ENTITY_ODATA_V4_MAX_QUERY_URL_LENGTH=1900
ACUMATICA_ENTITY_ODATA_V4_METADATA_CACHE_SECONDS=3600
ACUMATICA_ENTITY_ODATA_V4_METADATA_SLIDING_CACHE_SECONDS=1800
ACUMATICA_ENTITY_ODATA_V4_AUDIT_REDACT_QUERY_STRING=true

Allowed entity values can be:

• *
• entity set name
• short entity type name
• full EDM type name
• namespace wildcard

Generic Inquiry OData

Enable Generic Inquiry OData when the workflow depends on approved inquiry results. Allowlist the specific inquiries or simple patterns your team has reviewed.

ACUMATICA_ENABLE_GENERIC_INQUIRY_ODATA_TOOLS=true
ACUMATICA_GENERIC_INQUIRY_ODATA_SERVICE_URL=https://example.acumatica.com/odata
ACUMATICA_ALLOWED_GENERIC_INQUIRY_ODATA_INQUIRIES='BILeadConversion,SO-BI-*'
ACUMATICA_GENERIC_INQUIRY_ODATA_DEFAULT_TOP=10
ACUMATICA_GENERIC_INQUIRY_ODATA_MAX_TOP=1000
ACUMATICA_GENERIC_INQUIRY_ODATA_MAX_FILTER_LENGTH=2048
ACUMATICA_GENERIC_INQUIRY_ODATA_MAX_QUERY_URL_LENGTH=1900
ACUMATICA_GENERIC_INQUIRY_ODATA_METADATA_CACHE_SECONDS=3600
ACUMATICA_GENERIC_INQUIRY_ODATA_METADATA_SLIDING_CACHE_SECONDS=1800
ACUMATICA_GENERIC_INQUIRY_ODATA_AUDIT_REDACT_QUERY_STRING=true

Allowed inquiry values can be:

• *
• exact inquiry/entity set name
• exact entity type name
• full EDM type name
• function import name
• simple wildcard pattern

Query Export Cache

Query exports can use Postgres-backed cache storage for larger result sets. Keep public download URLs disabled unless a machine-download flow requires them.

ACUMATICA_CACHE_PROVIDER=Postgres
ACUMATICA_QUERY_EXPORT_DOWNLOADS_ENABLED=true
ACUMATICA_QUERY_EXPORT_PUBLIC_DOWNLOAD_URLS_ENABLED=false
ACUMATICA_QUERY_EXPORT_TTL_SECONDS=60
ACUMATICA_QUERY_EXPORT_DELETE_ON_DOWNLOAD=true
ACUMATICA_QUERY_EXPORT_COMPRESS=true
ACUMATICA_QUERY_EXPORT_MAX_BYTES=10485760
ACUMATICA_QUERY_EXPORT_INLINE_MAX_BYTES=262144
ACUMATICA_QUERY_EXPORT_MAX_ACTIVE_PER_USER=5

OpenTelemetry

OpenTelemetry is optional and should point at your collector when you want traces or metrics in your existing observability stack.

OTEL_SERVICE_NAME=acumatica-mcp-tools
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=0.1.0
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

The OTLP exporter is opt-in. It turns on when standard OTLP endpoint/protocol/header variables are set, or when OpenTelemetry__Otlp__Enabled=true is set.