Red by Big Red Cloud

Red MCP Server

Red is an open-source Model Context Protocol (MCP) server that connects AI assistants and MCP clients to Big Red Cloud accounting data through a set of controlled MCP tools.

Supported customer platforms today are ChatGPT, Claude, Mistral (Vibe), and Microsoft 365 Copilot. Copilot uses a Microsoft federated connector at /mcp/copilot. Because of current Microsoft federated connector limitations, that connector is read-only for now. Create, update and delete tools on Copilot are expected to follow when Microsoft supports them. ChatGPT, Claude and Mistral use /mcp, which already includes those write tools where the deployment enables them. Other MCP clients may work technically, but they are not treated as officially supported platforms. Red uses platform detection only for anonymous operational telemetry (see Privacy-safe telemetry).

Instead of calling the Big Red Cloud REST API directly, users work in plain language. The server translates requests into structured API calls and applies safety checks around anything that changes data.

With Red, a connected user can:

• Review Big Red Cloud data with read-only lookups (customers, suppliers, products, invoices, quotes, nominal reports, and more).
• Review before posting — see a plain-English preview of new or changed records before anything is written to Big Red Cloud.
• Create, update, delete, batch, or email records only after explicit confirmation (and only when those capabilities are enabled for the deployment).
• Ask Big Red Cloud how-to and training questions — Red answers using official support articles, customer documentation, screenshots, and webinar resources. These help tools do not require a connected company.

---

Why open source?

We believe AI infrastructure should be transparent. Customers should be able to inspect the software that connects their accounting data to AI assistants.

Our competitive advantage is not the connector itself; it is our accounting platform, our expert bookkeeping advice, our customer experience, and the value we build on top of it.

By open-sourcing Red, we hope to encourage trust, community contributions, and wider adoption of open standards.

---

Features

• Secure company connection flow (one-time connection page; no credentials in chat)
• Pre-confirm validation of company connection credentials on the connection page (single-company form or multi-company CSV upload)
• Partial connection results — invalid keys are rejected before confirm and reported in failedCompanies
• Hosted HTTP connectionRef / activeConnectionRef so MCP clients can silently reuse a confirmed connection across supported session changes; kept in tool JSON, not shown to end users
• Request routing for transactional work — action tools expect a short-lived routeToken from the router before create/update/delete/batch/email workflows proceed
• Privacy-safe anonymous operational telemetry (platform, environment, tool name, connected-company count) — see docs/TELEMETRY.md
• Company readiness check (brc_company_readiness_check) for connected companies
• Read-only Big Red Cloud lookups
• Customer, supplier, product, sales rep, VAT, and analysis category tools
• Sales quotes, invoices, credit notes, purchases, payments, and cash tools
• Preview-before-posting confirmation flow for create, update, delete, and batch actions (email tools use an explicit send confirmation)
• VAT and transaction safety checks
• Sales invoice safeguards, including multi-line generated-reference validation, Gross Price Entry priceBasis handling, Sales VAT category validation, placeholder product ID blocking, and related preflight checks
• Session audit log of writes made through the MCP session, plus a downloadable support diagnostic for one connected company
• Official Big Red Cloud help answers from Freshdesk articles, customer documentation, screenshots, and webinars — no company connection required
• Local stdio and hosted HTTP transports

---

Security and safety model

Red is designed so that AI-driven access to accounting data stays controlled and auditable.

• No credentials in the repository. Company connection credentials and secrets are never committed. Configuration is supplied at runtime through environment variables.
• No credentials in chat. Company connection credentials must not be pasted into chat. Companies are connected through the secure Red connection page, where credentials are entered directly — not in the chat window.
• Two connection models. On https://red.bigredcloud.com/mcp, a connected company stays available for about the configured session duration and is held in session memory (or an optional shared connection store in hosted deployments). Where supported, that flow can reuse connectionRef / activeConnectionRef across MCP session changes. On https://red.bigredcloud.com/mcp/copilot, companies are linked to the verified Microsoft user who connected them. Those Microsoft-owned connections are separate from anonymous or session connections.
• Pre-confirm validation. Company connection credentials submitted on the connection page are validated against Big Red Cloud before they are stored. Invalid or expired credentials are not saved; they appear in failedCompanies at confirmation time.
• Credential invalidation. Only confirmed authentication failures clear a stored company credential. Endpoint, validation, permission, timeout, and server failures are not treated as an expired API key.
• User-facing presentation. connectionRef, session IDs, and other MCP diagnostics are for tool arguments only. Assistants must not show redconn_… values or internal connection metadata to normal users unless the user explicitly asks for technical details.
• Configurable session duration. How long connections last is controlled by BRC_API_KEY_TTL_MINUTES. User-facing wording (connection page, getting-started text, connection status) is derived from that value — not hardcoded.
• Request routing for writes. Create, update, delete, batch, and email tools require a valid short-lived routeToken issued by the request router for the matching workflow. A route token is not permission to post — preview and confirmation still apply.
• Explicit confirmation for writes. Create, update, delete, and batch actions require an explicit confirmation flag after a preview before posting has been shown. Email tools require an explicit send confirmation after an email preview.
• Preview before posting. The first call to a write tool returns a payload preview rather than performing the action. Nothing is written to Big Red Cloud until you confirm.
• Read and write are separated. Read-only lookups are clearly distinct from actions that change data.
• Audit log. Writes made through the MCP session are recorded in a session audit log; read-only lookups are not treated as completed changes. Activity is scoped to currently connected companies. A downloadable support diagnostic can be generated for one connected company at a time; generating it is read-only and does not write to Big Red Cloud.
• Deployment flags. Update, delete, email, batch, and operator/dev tools can each be disabled per deployment. Disabled skill groups are not registered with the MCP client for that process, so those tools are hidden rather than callable.

