What building MCP for a five-platform product taught us

commerce intelligence runs natively inside five commerce platforms. When we added an MCP server so agents could query the same co-purchase intelligence, we expected a thin wrapper job. It wasn't, and the reasons are useful to anyone connecting Claude to real systems.

1. The agent is a new kind of user

Admin-panel users see ranked lists with context; an agent gets whatever your tool definitions expose. We rewrote tool descriptions three times before agents stopped mis-calling them. The lesson: tool descriptions are UX copy. Write them like you'd write for a sharp colleague with no context, and test them with evals like everything else.

2. Scope is a security boundary, not a convenience

A merchant's MCP token should answer “what bundles should I run this month?”, and be structurally unable to touch another store's data or mutate anything the merchant didn't intend. We treat every MCP capability as a permission grant and default to read-only. When we consult on MCP integrations, this is the first thing we audit, because it's the first thing done carelessly.

3. Deterministic beats clever at the boundary

Agents retry, rephrase, and batch oddly. Endpoints behind MCP need to be idempotent, cheap to call twice, and honest about errors, an agent that gets a vague failure will happily hammer you. Boring API discipline turns out to be the load-bearing wall of agentic systems.

The payoff is real: intelligence that lived in one admin tab is now available wherever the merchant's agents work. That's the shape we expect most B2B software to take, and why MCP work is a core part of our consulting practice.