Connect your AI assistant (Claude, ChatGPT or Gemini) to MarginOS

You can connect Claude, ChatGPT or Gemini to MarginOS and ask it about your business in plain English: “How did yesterday go?”, “What is my CAC this month?”, “What should I fix first?” Your assistant answers from the same figures your Command Center shows. It does not do its own sums on your raw orders. And when you want to check a profit figure, ask it to show you the math.

Setting it up takes about two minutes. You add MarginOS in your AI app, then approve it on a MarginOS screen. The connection is read-only. The assistant can look at your numbers, but it cannot change anything in MarginOS. An admin can disconnect it at any time.

Before you start

• You need to be an admin of the business in MarginOS. Only an admin can approve a connection. If you are a team member without admin rights, ask an admin to connect it. See Invite a teammate for how roles work.
• You need one of these AI apps:
  • Claude on the web (claude.ai), the Claude desktop app or Claude Code. On Claude’s Free plan you can add one custom connector.
  • ChatGPT on the web, on a Plus, Pro, Business, Enterprise or Education plan, with developer mode turned on. In a Business or Enterprise workspace, your ChatGPT admin may need to allow developer mode first.
  • Gemini on the web (gemini.google.com), signed in with a personal Google account. For now, Google offers custom apps only in English, to people aged 18 or over in the US, with Keep Activity turned on. Work and school accounts cannot add them yet.
• Have the MarginOS server address ready. This is the one address your AI app needs:

  https://app.marginos.com/api/v1/mcp

How to connect Claude

1. In Claude, go to Customize > Connectors. Click +, then Add custom connector.
2. Paste the server address above. Leave Advanced settings empty: MarginOS does not need a client ID or secret. Click Add.
3. Click Connect next to the new MarginOS connector. A MarginOS page opens. Sign in to MarginOS if it asks you to.
4. The page reads Connect Claude to MarginOS. Under Business, choose the business Claude should read. If you are an admin of only one business, it is already selected.
5. Click Approve. You go straight back to Claude, and the connector now shows as connected. (Click Deny instead if you change your mind. Nothing is connected.)
6. In a chat, click + at the bottom left, open Connectors and make sure MarginOS is switched on. Then ask your question.

On a Claude Team or Enterprise plan, an owner of your Claude organisation adds the connector once, under Organization settings > Connectors. After that, each person clicks Connect on it under Customize > Connectors and goes through the approval page themselves. Each person still has to be an admin of the business in MarginOS.

In Claude Code, run this command, then type /mcp inside Claude Code and follow the sign-in steps in your browser:

claude mcp add --transport http marginos https://app.marginos.com/api/v1/mcp

The approval page is the same one. It will say Connect Claude Code (marginos) to MarginOS, with the name you chose in the brackets.

How to connect ChatGPT

1. In ChatGPT on the web, open Settings > Security and login and turn on Developer mode.
2. Go to Plugins and click + to create a new app.
3. Give it a name, such as MarginOS, and paste the server address above. If ChatGPT asks how to sign in, choose OAuth. MarginOS does not need a client ID or secret.
4. Create the app. A MarginOS approval page opens. Sign in to MarginOS if it asks you to, choose the business under Business, and click Approve. You go straight back to ChatGPT.
5. In a chat, click +, choose Developer mode and switch on MarginOS. Then ask your question.

How to connect Gemini

1. Open gemini.google.com on a computer. You can only add MarginOS in the Gemini web app. Once it is added, it works in the Gemini mobile app too.
2. Click Settings at the bottom, then Connected Apps.
3. Under Custom apps, click Add a custom app.
4. Paste the server address above. Leave Advanced features as it is: MarginOS does not need any credentials. Click Next.
5. A MarginOS approval page opens. Sign in to MarginOS if it asks you to, choose the business under Business, and click Approve. You go straight back to Gemini.
6. In a chat, type @ and choose MarginOS, so Gemini uses it for that question.

To stop Gemini using MarginOS for a while, switch it off under Settings > Connected Apps. To remove it from Gemini for good, open More details on it there and click Remove app.

Where to see your connection

Open Settings in the MarginOS sidebar. This takes you to Account Setup. Go to the Developer APIs tab and scroll to Connected AI apps. Only admins see this card.

Each row is one connection:

Column	What it tells you
App	The app’s name, for example Claude.
Connected by	The email address of the admin who approved it.
Connected	The date it was approved.
Last used	The last date the app used the connection. Never means it has been approved but not used yet.
Status	Connected means it works. No longer active means it has stopped working: the person who connected it is no longer an admin of this business, or the business is suspended.

If the card says No AI apps connected, nobody has approved a connection for this business yet.