Sales invoice safety checks

Sales invoice handling includes:

• Gross Price Entry requires an explicit priceBasis of gross or net so VAT is never guessed.
• Sales VAT rates only. Sales invoices must use a Sales VAT category; purchase VAT rates are blocked, even when the percentage matches.
• Placeholder product IDs (productId 0 and 1) are treated as placeholders and blocked before preview-before-posting and post.
• Multi-line generated-reference invoices (brc_create_sales_invoice_gen_ref) require each productTrans line to include its own acEntries analysis allocation. Line net/VAT/gross reconciliation, analysis allocation totals, header totals, and required product/VAT/analysis fields are validated before posting; failures return structured field-level errors.
• note defaults to the customer name unless a note is explicitly provided, and is never set to a product name.
• deliveryTo is included only when a delivery address is explicitly provided.
• Plain-language results. Technical HTTP status codes are translated into plain-language messages for users.

---

Architecture

Red has two hosted MCP interfaces, each with its own tool registry.

Local stdio (src/index.ts, node build/index.js) uses the same full registry as /mcp. Hosted HTTP is src/remote.ts. /mcp registers that full registry and keeps request routing, routeToken checks, and preview-before-posting confirmation on protected writes. /mcp/copilot registers only its own read-only facade. It does not register accounting create, update or delete tools.

Key shared modules:

• src/server.ts — MCP server factory and stdio singleton
• src/register_all_tools.ts — central tool registration; skips tools whose skill group is disabled, and wraps write tools with routing and preview-before-posting/confirmation handling
• src/config/server_config.ts — deployment skill gating driven by the BRC_ALLOW_* flags
• src/config/mcp_config.ts — MCP server instructions, connection-safety rules, help-answer rules, and connectionRef presentation rules
• src/routing/ — request classification and short-lived routeToken issuance/validation for transactional tools
• src/shared.ts — Big Red Cloud HTTP client, connection handling, audit log, and helpers
• src/read_connection_metadata.ts — connection status metadata echoed on tool responses (including activeConnectionRef for hosted clients)
• src/auth/connection_presentation.ts — user-facing TTL wording and assistant presentation hints
• src/auth/credential_validation.ts — BRC read validation before storing company connection credentials
• src/guards/ — transaction, reference, VAT category, product line, and write-confirmation safety checks
• src/auth/ — secure connection flow, connection store (memory or Cosmos), connection page, and credential persistence
• src/telemetry/ — anonymous client/session identity and platform detection for hosted operational telemetry
• src/brc-edu/ — Freshdesk articles, customer documentation, webinar indexes, screenshots, and unified help search
• src/edu/ — shared help-resource loading, enrichment, workbook parsing, and storage configuration
• src/tools/edu/ — read-only help tools
• src/tools/routing/ — request-routing tool registration

Domain logic lives under src/tools/, with generic create/update/delete/list/batch helpers in src/tools/general/.

Technology

• TypeScript / Node.js (ES modules)
• @modelcontextprotocol/sdk
• Zod for tool input validation
• Express + Streamable HTTP for hosted mode

---

Requirements

• Node.js 24 or newer (engines in package.json; the hosted Linux app uses Node 24).
• npm (bundled with Node.js).

---

Installation

npm install

npm run build

If a .env.example file is provided, copy it to .env and adjust the values:

cp .env.example .env

Never commit your .env file or any real credentials.

---

Running

Hosted HTTP server:

npm run start

Serves the MCP endpoint at htt