Tool Reference

Troubleshooting

This page lists common setup and runtime issues.

This page lists common setup and runtime issues.

MCP Client Cannot Connect

Check:

  • API is running.
  • MCP endpoint path is correct.
  • ACUMATICA_MCP_RESOURCE_PATH matches the client URL.
  • public base URL is correct.
  • reverse proxy forwards HTTPS and host headers correctly.
  • client completed MCP authorization.

Default local endpoint:

http://localhost:5240/mcp

OAuth Redirect Mismatch

Symptoms:

  • Acumatica OAuth fails before returning to the MCP server.
  • Error references redirect URI mismatch.

Check:

  • ACUMATICA_OAUTH_REDIRECT_URI
  • Acumatica OAuth application redirect URI
  • public HTTPS URL
  • reverse proxy configuration
  • callback path /oauth/acumatica/callback

The redirect URI must match exactly.

Invalid Swagger URL

Symptoms:

  • entity tools do not load expected schemas
  • startup or tool calls fail when reading Contract API metadata

Check:

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

Make sure the endpoint version and tenant path are correct.

Acumatica 401 Or 403

401 usually means the token is missing, expired, invalid, or not accepted.

403 usually means the user or Acumatica tenant rejected access.

Check:

  • OAuth login completed
  • token storage is working
  • user has Acumatica permissions
  • Acumatica endpoint path is correct
  • requested entity/action is available to that user

Write Or Action Is Denied

This may be expected.

Check allowlists:

ACUMATICA_ALLOWED_WRITE_ENTITIES=Lead,SalesOrder
ACUMATICA_ALLOWED_ACTIONS=SalesOrder/SalesOrderCreateShipment

Destructive and sensitive operations are denied by default until explicitly configured.

Attachment Tool Is Denied

Check:

ACUMATICA_ALLOWED_ATTACHMENT_ENTITIES=Customer,SalesOrder

Attachments are allowlist-controlled separately from writes.

Entity OData v4 Metadata Fails

Check:

ACUMATICA_ENABLE_ENTITY_ODATA_V4_TOOLS=true
ACUMATICA_ENTITY_ODATA_V4_SERVICE_URL=https://example.acumatica.com/odatav4/CompanyName

The service URL should be the service root, without /$metadata and without an entity set segment.

Generic Inquiry Not Visible Through OData

Check:

  • the Generic Inquiry is exposed through Acumatica OData
  • the service root is correct
  • the current Acumatica user can access the inquiry
  • the inquiry is included in ACUMATICA_ALLOWED_GENERIC_INQUIRY_ODATA_INQUIRIES

Example:

ACUMATICA_GENERIC_INQUIRY_ODATA_SERVICE_URL=https://example.acumatica.com/odata
ACUMATICA_ALLOWED_GENERIC_INQUIRY_ODATA_INQUIRIES='BILeadConversion,SO-BI-*'

OData Filter Rejected

Filters are validated before execution.

Common causes:

  • filter too long
  • unsupported function
  • unsafe URL characters
  • field not present in metadata
  • contains() used with Generic Inquiry OData

For Generic Inquiry OData, use safer predicates such as:

  • eq
  • ne
  • gt
  • lt
  • and
  • or
  • startswith
  • endswith
  • tolower

Postgres Connection Fails

Check:

  • Postgres container is healthy.
  • connection string host and port are correct.
  • database/user/password match.
  • network allows API to reach Postgres.

Compose default points the API at host postgres inside the Compose network.

Token Encryption Key Problems

Check:

  • ACUMATICA_TOKEN_ENCRYPTION_KEY_BASE64 is set
  • key decodes to 32 bytes
  • key is stable across restarts
  • key ID is set if using key rotation practices

Generate a key:

openssl rand -base64 32

Public Download URL Does Not Work

Public query export URLs are disabled by default:

ACUMATICA_QUERY_EXPORT_PUBLIC_DOWNLOAD_URLS_ENABLED=false

If enabled, remember:

  • URL token is the download credential
  • public URL is one-time/short-lived
  • endpoint does not require the MCP bearer token

Prefer MCP-authenticated resource reads unless a machine-download URL is required.