Guide for AI and developers
Everything a person can do in ProfitNod, an AI or a script can do too. One set of tools, three ways in: MCP, REST, and the app.
1. Create a connection
In your store admin open ProfitNod, go to Connect AI, choose what the connection may do, and copy the link. The link contains the key; treat it like a password.
2. Connect an AI (MCP)
The link is a Streamable HTTP MCP endpoint. Paste it wherever your AI asks for a custom connector or MCP server URL.
https://profitnod.com/mcp/<your-key>Clients that prefer a header can use the plain endpoint with the key as a Bearer token:
POST https://profitnod.com/mcp
Authorization: Bearer <your-key>Claude Code:
claude mcp add --transport http profitnod https://profitnod.com/mcp --header "Authorization: Bearer <your-key>"3. Or call the REST API
Every tool is also one POST. The body is the tool's input as JSON; the answer has result (structured) and text (short, ready to read).
curl -s https://profitnod.com/api/v1/tools/get_profit_summary \
-H "Authorization: Bearer <your-key>" \
-H "Content-Type: application/json" \
-d '{"period":"7d"}'OpenAPI description · GET /api/v1/tools lists the tools with their input schemas · llms.txt for agents.
Tools
| Tool | What it does | Kind |
|---|---|---|
get_profit_summary | The store's real profit for a period: net revenue, product cost, shipping, payment fees, ad spend, what is left before ads, profit after ads, ROAS next to break-even ROAS, cost per order next to break-even cost per order, the one next step, and what data is missing. Numbers are computed by code from store orders and the merchant's costs; when a product cost is missing the result is a low/high range. Use this first for any question about profit, ROAS or whether ads make money. | Reads |
explain_break_even | Shows step by step how the store's break-even ROAS and break-even cost per order are worked out from its own numbers, and what each cost contributes. Use it when the merchant asks 'what ROAS do I need?' or doubts a number. | Reads |
get_daily_profit | Day-by-day table for a period: orders, net revenue, ad spend, left before ads, profit after ads, ROAS and break-even ROAS. Use it to find which day went wrong or to chart a trend. | Reads |
get_product_profit | Per product variant for a period: units, sales, unit cost, margin (sales minus product cost, before shipping, fees and ads) and share of sales. Flags variants whose cost is missing. Sort by sales, margin, margin_low (worst first) or units. | Reads |
get_campaign_decisions | For every ad campaign with recorded spend: spend, purchases, revenue (the ad platform's claim scaled down so all campaigns together never exceed store revenue), ROAS against break-even, profit, and a decision: raise, hold, cut, too_early, no_data or fix_costs, each with its reason. Decisions are rule-based and conservative. The merchant's ads are never changed by this tool. | Reads |
list_missing_costs | Product variants that have no cost yet, biggest sellers first. Each missing cost turns profit into a range, so filling these makes the numbers exact. | Reads |
list_ad_spend | The ad spend entries recorded for a period, by day, channel and campaign, with purchases and purchase value where given. | Reads |
get_cost_settings | The merchant's cost settings: shipping cost per order, payment fee rate, other per-order costs, and whether the fee rate was confirmed. | Reads |
get_setup_status | What is set up and what is still missing for exact profit: store sync, shipping cost, product costs, ad spend, AI connection. | Reads |
list_approvals | Store changes an AI has proposed and their status: pending (waiting for the merchant's tap in the app), done, rejected or failed. | Reads |
get_activity_log | The audit trail: every change made through the app or by a connected AI, newest first, with who did it and when. | Reads |
record_ad_spend | Save ad spend per day, channel and (optionally) campaign. Include purchases and purchase_value as the ad platform reports them to get per-campaign decisions. Saving the same day, channel and campaign again replaces the earlier entry. Amounts are in the store's currency unless `currency` is given, in which case they are converted at that day's reference rate. | Writes |
record_ad_spend_total | Quick way to add ad spend when daily numbers aren't at hand: give one total for a period and it is spread evenly over the days. It replaces earlier whole-channel entries for that channel on those days. For exact daily results and per-campaign decisions use record_ad_spend instead. | Writes |
delete_ad_spend | Remove one recorded ad spend entry by day, channel and campaign (leave campaign out for the whole-channel entry). | Writes |
set_product_costs | Set what a product variant costs you per unit, by variant_id or by SKU. These costs are kept in this app and used for profit; the store's own 'cost per item' field is not changed (use propose_store_cost_update for that). Pass cost null to remove a cost you set earlier. | Writes |
update_cost_settings | Change the cost settings used for profit: shipping cost per order, payment fee percent and fixed part, other per-order costs, and a rough product cost share for products without a cost. Only the fields you pass change. | Writes |
ask_support | Ask the app's support a question, report a problem or suggest an improvement on the merchant's behalf. Returns the support answer. The message is kept so the team can read it and improve the app. | Writes |
propose_price_change | Propose a new price for one product variant. Nothing changes in the store until the merchant approves it on the Approvals page of the app. Returns the approval id; check it later with list_approvals. | Proposes |
propose_store_cost_update | Propose writing a product variant's unit cost into the store's own 'cost per item' field, so the store's reports match. Nothing changes until the merchant approves it on the Approvals page of the app. | Proposes |
Ready-made prompts
- Daily profit check. Yesterday's profit, ROAS against break-even, and the one thing to do today.
- Weekly profit review. A one-page review of the last 7 days: profit, the worst day, the weakest products, campaign decisions.
- Log ad spend. Record yesterday's ad spend per campaign so profit after ads is exact.
- Fill missing product costs. Find products without a cost and fill them in, biggest sellers first.
- Find and fix thin margins. Find products that sell at a thin margin and propose price changes for approval.
Rules an agent should know
- Amounts are in the store's currency, in major units (12.50, not 1250).
- A value with
lowandhighmeans a product cost is missing. Say it as a range and name the missing cost. 7dand30dend yesterday in the store's timezone, so numbers don't move during the day.- Tools starting with
propose_do nothing until the merchant approves them in the app. - Limit: 120 calls a minute per connection. Over that the API answers 429.
- Errors are JSON:
{"error": "code", "message": "what to do"}.