OpenCore MES Try the demo

Docs Integration 7

Other ways in

On this page
AI access on the designer's home: the MCP and REST addresses, and a form to issue a token
AI access, on the designer's home: tokens through which an AI designs as a person, over MCP or the REST API.
AI access on the designer's home: the MCP and REST addresses, and a form to issue a tokenAI access, on the designer's home: tokens through which an AI designs as a person, over MCP or the REST API.

7.1 The AI design API

An AI works in the designer as the person whose token it holds: it reads, drafts, checks, tests and dry-runs, and never reviews, approves, executes or verifies a change. Tokens are issued in Designer → AI access, with scopes of design:read, design:draft, design:submit (submitting is optional); the web scopes (service:call, transaction:run, query:run, file:upload) are given only by node app/mes/db/token.mjs <user> "<name>" --scope …. GET /ai/v1/openapi.json describes it; node app/mes/test/ai-agent.mjs is an agent's whole loop.

RouteDoes
GET /me · /contract · /catalogwho the token is; the design contract (and the published contracts' names); the plant's model
GET /suitesthe installed suites: their versions and a newer one, what each gives designs, its design pack against what is live, its set-up guide, every version run here and what each gave; suites removed; what every live design needs from suites, given or not and why, with the version that last gave it and the command back
GET /contracts/{name}a published contract (docs/contracts: equipment-adapter, http-apis, embedding), its specification, schema and conformance kit
GET /objects/{name} · /scripts/{name} · /flows/{name}a live design
POST /index · GET /designs/{kind}/{name} · POST /related · /search · /organizationthe plant's model a part at a time: the map of every design by kind; one design whole (an object with its rule scripts); what a design uses and what uses it (an object's rule pipe, the transactions touching it with their checks and policies, the objects it depends on; a transaction's checks and every object it writes with the rules that apply); where a word is written; departments, groups and people
POST /catalog · /runsonly the parts of the catalog named; the integration's run history
POST /mcpthe same tools over the Model Context Protocol (Streamable HTTP; 2026-07-28, and 2025-03-26 to 2025-11-25 through initialize), for Claude Code, Claude Desktop or any MCP client: claude mcp add --transport http opencore-mes <the MES>/ai/v1/mcp --header "Authorization: Bearer <token>"
GET · POST /changes; GET · PUT /changes/{id}list and start changes; read and save a draft
GET /model · POST /model/preview · /model/changesevery published design as one model file (no records, secrets or history); what a model file would change here; one change request from it
POST /changes/{id}/includebring a live object, transaction, screen, flow, service or connection into a change, to change several together (one review, one approval per department)
POST /validate · /scripts/{name}/test · /pipe/run · /access/simulate · /dry-runcheck a draft; run a script's tests; run a rule pipe; simulate access; dry-run a service
POST /flows/check · /flows/layout · /flows/explain · /flows/walk · /scenarios/tryflow templates and their scenarios; an input flow walked with sample values
POST /changes/{id}/fitness · /changes/{id}/submitrun the fitness test; submit (with the scope; where the plant executes by hand, the first submission names the executor the person says: { "executor": "" })

Requests are JSON; a token sending too many is answered 429.

The Copilot tab on a change to the lot object: Claude ready, a box to ask in words
The copilot on a change: ask in words; it drafts and checks through the design tools as you, and you submit.
The Copilot tab on a change to the lot object: Claude ready, a box to ask in wordsThe copilot on a change: ask in words; it drafts and checks through the design tools as you, and you submit.

7.2 The copilot package

The copilots (the designer's, the integration monitor's, AI Report's) are one package, @opencore-mes/copilot, in a repository of its own and released on its own. It reaches the core through one contract, docs/contracts/copilot-host, and nothing else: the core gives it the tools (as the person who asks), the conversations it keeps, the send limits, the attachments and the AI settings; the package gives back each role's services, its models and its chat panels. A plant upgrades it without a restart (the installation procedure, IN-53).

  • Check a version against the contract, changing nothing: node docs/contracts/copilot-host/kit.mjs <package folder>: its manifest and the host range it is built for, what it imports (only its own files, node: and its own dependencies), activate(host) on a stand-in host, and its panels registered under a tag.
  • Work on it beside a checkout of the core: COPILOT_FROM=<its folder> npm run dev makes that working copy answer.
  • What the core keeps: every decision about what a copilot may read or change (its tools are the core's, written into the contract with their arguments and answers), and every service name it answers (fixed at start, forwarding to the version in use).

7.3 Versions and notice

/ai/v1 and /svc/v1 keep what they promise for as long as /v1 runs: the contract docs/contracts/http-apis writes it down (every /ai/v1 operation with its scope and the fields it reads; the /svc/v1 envelope, its statuses and its error body { error, code?, fields? }). A new version may add; nothing promised leaves /v1 (that is /v2, beside it).

  • Every answer carries API-Version: 1.26.
  • Shapes are kept. What each operation and MCP tool takes and answers is written down as a shape (types, required fields, values): a request may grow looser, never stricter; an answer may grow, never lose a field it always gave nor change its type. Each route's answer is in the OpenAPI document; over MCP it is the tool's outputSchema, and the answer comes as structuredContent too. Compare your own copy with compareShapes in docs/contracts/http-apis/surface.mjs.
  • A tool given notice starts its description with it (when, its sunset, what to use instead), which is what the model reads, and carries it in each answer's _meta["io.opencoremes/deprecated"]: an agent moves before the sunset by itself.
  • Notice first. What /v1 will lose is marked deprecated at least 180 days before it goes; each answer to it then carries Deprecation (when it was deprecated), Sunset (the date after which it may go) and Link (its successor). Log them, and move before the sunset. Nothing is deprecated today.
  • A plant's web services are the plant's promise to you. A change that would break a caller who called in the last 30 days is refused at the plant's review unless the plant gave notice first: the service then answers you with the same headers until its sunset, and its OpenAPI description says until when and what to use instead.

Check an instance yourself, changing nothing: node docs/contracts/http-apis/kit.mjs --url <the MES> --token <a token> (add --service <name> --input <json> to try a call and its retry; --json for a program).

7.4 Languages and language packs

A plant sets its language and those it offers (People & departments, approved by governance); each person picks theirs. What a caller of /ai/v1 or /svc/v1 reads never depends on it: both answer in English (refusals, messages, the words of fields), as the contract promises, so parse and log them as before.

  • A language pack is a package with one file, language.json, and no code: the platform's words keyed by their English as app/mes/i18n/source.json lists them, values as {name}, counts as {n, plural, …} in the language's own forms. It is installed as a suite is (opencore-mes suite install lang-de). Check one with node docs/contracts/language-pack/kit.mjs <folder>; start one with kit.mjs new <tag>. A pack's coverage never stops anything: a word it lacks is said in English.
  • A design's own words are not in a pack: each design carries translations, keyed by its English, changed and approved with it. Through /ai/v1, POST /texts (kind, name, or a whole design) says which words a design shows and, per language, which are translated, missing or no longer said; translations are saved with PUT /changes/{id} as any part of it.
  • A signature made in another language keeps the meaning as designed, the words its signer read and their language, together.

7.5 Excel import and export

Records go in and out as spreadsheets from Data → Import / export, through the same forms' checks, as the person importing: what an object's design allows (create, update, the key rows are matched by). See the user guide, section 13.

7.6 What is not an interface

The browser's own calls (/api/…) and the database are internals: they change without notice and are not to be built on. Integrate through web services, connections, the AI API, or files.

7.7 Planned

Planned. The extension API: a narrow, versioned surface for suites (core-api), with its machine-readable schema and conformance kit; today a suite is handed the core's context. Equipment data collection: high-rate machine data outside the MES, which receives only derived events. Neither is built. The versioned HTTP APIs and the equipment adapter contract are built (1.2); the adapters themselves (SECS/GEM over HSMS, OPC UA, MQTT) come with the Equipment integration suite, not the core.