This repository provides a demonstrative MCP server that implements the Agentic Commerce Protocol (ACP) flow. The MCP server acts as the middle layer that coordinates the Client (LLM interface), Merchant API, and PSP, enabling a simulated commerce interaction where a user can browse, add items to a cart, and complete payments via a delegated PSP flow. The server exposes endpoints for managing checkout sessions, updating session state, cancelation, and retrieving session details, following the ACP spec. It is designed to work with the accompanying demo Merchant API and PSP services and a chat client UI that mirrors the MCP-UI pattern so you can experiment end-to-end in a local environment.

To use it, start all services with the project’s development workflow (npm run dev as described in the Quick Start). The MCP server listens on port 3112 and integrates with the Merchant API (port 4001) and PSP API (port 4000). The chat client frontend connects to the MCP UI-compatible interface and demonstrates how a user can interact with items, carts, and a delegated payment process. Tools and capabilities include:

• Creating and updating checkout sessions via POST /checkout_sessions and POST /checkout_sessions/{checkout_session_id}
• Retrieving session details via GET /checkout_sessions/{checkout_session_id}
• Canceling a session via POST /checkout_sessions/{checkout_session_id}/cancel
• Completing a checkout by providing a delegated payment token to the Merchant via the appropriate endpoint The demo focuses on illustrating the ACP flow end-to-end, including how the Client, Merchant, and PSP exchange state and tokens throughout a simulated shopping experience.

Prerequisites:

• Node.js 20+ installed on your machine
• Docker and Docker Compose (for local DB and dependent services)
• Git to clone the repository

Installation steps:

1. Clone the repository and navigate into it: git clone https://github.com/locus-technologies/agentic-commerce-protocol-demo cd agentic-commerce-protocol-demo

2. Install dependencies (this is a monorepo with multiple workspaces; npm install will install across all demo services and the chat client): npm install

3. Configure the chat client keys (if you plan to use the chat UI): cd chat-client cp .env.example .env

   edit .env to supply OPENAI_API_KEY and/or ANTHROPIC_API_KEY

   cd ..

4. Start all services (MCP server, Merchant API, PSP, and databases) in development mode: npm run dev

5. Access the MCP server and UI:

   • MCP server runs on port 3112 by default
   • Merchant API on port 4001
   • PSP API on port 4000
   • Chat client UI typically served at http://localhost:3000 (when started)

Note: The demo uses Docker to spin up PostgreSQL databases and other services as part of the dev workflow. Ensure Docker is running before starting the dev script.

Tips and considerations:

• This is a demo sandbox; all payments are mocked and no real transactions occur.
• The MCP server path in this configuration points to the demo MCP UI server implemented under demo/mcp-ui-server. If you reorganize folders, adjust the path accordingly.
• Environment variables like DATABASE_URL should be provided by your local environment or Docker Compose setup. The defaults shown here are placeholders for local development.
• If you encounter port conflicts, stop any existing services using those ports or adjust the MCP/Merchant/PSP ports in the environment configuration.
• The ACP flow assumes standard ACP endpoints (checkout_sessions, session updates, cancel, and complete) and token-based delegated payments; refer to the OpenAI ACP docs for exact payload formats and headers.
• For production-like usage, consider separate environment configurations for dev, staging, and prod and secure your API keys properly.