You can also ask your assistant directly: “Which MarginOS business are you connected to?” It can check which business it reads, which app connected it and when.

How to disconnect

1. Go to Account Setup > Developer APIs > Connected AI apps.
2. Click Disconnect on the row.
3. Confirm with Yes, disconnect.

The app stops working straight away and the row disappears from the list. To use it again, someone has to connect it again from the AI app. Any admin of the business can disconnect any connection, not just the one they approved.

What your assistant can look up

Your assistant gets thirteen read-only lookups. Each one returns the same figures you would see on the matching MarginOS screen, so the answer matches what is in front of you.

Lookup	What it returns
Company pulse	Yesterday’s contribution profit and revenue, the 7-day averages, month-to-date contribution profit against your monthly plan goal, and the Performance Snapshot for the window you ask about.
Unit economics	Gross margin, profit per order, CAC, LTGP:CAC, CAC recovery and payback. Some of these follow the window you ask about. Others, such as 90-day LTGP and payback, always use their own fixed period, and the assistant is told which is which.
Active alerts	Your open alerts, in the same three groups and the same order as your Margin Briefing: Today’s Top Moves, Risk Radar and Data Health. Each alert says what happened, what it means and what to do, with a link to the MarginOS page where you fix it. Five per group by default; you can ask for up to 25.
Data trust	How far the numbers can be trusted right now: product-cost coverage and warehouse data health for the last 30 days on your DTC business line, stock with no known cost, and your Data Health alerts. See Data Trust levels.
Business lines	Revenue, gross profit, gross profit per order and orders over the last 90 days for your DTC business, and revenue and orders for your other business lines (wholesale, marketplace, retail, other). The other lines carry no profit figure, because their extra fees are not modelled yet.
Inventory health	Cash conversion days, slow and dead stock, weeks of cover, revenue at risk of a stockout, stock with no known cost, and stock value counted on more than one listing, as your Cash & Inventory Health tiles show them. When some stock has no known cost, the slow and dead figures cover only the products that do have one, and the assistant is told the real figure is likely higher.
Logistics costs	Your logistics cost over the last 30 days: the total, its share of revenue, cost per order, the split by cost type and your largest carrier services. The answer says whether the total was measured from carrier and warehouse invoices or estimated from your store settings, and each cost type says whether it is already inside gross profit.
Portfolio cells	The Profit & Inventory grid from the Growth page: one row per product family and acquisition channel, DTC only, with 30-day revenue, gross profit, orders, gross profit per order, LTGP:CAC, 90-day return rate, stock, weeks of cover, cash tied up and variance against plan. The assistant can filter by channel, family or status and sort the cells by a figure it picks.
Customer profit	Your customers ranked by lifetime gross profit, as in Customer Profit: value tier, lifecycle stage, acquisition channel, churn risk, LTGP:CAC, return rate and cost coverage, with the tier and stage counts for the same selection. DTC by default, up to 25 customers at a time, each under a reference code rather than a name (see below).
Channel economics	One row per acquisition channel, DTC only, as the Growth page’s channel table shows it: orders, net revenue, new customers, contribution margin before and after ad spend, channel CAC, 90-day LTGP per customer, LTGP:CAC, return rate, MER, ad spend, the channel’s role and how confident its attribution is, plus your MER target band. Over 1 or 7 days the LTGP figures are left empty by design.
SKU economics	The Catalog Profit table: one row per product SKU, DTC only, with 30-day revenue, gross profit, gross profit per unit and per order, gross margin, return rate, units sold, stock and weeks of cover, its profit class, how far its cost can be trusted, and flags such as missing cost or negative margin. Active products only unless the assistant asks for all of them; up to 50 SKUs at a time.
Proof Ledger	Shows how one product’s 30-day contribution margin on its product page is built, line by line, and checks that the lines add up to the figure on screen. See Proof Ledger: show me the math below.
Connection info	Which business the connection reads, which app connected it, and when.

Company pulse, unit economics and channel economics let you pick the last 1, 7, 30, 60 or 90 days. If you do not say, the assistant uses 30 days. The other lookups each use a fixed period of their own.

Where MarginOS has no number, the assistant gets no number. A figure that cannot be backed by your data comes back empty, never as a guess. That is the same rule the rest of MarginOS follows.

Two exceptions are spelled out to the assistant so it does not misread them. In SKU economics, weeks of cover reads 0 both when there is no stock and when your stock is not counted, so the assistant is told it cannot tell the two apart. And Customer profit counts a product with no known cost as costing nothing, so the assistant is told to check a customer’s cost coverage before trusting their tier.

Proof Ledger: show me the math

Profit numbers your CFO or accountant can challenge, trace and tie out. Ask your AI assistant to “show me the math” for a product, and get the full working behind its profit:

