Connectors

Connecting an AI Agent to Brightpearl: When There Is No First-Party MCP Server

By IdeaBosqueLast updated: July 22, 2026

Key takeaways

Zero first-party MCP coverage — Brightpearl has no vendor-shipped MCP server for store operations, unlike NetSuite (AI Connector), Shopify (Storefront MCP + UCP), and HubSpot (Remote MCP Server). The custom module is the integration, not a gap-filler.
200 requests per rolling 60-second period, HTTP 503 when exceeded — the Brightpearl REST API throttle. Private apps share one pool per account. No tiered caps, no plans to increase. An agent making 30 parallel tool calls can exhaust the window in seconds.
76 data endpoints available through third-party SyncHub MCP, but read-only — the only managed MCP server for Brightpearl is SyncHub, which syncs data to an Azure warehouse and exposes it as a read-only MCP surface. No write-back, no order creation, no inventory updates.
B2B price lists assigned by customer group — the semantic layer no wrapper encodes — Brightpearl's wholesale pricing model (price lists per account, group, or salesperson) is the business meaning a generic API wrapper cannot infer. Which price list applies to which contact for which product is a semantic-layer decision, not a data retrieval.
Anthropic's 2026 State of AI Agents Report identifies integration as the #1 adoption barrier at 46% — for Brightpearl merchants, the barrier is not a gap in a first-party server. It is the absence of one.

The problem: no vendor-shipped agent entry point

The Anthropic 2026 State of AI Agents Report surveyed 500+ technical leaders with real-world implementations at Novo Nordisk, Doctolib, L'Oréal, and Shopify. Integration is the #1 adoption barrier at 46%. For a Brightpearl merchant, that barrier has a specific shape: there is no first-party MCP server to integrate with.

The per-connector series has mapped four vendors so far. NetSuite shipped an AI Connector Service with an MCP endpoint — the custom module fills the semantic-layer gap (which GL accounts are "revenue"). Shopify shipped a Storefront MCP server and co-developed the Universal Commerce Protocol with Google — the custom module fills the B2B gap (customer-tier pricing, bulk RFQ quoting). HubSpot shipped a Remote MCP Server with 12 tools — the custom module fills six capability gaps (custom objects, reviewable writes, headless auth). BigCommerce partnered with Stripe on the Agentic Commerce Suite — the custom module fills the B2B Price List and Customer Group gap.

Brightpearl is the fifth case, and the pattern is different. Brightpearl is a Retail Operating System for mid-market retail and wholesale brands at $1M–$20M revenue. It is a Shopify Global ERP Program partner with a native Shopify integration — inventory updates in seconds, automated order routing, unified customer history. It has a REST API that is the same API Brightpearl's own developers use, covering orders, products, contacts, inventory, accounting, and warehouse operations. What it does not have is an MCP server. No Storefront MCP, no AI Connector, no Remote MCP Server, no docs-only MCP. The vendor has not shipped an agent entry point.

This article maps the three agent integration paths that exist, the semantic-layer gaps in each, and the custom MCP module pattern that makes Brightpearl agent-ready. The framing is different from the prior connector articles: here, the custom module is not a complement to a first-party server. It is the integration.

The three agent integration paths

Path 1: SyncHub — read-only MCP with no write-back

SyncHub offers a plug-n-play MCP server that connects Brightpearl data to AI chatbots. It incrementally syncs data from 76 Brightpearl endpoints into an AI-optimized database hosted in Microsoft Azure (Sydney data center), then wraps that database in an MCP-compliant interface. The agent queries the synced data through natural language, and SyncHub's SQL-generation engine returns only the necessary rows — reducing token usage. It supports 70+ connectors beyond Brightpearl, so a merchant running Brightpearl plus Shopify plus Xero can query across all three in a single conversation.

The limitation is structural: SyncHub is read-only. The FAQ states it plainly: "Update Brightpearl? No — SyncHub is read-only." An agent that needs to create a sales order, update inventory levels, modify a customer record, or post a payment cannot do it through SyncHub. The MCP surface is a query layer, not an action layer. For analytics and reporting use cases — "show me overdue accounts receivable across all channels" or "which suppliers delivered the highest margins last quarter" — SyncHub is a genuine product. For an agent that orchestrates quoting workflows, processes RFQs, or automates order fulfillment, it is not the integration path.

