Oply Digital Twin — connector guide

The Oply Digital Twin (ODT) is demand forecasting and supply intelligence for retail and distribution networks: which site × product pairs are at risk, what to buy and transfer, why the plan decided what it decided. This connector puts it inside the AI assistant your team already uses. The assistant calls the Digital Twin's tools with your workspace's data; nothing is typed into a separate system.

1. Add the connector

Claude (web, Desktop, Cowork). Settings → Connectors → Add custom connector → paste the server URL → Add. Claude opens the Oply sign-in page the first time a tool needs your workspace.

Claude Code.

claude mcp add --transport http oply https://mcp.oplytec.com/odt

The first protected call opens the browser for sign-in; the token is kept by Claude Code.

Messages API (a program, not a person). The connector takes an API key as its bearer:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.oplytec.com/odt",
      "name": "oply",
      "authorization_token": "oply_sk_…"
    }
  ]
}

An administrator mints the key in the Oply console (Settings → API access) or by asking the assistant to create_api_key. See §6.

Other hosts (Cursor, ChatGPT, any MCP client). Add a remote MCP server with the URL above. The authorization server supports client metadata documents (CIMD) and dynamic client registration (RFC 7591), PKCE only, so a standard client needs no manual setup.

2. Sign in and consent

Sign-in uses your Oply workspace account (the same username and password as the console). The consent page names the application asking for access and the permissions it requests:

Permission What it allows
demand:read forecasts, alerts, sales history, prices and promotions
supply:read products, sites, suppliers, network, inventory, risks, plans, orders, explanations
plan:write approve suggestions, review and override forecasts, approve promotions, file data anomalies
data:write rules, datasets, uploads, data sources, pipeline runs
admin engine parameters, the run schedule, usage, API keys

Two things cap what a token may hold, whatever the host asks for:

A workspace that does not exist yet can be created from the consent page as a 14-day trial when self-signup is enabled for the server: the trial workspace is provisioned from a template and the sign-in completes in the same step. The first conversation to have then is the onboard_dataset prompt (§4).

Tokens last one hour and are refreshed silently for up to 30 days. A change of plan or role takes effect at the next refresh; disconnecting the connector in the host ends it.

3. What the assistant can do

Every answer carries the date it was computed for (as_of), the measure of every quantity (units: cases, kilograms…), whether the snapshot is stale, and how many rows were cut when a list was capped. An empty answer is an empty answer, never an error; an unavailable Digital Twin says unavailable, never no data.

Discovery. whoami, get_capabilities (versions, permissions, freshness of each engine), get_manual_section (the ODT manual by section: the six stages, the risk classes, the glossary, the explainability playbooks), search_entities (the exact code of a store, DC, product, supplier or transport).

Physics and network. get_product, get_site, get_supplier, get_transport, get_network_topology (sourcing lanes with priority and lead time), get_calendars (replenishment, purchasing, open-to-buy), get_purchasing_rules.

Demand. get_demand_forecast (daily, up to 91 days, with the error over closed days), list_forecast_alerts (the month's review queue by revenue at stake), get_sales_history, get_pricing_and_promotions.

Supply. get_inventory_position, get_inventory_projection (closing stock and spoilage per day, the 21-day twin), list_risks (one row per site × product with its class, exposure and action), get_risk_diagnosis, get_replenishment_needs (raw need, rounded need, the solver's decision, what was vetoed or cut).

Orders and plans. list_purchase_suggestions, list_transfer_suggestions, list_purchase_orders, list_transfer_orders, explain_decision (objective terms and binding constraints behind one decision), get_engine_parameters.

Writes (the assistant asks before each). approve_purchase_suggestions, approve_transfer_suggestions, review_forecast_alerts, override_forecast, approve_promotions, report_data_anomaly, update_engine_parameters; the rules (save_sourcing_rules, save_demand_rules, save_purchasing_rules, save_calendars, delete_rules, get_rule_coverage); the data (§4); the runs (run_pipeline, get_run_status, list_runs, get_pipeline_schedule, set_pipeline_schedule); the account (get_usage, create_api_key, list_api_keys, revoke_api_key).

Tools take business codes (site_code, product_code), never internal identifiers, and never your tenant: the workspace comes from the sign-in.

Prompts the host may offer as shortcuts: morning_briefing, explain_stockout, why_was_this_vetoed, review_purchase_plan, review_promotions, onboard_dataset. Resources: oply://manual and oply://manual/{section}, oply://glossary.

4. Bring your data

The assistant can take a workspace from empty to a first plan. The onboard_dataset prompt walks it through one dataset at a time:

  1. list_datasets — the datasets the Digital Twin expects, their columns and keys.
  2. preview_dataset_mapping — a sample of your file read in code: proposed header mapping, missing required columns, mixed date formats, decimal comma vs dot, leading zeros, codes it does not know.
  3. save_dataset_mapping — the agreed header → column mapping.
  4. The rows themselves:
    • master data (sites, products, suppliers, transports, measures, packagings, customers, groups): import_master_data, up to 5,000 rows per call, upsert by key, errors reported per row;
    • sales history and anything large: create_upload_url hands back a one-hour upload URL for the whole file (the file never passes through the conversation), or upload_dataset_rows sends up to 1,000 rows inline;
    • anything recurring: register_data_source names where the nightly ingestion pulls the dataset from (S3, GCS, HTTPS, SFTP). A credential is a name in the platform's secret manager, never a value in the conversation.
  5. get_ingestion_status — where a load stands.

Then the rules (save_sourcing_rules, save_demand_rules, save_purchasing_rules, save_calendars, get_rule_coverage), the schedule (set_pipeline_schedule, one run a day at most) and a first run_pipeline.

5. Plans, quotas and limits

Trial Starter Pro
Permissions all the role allows reads all the role allows
Tool calls a month (default) 2,000 20,000 unlimited
API keys yes no yes

6. API keys (programs)

An administrator mints a key for a program: the company's own agent, a script, the Messages API connector. The key (oply_sk_…) is shown once, holds read permissions unless a write is named, never admin, and never more than the administrator who minted it may hold today. It is sent as the bearer of every request:

Authorization: Bearer oply_sk_…

A key acts on the data surface only; it cannot manage accounts or mint other keys. Revoking it (revoke_api_key, or the console) takes effect within a minute.

7. Support