• The formula and a step-by-step waterfall of its last 30 days, line by line.
• Where every input came from, how much to trust it, and how fresh the data is.
• How shared order costs were split, with any estimates and anything the figure leaves out spelled out.
• The source records behind it, and a check that every line adds up to the number on screen.

It works on one product at a time, for products with sales in the last 30 days. Give the SKU exactly as the Catalog page shows it. The figures are in your reporting currency.

Why we built it: I hate black-box tools and dashboards that hide the math. I’m making MarginOS as transparent as possible, so you always know you can trust it.

What your assistant cannot see

• Your customers’ identities. No lookup returns a customer’s name, email address, phone number or postal address. Customer profit does list individual customers, but each one appears under a reference code, and never with exact order dates. As a safety net, MarginOS also checks every answer before it leaves. If one ever contains customer contact details or a customer ID, MarginOS holds the whole answer back, and the assistant is told: “This answer was withheld because it contained customer-identifying data.”
• Alerts about customer privacy requests. These are left out of the alert list. The assistant is told how many were left out, but not what they say.
• Other businesses. A connection reads one business only: the one chosen on the approval page.
• Anything it could change. There are no write actions. The assistant cannot change settings, costs, alerts or connections.

What MarginOS keeps

The approval page says it plainly, with your app’s name in it, for example: MarginOS keeps a record of what Claude looks up, and the question you asked, for 90 days.

• For each lookup, MarginOS records which lookup it was, what was asked for (such as the time window), whether it worked and how long it took.
• When the assistant passes it along, MarginOS also records the question you asked. Email addresses, phone numbers and long codes (such as keys) in that question are replaced with placeholders before it is stored. MarginOS never receives the rest of your conversation or the assistant’s reply.
• Records are deleted automatically after 90 days.
• If a shopper asks your store to erase their data, any stored question that names that shopper in full is erased too.
• Disconnecting stops new records. It does not delete the existing ones; they are still removed when they reach 90 days.

Example

An admin connects Claude on a Monday and asks, “How did last week go, and is there anything I should fix?”

Claude looks up the company pulse for the last 7 days and the active alerts. It replies that contribution profit for the week was $8,400, slightly ahead of the pace needed for the monthly goal. It then names the top alert in Today’s Top Moves, say a best-seller whose cost has gone missing, with the link to fix it.

Back in MarginOS, the Connected AI apps card shows one row: Claude, connected by the admin, last used today, status Connected.

Common questions

Which AI assistants can connect to MarginOS?

Claude (on the web, in the desktop app and in Claude Code), ChatGPT on the web with developer mode turned on, and Gemini. You add Gemini in its web app, and it then works in the Gemini mobile app too.

I cannot find where to add MarginOS in ChatGPT or Gemini.

ChatGPT shows developer mode only on the web, on a Plus, Pro, Business, Enterprise or Education plan, and a workspace admin can switch it off. Gemini shows custom apps only in its web app, for a personal Google account, in English, to people aged 18 or over in the US, with Keep Activity turned on.

Can my AI assistant change anything in MarginOS?

No. The connection is read-only. Your assistant can look up figures and alerts, but there are no lookups that change settings, costs, alerts or connections.

The approval page says “Only an admin of a MarginOS business can connect an AI app”.

You are signed in to MarginOS without admin rights on any active business. Ask an admin of the business to connect it, or to make you an admin first.

The approval page says the request has expired.

The approval link is only valid for a short time. Go back to your AI app and connect again to get a fresh one.

Why does the same app appear twice in Connected AI apps?

Every approval creates a new connection. That happens when you connect again, or when your AI app asks you to sign in again after about a month of not using it. The older row can stay behind. It is safe to disconnect the row whose Last used date is older.

A connection says “No longer active”. What do I do?

The person who approved it is no longer an admin of this business, or the business is suspended, so it has stopped working. Click Disconnect to tidy it away. If you still want the assistant connected, an admin connects it again from the AI app.

How do I switch my assistant to a different business?

A connection reads one business. Remove MarginOS from your AI app, add it again, and choose the other business on the approval page. Then disconnect the old row under Connected AI apps in the first business.

Does MarginOS keep my conversations?

No. MarginOS only sees the lookups your assistant makes, plus your question when the assistant passes it along. It keeps a record of those for 90 days, with contact details masked. It never receives the rest of the conversation or the assistant’s reply.

Related

• Read the Command Center: the figures your assistant reads from.
• Read your Margin Briefing: the alerts your assistant lists, and what each group means.
• Data Trust levels: how far each number can be trusted.
• Why MarginOS shows “N/A” instead of a made-up number: why some answers come back empty.
• Invite a teammate: who is an admin, and so who can connect.