Developer Setup

Quick Start

Use Docker Compose to run Acumatica MCP Tools locally for a self-hosted technical evaluation.

This page is for local technical evaluation of a self-hosted Acumatica MCP Tools deployment. It gets the API and Postgres running with Docker Compose, then validates OAuth and the default MCP endpoint.

Prerequisites

  • .NET SDK compatible with the project.
  • Docker and Docker Compose.
  • Access to an Acumatica tenant.
  • Acumatica OAuth client ID and secret.
  • Acumatica endpoint URL and Swagger URL.
  • A 32-byte base64 token encryption key.

Clone And Configure

Create a .env file in the repository root.

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_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'

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

ACUMATICA_TOKEN_STORE_PROVIDER=Postgres
ACUMATICA_TOKEN_ENCRYPTION_KEY_BASE64=replace-with-generated-key

Generate a token encryption key:

openssl rand -base64 32

Start With Docker Compose

docker compose up --build

The API listens on:

http://localhost:5240/

The default MCP endpoint is:

http://localhost:5240/mcp

Check The Service

Open:

http://localhost:5240/

Expected result:

  • service name
  • MCP path
  • OAuth helper endpoints
  • configured Acumatica base URL

Connect Acumatica OAuth

Start the Acumatica OAuth flow:

http://localhost:5240/oauth/acumatica/login

After authorization, the server stores the user’s Acumatica OAuth token using the configured token store.

Connect An MCP Client

Use the MCP endpoint:

http://localhost:5240/mcp

The client must complete MCP authorization before it can call tools.

First Safe Test

Start with read-only tools:

  • search available Contract API entities
  • inspect schema
  • query a small record list
  • query a Generic Inquiry if configured

Do not enable writes, deletes, attachments, or actions until you have reviewed the safety model and allowlists.

Next Reading