Skip to main content

ACP Engine

ACP Engine is the public runtime entrypoint for Agentic Commerce integrations. It is deployed as a thin public engine app plus internal Go microservices.

The public /api/v1 contract stays stable for Manager, web, mobile, SDK, and ADK clients. The unified mcp-service exposes approved Engine and Catalog capabilities over MCP JSON-RPC while also owning internal MCP management and execution. Domain execution happens in internal services.

Architecture​

Expose the engine for REST API traffic and the public paths of mcp-service for MCP JSON-RPC traffic. Auth, runtime, AI, usage, Catalog, and Enrichment remain private by default. A dedicated Catalog ingress is optional for approved merchant integrations and must retain Auth-backed merchant/store scope enforcement.

Services​

  • engine/cmd/server: public engine.
  • services/auth/cmd/server: authentication, users, realms, memberships, API keys, and themes.
  • services/runtime/cmd/server: durable execution, profile-based agent resolution, flows and generated drafts, delegated agents, compensation, prompts, sessions, context, agent policy, and routing rules.
  • services/ai/cmd/server: AI chat, usage, realm text/image provider management, and provider calls.
  • services/mcp/cmd/server: public MCP facade, built-in Catalog tools, MCP server management, discovery, routing, proxying, and tool execution.
  • services/usage/cmd/server: usage records, transaction counting, and usage summaries.
  • services/catalog/cmd/server: merchant/store products, carts, checkouts, orders, and Catalog events.
  • services/enrichment/cmd/server: internal Manager-facing store Enrichment execution, merchant providers, and usage.

Configuration​

Engine environment:

PORT=8080
JWT_SECRET=change-this-to-a-random-secret-key
AUTH_SERVICE_URL=http://auth-service:8081
RUNTIME_SERVICE_URL=http://runtime-service:8082
AI_SERVICE_URL=http://ai-service:8083
MCP_SERVICE_URL=http://mcp-service:8084
USAGE_SERVICE_URL=http://usage-service:8085
CATALOG_SERVICE_URL=http://catalog-service:8086

Internal service environment:

PORT=8081
DB_URL=postgres://acp:acp@postgresql:5432/acp_engine?sslmode=disable
REDIS_URL=redis://redis:6379/0
JWT_SECRET=change-this-to-a-random-secret-key
API_KEY_ENCRYPTION_KEY=change-this-to-a-32-character-key

Catalog uses AUTH_SERVICE_BASE_URL=http://auth-service:8081/api/v1 and calls /auth/verify and /auth/introspect for merchant API keys. Its Docker Compose port is 8086; Enrichment uses 8087.

Each internal service connects to PostgreSQL directly. Redis is optional and enabled when REDIS_URL is set. Services do not connect through the engine.

MCP server registration and updates call downstream tools/list by default and persist the discovered tool registry in PostgreSQL. Route/execute calls can use this registry to pick the matching MCP server when the caller provides only a tool name.

The runtime exposes POST /api/v1/runtime/ai/chat as the primary conversational/BFF contract and POST /api/v1/runtime/execute as the structured sync/async contract. Both use the same automatic/explicit Flow resolver. Public direct MCP execution and versioned published-flow MCP tools enter the same runtime boundary so identity, policy, approvals, reliability limits, usage, and trace behavior stay consistent across REST and MCP clients.

Unified MCP service public-facade environment:

PORT=8084
ENGINE_BASE_URL=http://engine:8080
MCP_SHARED_SECRET=
MCP_ALLOWED_ORIGINS=*

MCP callers use a merchant API key for built-in Catalog tools:

  • Authorization: Bearer <merchant_api_key>; or
  • x-api-key: <merchant_api_key>.

Realm-bound Engine tools authenticate with a realm service identity:

  1. Create a service identity through POST /api/v1/realms/:id/identities/services.
  2. Send the returned access_key and secret_key to MCP with the target realm:
    • X-ACP-Realm-ID
    • X-ACP-Access-Key
    • X-ACP-Secret-Key

The MCP service validates realm credentials for Engine tools and merchant key scope for Catalog tools. These identity systems are independent.

MCP_SHARED_SECRET is optional transport-level protection. When set, MCP clients must also send it in X-MCP-API-Key or X-ACP-API-Key.

Local Development​

From the repository root:

docker compose up --build

The engine is available at:

http://localhost:8080/api/v1/health

The unified MCP service is available at:

http://localhost:8084

Build Targets​

Standalone service Dockerfiles:

  • services/auth/Dockerfile
  • services/auth/Dockerfile.dev
  • engine/Dockerfile
  • engine/Dockerfile.dev
  • services/runtime/Dockerfile
  • services/runtime/Dockerfile.dev
  • services/ai/Dockerfile
  • services/ai/Dockerfile.dev
  • services/mcp/Dockerfile
  • services/mcp/Dockerfile.dev
  • services/usage/Dockerfile
  • services/usage/Dockerfile.dev
  • services/catalog/Dockerfile
  • services/catalog/Dockerfile.dev
  • services/enrichment/Dockerfile
  • services/enrichment/Dockerfile.dev

Deployment​

The Helm chart lives in:

deployment/helm-chart

The current chart deploys Manager, one public Engine application, the unified MCP service, auth, runtime, AI, usage, and optional Redis. The engine is the public REST entrypoint and mcp-service is the public MCP JSON-RPC entrypoint. Docker Compose additionally defines Catalog and Enrichment as private domain services. Confirm the target chart version includes those workloads before using Catalog or Enrichment in a Kubernetes release.

Deployment readiness is covered by:

  • Docker Compose service definitions for independent local workloads.
  • Per-service production and development Dockerfiles.
  • Helm templates for Deployments, Services, probes, HPAs, PDBs, NetworkPolicies, Secrets, ConfigMaps, and separate engine/manager/MCP ingress.
  • CI/build assets for backend services, Manager, and container registry provider image publishing.
  • Route parity and proxy fixture tests for critical public endpoints.
  • Structured logs, request IDs, trace IDs, traceparent propagation, signed internal service headers, and realm/user propagation headers.