# X-MP Agent Integration Guide > Canonical agent-facing entrypoint for `https://x-mp.ru`. > Human presentation: . Short discovery file: > . Complete human project map: . Complete machine catalog: . The compatibility scalar links near the top of the catalog are shortcuts, not the complete inventory; agents must inspect the `services`, `connectors`, `mcp_servers`, `runtime_components`, `data_products` and `route_index` sections. Target placement: all server services run in isolated account cells inside the central `main-node` deployment. `wb-node-01..04` are Codex/MCP clients only and must not receive new databases, queues, schedulers, marketplace credentials or server applications. Existing client-node services are frozen legacy instances until an account-by-account canary, read-back and rollback-controlled migration is complete. ## 1. System purpose X-MP is an agentic operating system for marketplace businesses. Its target is not maximum revenue or marketplace rank in isolation. The business objective is sustainable net profit and owner-available cash flow, subject to capital, risk, inventory, legal, marketplace and owner-defined constraints. The canonical management loop is: ```text owner goal and limits -> verified business state -> opportunity or risk -> alternatives and expected money impact -> approval or pre-authorized limit -> idempotent action -> measured outcome -> reviewed memory or regulation update ``` Do not present roadmap capabilities as active production functions. Current public production services are listed below. ## 2. The problem X-MP solves Marketplace operators do not need another isolated dashboard or a generic chat assistant. Their real problem is that sales, advertising, prices, competitors, inventory, warehouses, content, reviews and finance change continuously, while the facts remain split across cabinets and spreadsheets. Important signals are noticed late, recommendations are disconnected from money, actions are hard to control, and teams rarely measure whether a decision actually worked. X-MP solves one central job: > Continuously turn fragmented marketplace facts into a money-aware priority, > a safe next action and a measured result, while the owner chooses how much > control to delegate. This makes X-MP more than analytics. It is a progressive operating layer around the marketplace cabinet: it can begin as an always-on adviser, grow into a decision co-pilot and eventually manage explicitly allowed operations within owner-defined limits. ## 3. Who the system is for Primary users: - marketplace owners who cannot personally monitor every SKU and cabinet signal; - operating managers responsible for sales, advertising, prices, supplies and inventory performance; - multi-brand teams and agencies that need one repeatable management method; - analysts who need evidence, provenance and outcome measurement rather than unexplained recommendations; - agent runtimes that need a documented business objective, service map, safety boundary and expected output contract. The strongest fit is a business where missed signals, ineffective advertising, stockouts, excess inventory, wrong prices or slow manual analysis already cost more than continuous management would. ## 4. Goal hierarchy Agents must optimize in this order unless an owner policy states a stricter constraint: 1. Protect the business from material, legal, marketplace and liquidity risk. 2. Grow sustainable net profit, not revenue in isolation. 3. Preserve and improve owner-available cash flow. 4. Use inventory and working capital efficiently. 5. Grow profitable demand, conversion and revenue. 6. Reduce avoidable advertising, logistics and operating losses. 7. Reduce the owner's manual monitoring and decision workload. A local metric such as CTR, rank, orders or revenue is a signal, not the final objective. An agent must explain how a proposed change can affect profit, cash, capital, risk or owner time. ## 5. Three autonomy levels Autonomy is selected per business domain and, when necessary, per operation. A seller may use Advisor for prices, Co-pilot for advertising and Autopilot for a bounded inventory check. Never infer a higher level from access to a credential. ### Level 0 — Advisor Purpose: see and understand everything without changing the cabinet. - continuously observes first-party products, sales, advertising, prices, positions, content, reviews, warehouses, stocks and supplies; - compares competitors, market prices, assortment and visibility; - detects changes, opportunities, anomalies and risks; - explains likely causes, money impact, evidence gaps and next checks; - produces reports and alerts; - performs no marketplace write operation. ### Level 1 — Co-pilot Purpose: turn analysis into a concrete owner-controlled decision. - includes every Advisor capability; - compares act, wait and do-nothing alternatives; - estimates expected effect, downside, capital need, reversibility and confidence; - prepares an explicit action plan, limits, measurement window and rollback; - asks the owner to choose or confirm the decision; - does not independently change a material cabinet state. Any separately installed executor may run only the exact approved plan and authority envelope. ### Level 2 — Autopilot Purpose: manage allowed cabinet operations continuously within explicit rules. - includes every Advisor and Co-pilot capability; - executes only allowlisted operation types with owner-defined limits; - records before-state, authority, idempotency key, action and after-state; - measures the outcome and adapts only from reviewed evidence; - pauses and escalates on stale data, low confidence, a new situation, breached limit, conflict, high downside or irreversible action; - never treats broad API access as unlimited business authority. The effective autonomy is always the lowest of owner policy, current service capability, data quality, operation risk and technical readiness. Public X-MP production currently provides the read-only connector and Memory foundation; write-capable controllers are enabled only as separately verified capabilities. ## 6. What the agent team continuously does The operating cycle is persistent rather than a one-time prompt: ```text observe own products and market -> compare competitors, prices and availability -> analyze sales, profit, ads, conversion, stocks and warehouses -> detect a signal, opportunity or threat -> explain causes and rank by money impact -> advise, propose or execute according to autonomy level -> measure the result -> preserve reviewed evidence and learning -> continue observing ``` Expected observation domains include: - own products, assortment, cards, content, ratings and reviews; - competitors, their assortment, prices, visibility and meaningful changes; - prices, discounts, margin and price-position context; - sales, orders, returns, revenue, profit and conversion funnel; - advertising spend, efficiency and campaign behavior; - warehouses, available stock, stockout risk, excess inventory, turnover and supply requirements; - data freshness, collection failures and contradictory facts. X-MP is valuable because it combines continuous observation, progressive autonomy, evidence-first decisions and measured memory in one management loop. An ordinary report stops at “what happened”; X-MP is designed to continue through “why it matters”, “what should happen next” and “did it work”. ## 7. Connect Codex, Claude Code or another harness X-MP is model- and harness-neutral. An owner can connect Codex, Claude Code or another runtime capable of reading Markdown and calling HTTPS REST, OpenAPI or MCP tools. The harness supplies reasoning and execution sessions; X-MP supplies the stable business context and operating boundary. The connected agent can receive these layers without being given database or raw infrastructure credentials: 1. cabinet data and verified marketplace facts; 2. Memory task cards, decisions, evidence and measured outcomes; 3. Wildberries and other registered connectors; 4. analytics, competitor context and business signals; 5. tools and services enabled for this account; 6. autonomy, approval and risk policy selected by the owner. The account cabinet currently keeps the human UI deliberately narrow: cabinet settings and access keys only. Additional service/task foundations remain behind the UI for later controlled work. A credential saved for one connector remains server-side, encrypted and isolated; it is not copied into agent context. Each agent harness receives its own revocable X-MP key. - a standard `xmp_live_` key reads only the base cabinet context; - a special `xmp_special_` key uses a server-defined profile for one account; - cabinet data collection uses one WB token marked read-only; - prices, promotion, content, and feedbacks/questions use separate WB credential slots; - a credential slot never implies unconditional marketplace write authority. Recommended bootstrap: ```text register at /cabinet/ -> choose autonomy per domain -> enable only required modules -> connect Memory, data and connector services -> issue one scoped key per agent runtime -> agent fetches /cabinet/api/agent/context -> agent resumes or creates a task -> work through the selected autonomy contract ``` Agent context endpoint: ```http GET /cabinet/api/agent/context Authorization: Bearer xmp_live_ | xmp_special_ ``` The response contains the cabinet policy and service registry, but never returns saved third-party credentials. Task endpoints use the same scoped key: - `GET /cabinet/api/agent/tasks` requires `tasks.read`; - `POST /cabinet/api/agent/tasks` requires `tasks.write` and creates a durable token-bound Memory task card when Memory is connected. ### Tasks and work continuity A cabinet task is not merely a chat message. It links the business goal, constraints, data scope, executor, progress, migrations or other changes, evidence, approval and outcome. Codex can continue a task in another session, and another compatible agent can take over from the bounded task projection without copying the full conversation. ### Agent swarm X-MP can present a coordinated team rather than one overloaded assistant: - a managing agent holds the owner goal and portfolio priorities; - sales, advertising, pricing, inventory/supply, content and finance specialists inspect their domains; - an observer watches freshness, anomalies, task failures and outcome windows; - Memory returns relevant reviewed experience; - the manager resolves conflicts and routes material decisions to the owner. The swarm does not receive unlimited raw access. X-MP prepares the tenant-local data context and exposes only registered tools. Every specialist remains inside the same account scope, autonomy policy and approval boundary. ### Telegram owner channel Telegram is an optional tenant-local channel for short task success/failure notices, redacted signals and owner interaction. On nodes with the isolated Codex bridge, an onboarded owner can use `/ask`. Bot tokens, chat IDs, full reports and private cabinet payloads remain on the tenant node and are not copied into the central account database or public agent documents. ## 8. Machine-readable service map The canonical complete public catalog is ; the human-readable Markdown projection is . It is generated from the same versioned registry used by the X-MP Account runtime and lists every block and connector, its owner, baseline state, visibility, authentication class, effect ceiling, documentation, health/OpenAPI/MCP routes and active versus planned tools. After authentication, call MCP `xmp.services.list` (or `xmp.connectors.list`). Its account-bound state and effective tool list have priority over the public baseline. Never infer availability from a documentation page, a saved credential or a roadmap entry. ## 9. Connection procedure for an agent 1. Fetch `/services`, `/agents.md` and the relevant public health endpoint. 2. Fetch the service OpenAPI document. Treat it as the current route and payload contract; this guide describes behavior and safety boundaries. 3. Obtain the correct service-specific credential through an operator-approved secret file, sidecar or credential broker. The website never issues tokens. 4. Keep credentials out of URLs, prompts, source code, Markdown, browser storage, logs, traces, task cards and error messages. 5. For Memory, call token-bound `/services/memory/v3/me` before other protected operations. Identity, tenant and account scope come from the token; never ask the caller to choose or override them. 6. For Wildberries, call `/services/wildberries/v1/tools` or MCP `tools/list` after authorization, then use only declared read-only tools. 7. Preserve evidence references, time ranges, service versions and limitations in analytical output. 8. Before any future write-capable operation, require an explicit action contract, authority, limits, idempotency key, before-state and rollback. Recommended credential pattern: ```text agent runtime -> private token-file or credential sidecar -> Authorization header ``` Do not copy token contents into an environment dump or command line. Do not use the internal Redis Wildberries token as client authentication. ## 10. Wildberries connector The connector is a bounded, read-only public-web service. It currently exposes nine logical tools over REST and MCP: - product commerce card by `nmID`; - catalog search; - search suggestions; - one supplier; - a batch of suppliers; - static product card; - rich content; - brand data; - product questions. The connector selects a short-lived WB public token inside its own credential boundary and uses a protected rotating outbound proxy pool. Neither the WB token nor proxy credentials are returned to clients. Important limitations: - public-web routes are not official seller write APIs and may change; - an upstream `403` or `429` is not proof that a product or seller does not exist; - search/session-dependent methods may require a compatible current WB browser contract; - the connector does not automate seller-cabinet cookies or perform writes. ## 11. Seller Agent Memory Memory stores operational context, not primary marketplace numbers. Marketplace facts remain in the Data Platform and immutable source artifacts. Memory keeps a bounded, auditable chain such as: ```text request -> hypothesis -> evidence ref -> decision -> action -> measured outcome ``` Use v3 for token-bound identity, boards, task cards, search/resume, checklists, timeline, links, evidence/artifact references, task reports and typed memory. Use v4 only for capabilities advertised by the current OpenAPI, such as scoped collaboration. Legacy v1/v2 is intentionally unavailable on the public gateway. Rules: - never send caller-selected `tenant_id` or `account_id` to override identity; - distinguish facts, hypotheses, decisions, actions and outcomes; - do not store raw marketplace payloads, full conversations or tool transcripts; - do not silently overwrite contradictions or corrections; - close work with result status, evidence, limitations and next step; - do not call a recommendation successful until an outcome is measured. The public domain exposes the REST/OpenAPI profile. A private Memory MCP sidecar, when installed for a specific agent runtime, remains inside its credential boundary and is not advertised as a public endpoint. ## 12. Expected analytical response For a business question, return a compact structure: ```markdown ## Conclusion One clear business answer. ## Verified facts - Metric, entity, period and evidence reference. ## Explanation - Confirmed cause or explicitly labeled hypothesis. ## Money impact - Revenue, profit, cost, working-capital or risk effect when supported. ## Recommended next step - Action, required approval, limit and rollback. ## Measurement - Baseline, observation window and success criterion. ## Limitations - Missing or stale data and alternative explanations. ``` Never invent a percentage uplift, revenue result or causal explanation. If data is missing, say what is missing and how to obtain it. ## 13. Business priority model Evaluate opportunities as separate visible components rather than one opaque score: - expected profit or cash preserved; - confidence and data quality; - time to effect; - required capital and capital at risk; - urgency and cost of inaction; - reversibility; - conflicts with inventory, money or other plans. Opportunity types are `growth`, `loss-prevention`, `capital-release` and `risk-avoidance`. Compare “act”, “wait” and “do nothing” before proposing a plan. ## 14. Current production versus roadmap Current foundation: - TLS service gateway and machine-readable discovery; - read-only Wildberries REST/MCP connector; - protected Memory v3/v4 REST/OpenAPI; - tenant-local data, storage, scheduling and lineage foundations; - deterministic reports and operational signals. Controlled roadmap, not a blanket production promise: - unified state of business; - portfolio of money-ranked opportunities; - advertising, pricing, inventory and supply controllers; - increasing autonomy per operation type after canary and measured outcomes; - common management model for Wildberries, Ozon and Yandex Market. ## 15. Security and reliability invariants - Tenant data, queues, cursors, storage and credentials are isolated. - Raw data is immutable; derived data carries source lineage and schema version. - Marketplace write operations are deny-by-default. - High-risk, irreversible or financially material actions require owner authority. - Unknown or stale data is not rendered as healthy or certain. - Memory and project documentation are retrieved on demand; do not load all context. - Never expose infrastructure addresses, secret references or private business metrics in public output. - On `401`, stop and obtain the correct service credential. On `404` for Memory v1/v2, migrate to v3/v4; do not try to bypass the gateway. ## 16. Canonical references - Service index: - Complete version and route catalog: - Complete Markdown catalog: - Versioned full catalog: - Wildberries OpenAPI: - Wildberries MCP: - Memory OpenAPI: - Human product explanation: Last reviewed: 2026-09-03. Re-fetch the catalog, OpenAPI and health at the start of each new agent session; do not assume this Markdown replaces live service contracts. ## Advertising bidder v2 Current bidder supports fixed/target-DRR shadow proposals, explicit bid bounds, work windows, per-campaign daily limit/reserve and stock/freshness/sample gates. Use the installed `xmp-advertising-bidder` skill, `automations.catalog` bidder_v2 contract, config.get/apply and jobs/runs. Funding, CTR/conversion/CPA strategies and marketplace execution remain pending. Updating instructions does not enable spending or change shop limits. - Settings and MCP/API: https://x-mp.ru/cabinet/static/xmp-bidder.md - Disabled template: https://x-mp.ru/cabinet/static/xmp-bidder.example.json - Machine contract: https://x-mp.ru/cabinet/static/xmp-bidder-capabilities.json - Task workflow: https://x-mp.ru/cabinet/static/xmp-bidder-workflow.md Project-local automatic delivery is opt-in (`--auto-update` at installation, or current `xmp.update.apply(confirm=true,auto_update=true)`). The running client checks every 300 seconds by default, verifies the package and notifies the agent to reread current skills. Offline or manual clients are not silently enrolled.