mcp-ecom-agent-layer

The AI-access layer for the mcp-ecom storefront: an MCP server exposing nine e-commerce capabilities to agents, and — from Phase 2 onward — the agents themselves.

Status: Phase 1 (MCP server) complete. No agent exists yet.

→ Technical Snapshot — the whole service in one document: architecture, the nine tools, the security model, deployment and known limits.

→ Iterations — how it was built: what worked, what failed, and how to replicate this service from scratch.

→ M4 Plan — what comes next: the agent that uses these nine tools, and how it is kept from approving itself.

Both carry a plain-language summary in every section, so they read for technical and non-technical audiences alike.

What this is

MCP Client  ->  this server  ->  mcp-ecom /api/v1  ->  Postgres

An adapter, not a second implementation. Business logic — may this order be cancelled, is there stock, who owns this cart — stays in the storefront's API. This server never touches the database and never re-implements a rule, because the value of an adapter is that there is exactly one implementation of each rule.

Related MCP server: E-Commerce MCP Server

The tools

Low executes silently. Medium executes and is surfaced as an informational event. High is refused at the server without a valid approval token, regardless of what the caller intended.

Two things worth understanding before changing anything

Identity is never an argument. The server derives the caller from the bearer token by asking GET /api/v1/auth/whoami. It does not decode the token itself: NextAuth v4 mints an encrypted JWE, so reading a subject out of one in Python would mean a second implementation of NextAuth's key derivation, which would break silently the day that changes.

Approval tokens are bound, not merely present. Each is HMAC-signed over (session, tool, argument hash, nonce, expiry) and single-use. The argument hash is the part that matters: without it, approval to cancel order #3 is approval to cancel order #7, and a prompt-injected agent can talk itself past a confirmation step. Approvals are minted only by the POST /approvals HTTP route, which is deliberately not an MCP tool — an agent that can approve itself makes the mechanism theatre.

Running it

python -m venv .venv
.venv/Scripts/pip install -r requirements-dev.txt      # Scripts/ on Windows, bin/ elsewhere
.venv/Scripts/python -m pytest

MCP_APPROVAL_SECRET=<32 random bytes> .venv/Scripts/python server.py

Serves streamable HTTP on $PORT (default 8000). Deliberately not stdio: a stdio process carries one ambient identity, which is wrong for a multi-user app — every caller would share whichever token the process started with.

Known limitations

These are honest gaps, not oversights. Each needs closing before this is more than a demo.

• Prompt injection via tool output is unmitigated. Product descriptions and review text are attacker-controllable and flow into agent context through low-risk tools. Approval tokens close the execution path only.

• The spent-nonce set is in process. Single-use holds for one replica; scale out and a token becomes replayable within its TTL.

• Approvals defend the agent path, not the API. Anyone holding a bearer token can still call the cancel endpoint directly. That is unchanged and by design — the API's own defence is ownership plus status rules.

• Session JWTs cannot be revoked. Short lifetimes bound the exposure; nothing shortens it to zero.

Provenance

Split out of the mcp-ecom monorepo, where it was built as apps/mcp during milestone M3. The design documents, phase plans and the reasoning behind each decision live there under docs/mcp/.