MCP server

The Brainerce MCP server exposes a small set of read-only documentation and discovery tools over the Model Context Protocol. AI agents (Cursor, Claude Code, Lovable, custom orchestrators) connect to it to fetch SDK docs, integration guides, and runtime store capabilities while generating code against the Brainerce SDK.

It is intentionally narrow — it does not carry admin credentials, cannot read or mutate merchant data, and is not a substitute for the Public API (v1). Think of it as a documentation oracle that knows a little bit about a specific sales-channel's runtime capabilities.

Endpoint

POST https://mcp-docs.brainerce.com/mcp        (Streamable HTTP transport)
GET  https://mcp-docs.brainerce.com/sse        (legacy SSE transport)
GET  https://mcp-docs.brainerce.com/health     (unauthenticated liveness)

For self-hosting, the server lives at packages/mcp-server/src/bin/http.ts and listens on PORT (default 3100).

Connecting clients

Gemini CLI — install the official extension (bundles the endpoint above plus /brainerce:create-store, /brainerce:add-feature, and /brainerce:verify commands):

gemini extensions install https://github.com/brainerce/ai-toolkit

Claude Code — add the Brainerce marketplace and install the plugin (bundles the endpoint plus the same /brainerce:* commands):

/plugin marketplace add brainerce/ai-toolkit
/plugin install brainerce@brainerce

Claude Desktop — Settings → Connectors → Add custom connector → paste https://mcp-docs.brainerce.com/mcp.

Any other MCP client — paste the Streamable HTTP endpoint (https://mcp-docs.brainerce.com/mcp) into the client's MCP settings, or run the server locally over stdio with npx -y @brainerce/mcp-server.

Store management (admin): this docs server is read-only. To manage a store from an MCP client, connect the separate Admin MCP at https://api.brainerce.com/api/mcp.

Signing in is the primary way in, not an API key. The Admin MCP is an OAuth 2.1 authorization server with dynamic client registration, so a client you have never registered can connect on its own: it opens a browser, the merchant signs in, chooses which store to bind the grant to, approves the scopes, and nothing is copied or pasted. That flow is also a hard requirement for hosted chat clients — ChatGPT's custom connectors require OAuth and will not accept a bearer token at all.

A brainerce_* API key as the Authorization: Bearer header still works, and is the right choice for a headless client that cannot open a browser. In Gemini CLI, /brainerce:connect-admin sets up the key form.

Compact mode — use it unless you know the client can take a few hundred tools. The Admin MCP's full surface is over 340 tool definitions and tens of thousands of tokens, and it keeps growing as features ship. That is over the tool budget of every hosted client we have measured, and a client that cannot load the list ends up with no tools rather than a truncated set. Compact mode serves 8 definitions (roughly 3,000 tokens) instead: search_tools to find a tool by task, the three call_read_tool / call_write_tool / call_destructive_tool dispatchers to invoke it by name, and the widget-bearing tools listed directly. Every tool on the full surface stays reachable through the dispatchers.

The widget-bearing tools are listed directly for a specific reason: OpenAI reads openai/outputTemplate from a tool's own descriptor, never from a call result, so a card can only render if the tool declaring it appears in tools/list. Behind the dispatchers alone those cards were unreachable. Membership is detected from the descriptor, so a new widget tool joins the compact list automatically. ChatGPT is the only host that renders these cards; every other client is text-only in either mode.

Two equivalent ways to select it:

A third address, https://api.brainerce.com/api/mcp/openai, lists 40 tools by name instead of putting them behind a search step. It carries the store-operations set — products, stock, categories, tags, orders, fulfilment, customers, coupons, discount rules, product reviews, sales channels and the analytics summaries — and nothing else: no content, media, email, shipping, tax or settings tools, which stay reachable through compact mode's dispatchers. At roughly 15,000 tokens it loads in ChatGPT (verified against production, including the widget cards), so it is the address to prefer there when the actions it carries are the ones you need, with compact mode as the fallback for anything outside that set.

Prefer the path form anywhere the URL is stored and replayed by someone else — an app-directory submission, a connector registry, a config UI — because a query string may not survive the round trip. The query form stays supported for existing integrations. Anything other than exactly mode=compact is a 400, never a silent fall back to the full list.

Telemetry: each MCP initialize logs the connecting client's self-reported name/version and User-Agent (adoption metrics). Queries, tool arguments, and content are never recorded.

Authentication

None — the server is public by design. Everything behind it is public data: static SDK docs and a handful of public /api/vc/* endpoints that any storefront browser can already call. Paste the URL into your AI tool and it works; no token, no registration. An Authorization header, if sent, is ignored.

Abuse is controlled by rate limits and session caps instead (below), plus Cloudflare in front.

Rate limits & abuse protection

• 60 requests / minute / IP, in-memory token bucket keyed by CF-Connecting-IP.
• SSE session caps: 500 concurrent sessions globally, 5 per IP. Above those, 503 / 429 respectively.
• 4-hour SSE session lifetime, enforced server-side.
• 100 KB request body cap; oversized payloads get 413.
• Header/request reception timeouts guard against slowloris-style connection hoarding.
• The bucket is per-process; if the MCP runs with N replicas the effective limit is N × 60/min.
• Health checks (GET /health) are exempt from rate limiting.

CORS

Browsers can only call the MCP from origins listed in MCP_ALLOWED_ORIGINS (comma-separated). In development localhost on any port is implicitly allowed.

Tools (public surface)

get-store-config / get-product-shape / list-store-products only work against a TEST-mode sales channel — a LIVE channel rejects the request (no browser Origin header from this server) and the affected fields come back explicitly marked unavailable rather than failing the whole call.

Also exposed as MCP resources and prompts:

• Resource sdk-types — static type catalogue
• Prompt create-store — scaffolding skeleton
• Prompt add-feature — feature-addition skeleton

All outbound calls hit public Brainerce endpoints. The MCP does not forward the caller's Authorization header — every call is unauthenticated and returns only public/sales-channel-scoped data.

Configuration env

Security note — BRAINERCE_API_URL

If BRAINERCE_API_URL points at an internal address (e.g. http://10.0.0.5) and the MCP is exposed to the public internet, a caller could potentially use the get-store-info / get-store-capabilities tools to probe internal endpoints (SSRF-class). Always set BRAINERCE_API_URL to a public Brainerce host (https://api.brainerce.com) when the MCP itself is publicly reachable.

Trust boundary

• The MCP holds no Brainerce admin credentials.
• Full compromise of the MCP grants nothing tenant-scoped — at worst, an attacker can make rate-limited requests to the public /api/vc/<id>/* read endpoints the tools above call (info, capabilities, catalog, checkout config, OAuth providers, products — data already exposed to any storefront browser with that connection ID). This is why running it unauthenticated is safe.
• The MCP container runs as non-root, with --frozen-lockfile installs and no baked secrets.

Health

GET /health returns { "status": "ok" } and is exempt from rate limiting (used by deployment health probes).