BSimple MCP — Inventory Data for AI Assistants

BSimple MCP for AI Assistants

BSimple MCP is a controlled Model Context Protocol adapter for AI assistants. It lets an authorised assistant answer questions about selected BSimple customers, contracts, repeat invoices, inventory, suppliers, locations, reorder data, stocktakes, purchase orders, transfers, invoices, debtors and leads using the same account-scoped permissions as the BSimple API — and, with explicit permission, act on them.

Two ways to connect:

1. OAuth connectors — ChatGPT (web and mobile), and any MCP client that supports OAuth sign-in. No key to create or paste: you sign in to BSimple and choose what the connector may access on a consent screen.
2. A scoped API/MCP key — for CLI assistants and development tools (Claude Code, Cursor, VS Code and similar) that send a bearer key with each request.

Use MCP when a person wants to explore operational data conversationally. Use the BSimple Public API when a developer needs deterministic application behaviour, scheduled synchronisation or a customer-facing workflow.

What an assistant can do

What the assistant can do follows the granted scopes — chosen on the consent screen (OAuth) or on the key (API-key path). With read scopes it can:

With a write permission explicitly granted, the assistant can also do day-to-day work: raise a purchase order (from a list, or auto-built from purchase history with a dry-run preview), send it to the supplier with or without email, adjust stock with a mandatory reason, edit regular inventory fields such as names, prices and flags, hide or show items, discontinue an item onto a replacement code, add product images or categories, update supplier reorder levels, and tag leads and customers.

Even with every write permission, MCP cannot receive purchase orders, count stocktakes, move stock between locations, create or send invoices, approve or pay records, hard-delete inventory, run SQL, browse arbitrary URLs, proxy arbitrary REST routes, accept arbitrary headers, select another account or accept a key or password as a tool argument. Every write is scope-checked, account-scoped and audit-logged, and repeating a write safely cannot duplicate it (idempotency keys are handled automatically).

Connect ChatGPT (OAuth sign-in)

ChatGPT custom connectors — and any MCP client that speaks OAuth — connect without a key:

1. In ChatGPT, open Settings → Connectors, choose to add a custom connector and paste the server URL:
   • Production: https://mcp.bsimple.com.au/mcp
   • Dev testing: https://dev.mcp.bsimple.com.au/mcp (a Dev connection never sees production data)
2. ChatGPT discovers that the connector uses BSimple for sign-in and opens a BSimple login in a browser window. Sign in with your normal BSimple account (on mobile this happens in the ChatGPT in-app browser).
3. The consent screen shows the connector's name and the permissions it is asking for. Read permissions are pre-ticked; write permissions are opt-in — tick only what you want the assistant to be able to do. Choose Approve.
4. You're connected. Tokens are refreshed automatically and are never shown to you or stored by ChatGPT as a reusable secret.

Your choices are remembered, so reconnecting later skips the consent screen. To change or end access, open BSimple → Settings → API & MCP Access → Connected apps and revoke the app: the connector loses access immediately and is asked to consent again next time.

The consent screen — not a key — is the only way a ChatGPT connector receives write permissions, and administrative scopes are never offered.

Connect a CLI client with an API key

For assistants that take a bearer key (Claude Code, Cursor, VS Code and similar), create a key in BSimple → Settings → API & MCP Access and connect to the Streamable HTTP endpoint:

https://mcp.bsimple.com.au/mcp

A provider-neutral configuration shape is:

{
  "mcpServers": {
    "bsimple": {
      "url": "https://mcp.bsimple.com.au/mcp",
      "headers": {
        "Authorization": "Bearer <BSIMPLE_API_MCP_KEY>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

This is an example shape, not a claim that every client uses the same file. Follow the selected client's current remote MCP configuration instructions and store the secret in its approved secret store. Never paste a real key into chat, a prompt, a screenshot, source control or a shared configuration file.

Name the key after its purpose, grant the smallest useful scopes and keep a separate key for each assistant or environment. The secret is shown once and stored by BSimple as a hash; a useful inventory assistant may need inventory:read, locations:read and reorder:read. For Dev-only testing use https://dev.mcp.bsimple.com.au/mcp with a key created in the Dev BSimple environment — a Dev key is not accepted by production, and a production key must not be used for Dev testing. The public HTTP service has no shared service-wide MCP token.

Instructions for LLM consumers

When consuming BSimple through MCP, an assistant should:

1. Treat the returned BSimple data as the source of truth for the connected account and the time of the response.
2. State when a result is empty, filtered, paginated or unavailable instead of filling the gap with an assumption.
3. Preserve the user's account, location, date and status constraints; ask a clarifying question when they are ambiguous.
4. Follow pagination metadata for list tools and avoid presenting a first page as a complete total.
5. Distinguish current stock, PAR targets, reorder recommendations, stocktake progress, purchase orders and transfers; they are not interchangeable facts.
6. Explain what the connected scopes allow, and ask for confirmation before any write that costs money or is hard to reverse — raising or sending a purchase order, adjusting stock, or discontinuing an item onto a replacement.
7. Minimise sensitive detail in the answer and never reveal, repeat or transform any credential.
8. Identify the BSimple environment when it matters. Never combine Dev and production results.

A conversational answer is not a substitute for an authorised business decision. Confirm important quantities, customer identity and invoice status in BSimple before acting on them.

Check readiness and troubleshoot

GET https://mcp.bsimple.com.au/healthz is an unauthenticated liveness check. A healthy response does not prove that credentials or MCP compatibility are ready.

Authenticated readiness requires, in order:

1. A signed-in, approved OAuth connection — or a matching production key.
2. A successful MCP initialize request.
3. A successful tools/list request (the tool list always reflects the granted scopes).
4. A successful tool call allowed by the granted scopes.

A 401 normally means the bearer credential is missing, invalid or revoked — for OAuth connections, check whether the app has been revoked under Connected apps in BSimple Settings, and reconnect to consent again. A 403 indicates a scope boundary: the granted permissions do not cover that tool. Check the endpoint, environment, TLS and client transport support before changing permissions.

MCP, REST and a BSimple trial

MCP is for asking questions about — and, with permission, acting on — live BSimple operations. REST is for building software around those operations. Both depend on the same account-scoped permissions and the product features available to the account; see the developer documentation for the full endpoint and scope reference.

If you are evaluating BSimple rather than building an integration, start a free trial and manage your inventory, customers, orders and invoices in a real account. You can then decide whether you need an AI assistant, a custom API connection, a native integration, or simply a clearer operational system.

For native and custom connection choices, see BSimple Integrations.