Organizely can connect directly to an AI assistant such as Claude (Desktop or Code), Codex, or any other client that supports MCP (Model Context Protocol). Once connected, you can ask the assistant questions about your own live Organizely data: your catalog, stock levels, orders, purchase orders, suppliers, warehouse bins, transfers, stocktakes, tasks, SOPs and more, and get answers based on what is actually in your account right now.
The connection is strictly read-only. An assistant connected this way can read and analyze your data, but it can never create, change or delete anything in Organizely. Each credential is personal to the person who created it.
Before you start
Permissions: to reach Settings > MCP you need either the "Create MCP keys" or the "API keys" permission, or an admin-level role, depending on how your team's roles are set up. To actually create a credential you need the "Create MCP keys" permission. Both toggles live in Team > Roles & Permissions .
What you need on your side: an MCP-capable client (Claude Desktop, Claude Code, Codex CLI, or another MCP client) installed on your computer.
Create a credential
Go to Settings > MCP . Look for the MCP entry in the Settings menu.
Click Create credential (top right). If you have no credentials yet, the table also shows "No MCP credentials yet" with a Create your first credential button that does the same thing.
In the Create MCP credential dialog, fill in:
Name : something that tells you which machine or client it is for, for example "My laptop, Claude". This is only a label for you.
Scopes : tick the areas of your data the assistant is allowed to read. Nothing is ticked by default, so you choose deliberately. Use Select all available or Clear all on the right of the list to move faster. You must select at least one scope.
Expires in (days) : defaults to 90 . You can set anything from 1 to 365 days.
Click Create credential .
The Copy your MCP credential dialog appears with your credential (it starts with orgz_mcp_ ). Click Copy , store it somewhere safe, then click Done .
You only see the credential once. The dialog says "This is the only time you'll see this credential. Copy it now and store it somewhere safe." Organizely stores only a one-way hash and a short prefix (for example orgz_mcp_ab1), so nobody, including support, can look it up or re-send it later. If you close the dialog without copying, create a new credential and revoke the old one.
Scopes cannot be changed after creation. If you picked the wrong areas, create a new credential with the right scopes and revoke the old one.
The scope checkboxes
The Scopes list offers fourteen areas, every one of them read-only:
Catalog (products & variants)
Inventory (stock levels & locations)
Warehouse (bins & physical layout)
Orders (customer orders)
Purchasing (suppliers & purchase orders)
Forecasting (reorder report)
Manufacturing (work orders & BOM)
Automations (rules & alerts)
Organization (business settings)
Team (organization members)
History (audit trail)
SOPs (standard operating procedures)
Tasks (task boards)
Approvals (proposal activity)
Your credential list
Back on Settings > MCP, the Your MCP credentials table shows Name, Prefix, Scopes, Last used, Expires and Status for each credential. Status is Active, Expired or Revoked. Expired and revoked credentials stay in the list for the record; revoked rows appear with the name struck through.
Last used can lag real usage by up to five minutes, so treat it as a recent-activity signal rather than a precise timestamp.
Connect your assistant
Your assistant needs two things: the Organizely MCP address and your credential sent as a bearer token.
Store the credential in an environment variable or your operating system's keychain rather than pasting it straight into a configuration file that gets shared, backed up, or committed to a code repository. Anyone who has the string can read everything the credential's scopes allow.
Other MCP clients work too, as long as they can call an HTTP MCP endpoint and send an Authorization header. If your client runs inside a web browser, contact support before you start: browser-based clients have to be approved by Organizely first, and until then they will be refused.
What your assistant can see
Each scope you tick unlocks a set of read tools in your assistant. In plain terms:
Catalog : search products and variants (titles, descriptions, SKUs, barcodes, tags), open a full product with all its variants (pricing, cost, barcode, weight), and list your vendors and product categories.
Inventory : your store locations, per-location stock for a variant (available, reserved, damaged, committed), stock transfers between locations, manual stock adjustments and their reasons, and stocktakes with counted-versus-expected variance.
Warehouse : where things physically sit: bin placements for a product or a variant, the contents of a single bin, and searching placements by product or SKU.
Orders : search orders by text or by payment/fulfillment status and date range, open a full order, and produce sales summaries (revenue, tax, shipping, quantity, cost and profit by product or variant).
Purchasing : search suppliers and purchase orders, open a full purchase order (line items, receiving, deliveries, tracking, totals, terms), and see which suppliers can supply a given variant or product with cost, pack size, lead time and minimum order quantity.
Forecasting : your organization's default forecasting settings (lead time, restock period, safety stock, buffer, reorder points, seasonality). Individual variants and locations may override those defaults, and per-variant forecasts are not included.
Manufacturing : work orders and work-order templates, machines, preventive-maintenance schedules and jobs, quality-control checks, bills of materials for a variant, where a component is used, untracked parts, and "can I build N of this at this location" material-availability checks.
Automations : your automation rules (name, actions, whether they are active, run counts) and your stock alerts with their firing history. Rule trigger conditions are deliberately not exposed.
Organization : your business profile, saved shipping addresses, and purchase-order delivery notification settings.
Team : who you are signed in as, the members of your organization (name, email, job title), and one member's access status and join date.
History : the change history for a single record and recent changes across the organization. History shows which fields changed, by whom, from where and when, never the before and after values.
SOPs : search and browse your SOPs, read a full SOP body, and list SOP folders. Attached files are listed by name, type and size only; the assistant cannot download them.
Tasks : task boards, their columns, the tasks in them, and each task's checklists.
Approvals : activity from Organizely's in-app AI assistant: proposals with their status, risk, summary and the human decision, plus multi-step plan progress.
A couple of details worth knowing:
Asking for "recent activity" that mixes AI decisions with audit changes needs both the Approvals and the History scopes.
Everything is scoped to your organization. No tool accepts another organization's identifier, so a credential can only ever reach your own account.
Who can do what
Seeing the page.Settings > MCP is visible to anyone holding the "Create MCP keys" or "API keys" permission, or an admin-level role, depending on how your team's roles are set up. If you cannot see it, ask an admin to adjust your role in Team > Roles & Permissions .
Creating credentials. This requires the "Create MCP keys" toggle specifically. If you can see the page but cannot create anything, that toggle is the one to ask for.
Everyone manages their own. Credentials are personal: you create them for yourself, and you can always list and revoke your own, even if your other permissions change later.
Organization-wide oversight. People with the "API keys" permission, or an admin-level role, see every MCP credential in the organization and can revoke any of them.
A credential never exceeds its owner. It answers only with data its owner can already see in the app. If the owner's in-app permissions shrink (for example their Orders permission is removed), the credential's answers shrink with it on the very next request, with no revoke needed.
The read-only guarantee
The Organizely MCP server cannot change anything in your account. This is not a policy, it is how it is built:
No create, update or delete tool exists on the connection at all.
The server refuses write attempts as they happen, and an automated safety check runs before every release to confirm that nothing reachable over the MCP connection can write.
Every tool is advertised to your assistant as read-only and non-destructive, so well-behaved clients will not ask you to approve a "write" step that does not exist.
The only thing an MCP request ever records is the credential's own "Last used" timestamp.
An assistant connected this way can read, analyze, summarize and recommend. To actually change something, you still use Organizely itself (or the in-app AI assistant's approval flow, where you review each change before it is applied).
Practical limits and troubleshooting
Keep parallel requests low. Send no more than 3 calls at a time on one credential, and no more than 6 at a time across your whole organization. As a courtesy ceiling, keep a single credential under roughly 60 calls per minute. If your assistant fires too many at once you will see a rate-limit response with a Retry-After value: have the client wait that long and retry, and tell it to run fewer requests in parallel.
"The result exceeds the response budget." This is not an outage. The answer was simply too big to return in one piece. Ask for a smaller number of results, fewer ids at a time, or a tighter filter, and page through the data.
Order summaries have a window. Sales and profit summaries look at the last 90 days when you do not give dates, and analyze at most the 8,000 most recent matching orders. On a busy store, ask for narrower date ranges (a month at a time, for example) and combine the results.
A whole area is missing from your assistant. Missing scopes look like missing tools, not like an error: your assistant will simply say Organizely has no such capability. Check the Scopes column for that credential. Since scopes cannot be edited, create a new credential with the right ones and revoke the old.
It worked yesterday and now that area is quiet. A credential also narrows when its owner's in-app permissions change. The credential still shows as Active, but the areas the owner lost are no longer answered. Check the owner's role in Team > Roles & Permissions.
Work-order questions return nothing. Work-order search, listing, details and templates depend on Manufacturing being switched on. If those four are missing while the rest of the manufacturing and bill-of-materials answers work normally, contact support.
Newly granted access does not show up. Your assistant reads the tool list when it connects. Restart or reconnect the client after creating a new credential or switching credentials.
You lost the credential. There is no way to recover it. Create a new one and revoke the old one.
Revoking. Click Revoke on the row and confirm in the Revoke MCP credential dialog. It stops working on the very next request and cannot be undone. The row stays in the table, struck through, for the record.
Expired credentials. A credential stops working the moment it passes its expiry date and is shown with an Expired badge. Create a replacement and update your client configuration.
Connection is refused entirely. Authentication failures always come back as a single generic "Unauthorized" for security reasons, so check the obvious things in order: the endpoint is exactly https://organizely.io/api/mcp, the header is Authorization: Bearer followed by the credential, the credential starts with orgz_mcp_, and it is neither revoked nor expired. Note that keys created on the Settings > API Keys page for the Business Intelligence API are a different kind of key and will not work here (and vice versa).
Need help?
If something is not working or you are not sure which scopes to pick, email us at support@organizely.io.