Path 2: Composio / Rube MCP — generic wrapper with no B2B semantic layer

The second path is a generic API wrapper. Composio's Rube MCP provides a Claude Code skill that wraps the Brightpearl REST API for order management, inventory synchronization, and customer record updates. It supports bulk operations through RUBE_REMOTE_WORKBENCH, includes error handling and pagination management, and uses dynamic tool discovery via RUBE_SEARCH_TOOLS for real-time schema compliance. This path can read and write — it wraps the raw API, so any endpoint the API exposes is reachable.

The limitation is the semantic layer. A generic wrapper exposes API endpoints as tools, but it does not encode business meaning. Brightpearl's price list system assigns prices by contact, contact group, or salesperson — a B2B pricing model where the same product carries a different price for each wholesale account based on negotiated terms. The API returns all price lists; the agent does not know which one applies to the current customer for the current product under the current contract terms. That decision is a semantic-layer operation: resolve the customer's contact group, look up the price list assigned to that group, filter by product and quantity tier, and return the contract price. A generic wrapper returns the raw price-list data and leaves the resolution to the model — which is exactly where hallucination risk enters. The MCP Module Code Standard calls this "typed schemas that encode business meaning." The wrapper has types. It does not have meaning.

Path 3: custom MCP module — the integration

The third path is a custom MCP module built against the Brightpearl REST API directly. This is the same structural pattern as the NetSuite, Shopify, and HubSpot modules — but with a different distribution of work. In those cases, the custom module complements a first-party server: the vendor handles connection, the module handles semantics. In Brightpearl's case, the custom module handles both. It is the integration.

The module pattern follows the MCP Module Code Standard: every tool has a typed input schema, a typed output schema, a rate limit, an audit log, and an error contract. The agent calls tools by name with structured arguments, not free-form API calls against raw endpoints. The module encodes the semantic layer — which price list applies to which customer, which order status triggers warehouse routing, which nominal code maps to revenue — as typed schemas that the model does not have to infer.

The API surface: resource-oriented REST with a hard throttle

Brightpearl's API is a clean, resource-oriented REST surface. The API Fundamentals documentation is explicit about the design philosophy: resources, not methods. A resource is any entity Brightpearl manages — contacts, orders, products, warehouses, nominal codes, price lists. Behavior is managed through HTTP verbs: POST creates, PUT/PATCH modifies, GET reads, DELETE removes. JSON for all data exchange. The API is the same one Brightpearl's own developers use — new features are delivered through the same surface that integrators receive.

The request throttling is the production constraint that shapes the module design. The cap is 200 requests per rolling 60-second period. Private apps connected to an account share a single pool — multiple private apps can cause each other to be throttled. Public apps get a separate pool per account/developer combination. When the cap is reached, subsequent requests receive HTTP 503 "Too Busy" responses, and the requests are discarded — not queued. The response headers brightpearl-requests-remaining and brightpearl-next-throttle-period tell the caller how many requests are left and when the window resets. There are no tiered caps and no plans to increase the limit.

For an agent that makes 30 parallel tool calls during a quoting workflow — fetch customer, fetch product, fetch price list, fetch inventory, fetch warehouse availability, create order, post payment — the 200-request window can exhaust in seconds if the module does not enforce per-tool throttling. The custom module handles this the same way the NetSuite module handles its concurrency pool: every tool call checks the remaining-request count from the response headers, and the module enforces a minimum 0.3-second spacing between calls (60 seconds / 200 requests = 0.3 seconds per request). The agent never sees a 503. The module absorbs the throttle.

Authentication: OAuth 2.0 with 7-day tokens

Brightpearl uses OAuth 2.0 Authorization Code Grant for API authentication. The access token expires in 604,800 seconds — 7 days. A refresh token is provided alongside the access token and can be used to obtain a new access token without re-running the browser-based consent flow. Each API call includes the Authorization: Bearer header, plus brightpearl-dev-ref and brightpearl-app-ref headers identifying the developer and application.

The 7-day expiry is more headless-friendly than HubSpot's OAuth 2.1 + PKCE (single-use refresh tokens that rotate on every refresh), but less headless-friendly than BigCommerce's X-Auth-Token (store-scoped bearer tokens that do not expire unless revoked). A background agent that runs nightly inventory syncs or scheduled order processing can use the refresh token to maintain access across weeks, as long as the module handles the refresh cycle internally — checking token expiry before each call, refreshing transparently, and logging the refresh event in the audit trail.

The private app path is the simpler auth model for internal integrations. A private app is created in the Brightpearl account's App Store, uses staff credentials, and does not require the full OAuth flow. This is the equivalent of NetSuite's Token-Based Authentication (TBA) — the production standard for unattended operations. The custom module supports both paths: OAuth 2.0 for public-app integrations that serve multiple Brightpearl accounts, and private app credentials for single-account headless agents.

The B2B semantic layer: price lists, customer groups, and the meaning gap

Brightpearl's wholesale management capabilities are the core differentiator that makes a custom module necessary rather than optional. The platform supports individual price lists by account, group, or salesperson — a B2B pricing model where the same SKU carries a different price for each wholesale customer based on negotiated contract terms. It handles proforma invoices, payments on account, deposits, and part payments. It manages multi-warehouse routing, dropshipping, partial fulfillment, and back-to-back ordering through its Automation Engine.

The semantic-layer gap is the same structural pattern that appears in every connector article, but it has a specific shape here. The Brightpearl Product Price resource returns prices for a product across all price lists. The Price List resource returns the list of price lists in the system. The Contact resource returns the contact's assigned price list. But the API does not resolve the question "what price does this specific customer pay for this specific product at this specific quantity?" — that resolution requires joining the contact's price list assignment to the product's price on that list, filtered by quantity tier and channel. A generic wrapper returns the raw data and leaves the join to the model. A custom module encodes the join as a typed tool: get_contract_price(contact_id, product_id, quantity, channel_id) returns a single number with a provenance trail showing which price list, which tier, and which assignment produced it.

This is the same gap that NetSuite has (which GL accounts are "revenue"), that Shopify has (which price applies to which customer tier), and that HubSpot has (which deal stages count toward forecast). The vendor's API exposes the data. The semantic layer — the business meaning that turns data into a decision — is what the custom module encodes. The difference for Brightpearl is that no first-party server exists to handle the easy half. The custom module handles both halves.

The Shopify connection: Brightpearl as the ERP behind the storefront

Brightpearl's native Shopify integration is pre-built and managed in-house — inventory updates in seconds, automated order routing to warehouses, customer history unified across channels. Brightpearl is a Shopify Global ERP Program partner, meaning the integration meets Shopify's performance and user-experience standards for the App Store. The program launched October 2021 and targets enterprise merchants running complex, high-volume retail businesses on Shopify Plus.

For agent orchestration, this creates a two-system stack: Shopify handles the storefront and the consumer-facing agent surface (Storefront MCP, UCP), and Brightpearl handles the back-office operations (orders, inventory, accounting, warehouse routing). The custom Brightpearl MCP module is the back-office half of the agent stack. An agent that receives a B2B order through Shopify's UCP can hand off to the Brightpearl module for inventory reservation, price-list resolution, order creation, and warehouse routing — without the agent needing to understand Brightpearl's API surface. The module translates between the commerce protocol layer (UCP/ACP) and the ERP resource layer (Brightpearl REST).

Brightpearl reports a 97% implementation success rate and a 120-day average go-live time, against an industry average of 420 days for traditional ERPs. For a mid-market merchant at $1M–$20M revenue, the implementation economics matter: Brightpearl at $1,500–$3,000 per month with a 4–8 week implementation is a different cost structure than NetSuite at $5,000–$15,000 per month with an 8–20 week implementation. The agent integration follows the same curve — a custom Brightpearl MCP module is a smaller build than a custom NetSuite module because the API surface is smaller and the data model is more opinionated.