Skip to main content

MCP Tool Map

The tools that Ask (chat) AI and automations can call come from seven MCP servers. This page lays out which server handles what, and why the AI sometimes doesn't use a tool even though it exists.

                              묻기(코파일럿) 의 AI
                                       │
   ┌────────────┬────────────┬─────────┼──┬────────────┬────────────┬────────────┐
   ▼            ▼            ▼            ▼            ▼            ▼            ▼
 플랫폼 통합   시계열 인사이트   RAG       문서 이해      비전       디지털 스레드     공학 계산
 /api/v5/mcp  insight_ 39개  rag_ 2개  document_ 2개  vision_ 5개  thread_ 4~9개   eng_ 4개
   22개
 «공장의 실제  «파형을 보고   «문서에서   «PDF·표를     «사진을     «무엇이 언제     «공식으로
   데이터»      판단»         찾는다»     읽는다»       본다»       일어났고 무엇과    계산한다»
                                                                  이어졌나»

The copilot does not attach these servers directly. From 2026.10 re-release (2026-10-20), a single MCP Gateway (plantpulse-mcp-gateway-api, internal 7160) gathers the tools of the platform · built-in servers · external servers the operator has attached, and the copilot looks only at that one address. The gateway registers the built-in servers itself at installation.

Tools enabled at first — gateway policy​

Whether a tool is on or off when first discovered is decided by the MCP Gateway's policy. The place to change on/off is AI Admin Console › MCP Gateway › Tools → AI Admin Console — MCP Gateway

ServerWhen first discovered
Platform Integration MCPAll on
Time series insights insight_34 on — of the 39, the one write tool (trigger_feature_pipeline, cannot be enabled) and the four forecast_order_completion · autonomy_status · get_oee_losses · get_spc_chart are off → Time series insights tools
Digital Thread thread_9 on — all the read tools
Engineering calculation eng_4 on — all four
RAG rag_2 on — rag_search (document search) · rag_list_documents
Document Understanding document_2 on — document_understand · document_profiles
Vision vision_5 on — vision_read_meter · vision_inspect · vision_ocr · vision_analyze · vision_classify
External servers attached by the operatorOff — read each tool's description and enable it
  • The lists are written by name. When a new tool appears on a built-in server, it comes in disabled.
  • A value an administrator has changed once stays in the gateway DB, and neither a restart nor an upgrade overwrites it.
  • 🔴 Document search in chat goes only through rag_search. If this tool is off or not allowed for the account, manual · drawing · procedure questions are answered with "Document search is turned off or not allowed for this account."
  • 🔴 Enabling this many assumes that tool search is on. For each question the gateway picks up to 20 matching tools (the budget) and loads them for the model, and search_domains, which finds name → ID, and document search rag_search are always loaded separately regardless of the budget (when allowed for the account). If you turn search off in Search Settings, the model receives all 70-some enabled tools for every question.
  • Search picks tools by their search terms as well as their name · description. Tool descriptions are in English, so these are words that link Korean questions to tools; they are used only in keyword search and are not shown to the model. The sources win in the order this installation's override › server declaration › gateway default (platform integration MCP). An external MCP server can declare them in the tool's _meta["io.plantpulse/search_terms"] as in {"ko": ["알람 확인 처리"]}. Per tool, up to 4 languages and 8 terms · 64 characters across all languages; anything beyond is discarded entirely → AI Admin Console — Tool search terms

In older releases (up to re-release 8) the copilot held the on/off values, and for time series insights only a few such as get_attention_ranking were on. When you upgrade to re-release (2026-10-20) those values are not carried over and everything restarts from the policy above. If you deliberately turned off tools in the older release, turn them off again after upgrading.

There are two reasons for this.

  1. Throw dozens of tools at an AI and it fails to pick the right one.
  2. Descriptions of tools you will never use consume tokens on every request.

So the tools to enable are fixed by policy, and among the enabled ones, search narrows them down for each question.

A newly attached external server starts disabled and allowed to no one

Even after you add an external server to the gateway and read its tools, neither the AI nor automations can use anything. You must enable the server, enable each tool, and allow it for the caller (the copilot) under Permissions. An external tool's description goes into the model prompt as-is, so read it before enabling.

This is the first thing to check when "the tool exists but the AI won't use it" → AI Admin Console — MCP Gateway

Write tools cannot be enabled

Tools that change state are hidden automatically and blocked by policy. The single exception is alarm acknowledgement (ack_alarm), and even that passes only after the target equipment scope has been verified. There is no mechanism at all for controlling equipment or changing settings.

Platform Integration MCP — 22 tools​

The actual factory data. Platform (server-web) serves it over /api/v5/mcp and authenticates with api_key.

AxisToolWhat it does
Timeget_current_timeCurrent server time
Structuresearch_domainsResolve an ID by searching on name (usually the starting point)
Structureget_asset_treeAsset hierarchy tree
Structureget_ontologySite ontology overview
Structurequery_ontologyTraverse the asset relationship graph
Structurequery_sparqlOntology SPARQL query
Structureget_asset_documentsList of documents attached to equipment
Connectionget_edge_statusEdge gateway status
Connectionget_edge_health_historyEdge health history (daily intervals)
Connectionlist_connectionsList of OPC collection connections
Tagget_tag_valuesCurrent tag value
Tagget_tag_historyTag history over a period
Alarmlist_alarmsAlarm list
Alarmget_alarm_contextAlarm root-cause diagnostic bundle
Alarmack_alarmAlarm acknowledgement — 🔴 the only write tool
Equipmentget_asset_snapshotSnapshot of all tags on a piece of equipment
Equipmentget_asset_timelineEquipment event timeline
Equipmentget_asset_statsEquipment business statistics over a period
Productionlist_ordersWork order list
Productionget_order_metricsWork order detail · KPIs
Productionget_asset_kpiPer-order equipment KPIs (OEE/EMS/RAM)
Rollupget_healthAsset hierarchy health rollup
Turning a name into an ID is almost always the first step

People say "the line 3 compressor" while tools take IDs. search_domains bridges the two — if the AI picked the wrong equipment, that is usually where it diverged.

Usage is covered in MCP Server Management; the ontology tools are detailed in Ontology.

Time Series Insights — 39 insight_ tools​

The side that looks at waveforms and judges. Anomaly detection, prediction, historical comparison, equipment summaries, alarm statistics, profiling, and — from 2026.10 — AI findings, equipment to watch, and production analysis (order completion forecast · OEE loss · control charts).

→ Full list of time series insight tools

RAG — 2 rag_ tools​

ToolWhat it does
rag_searchFinds relevant documents in hybrid mode and returns an answer with sources. Each source's reference_id pairs with the [n] in the answer body
rag_list_documentsList of indexed documents
If nothing is found, it comes back as «failure»

When the search retrieves nothing, rag_search returns success: false · retrieved: false along with code (NO_CONTEXT · EMPTY_ANSWER) · reason and does not include answer. This prevents the AI from receiving an empty result as "search results" and fabricating an answer from its own knowledge — the AI replying "I could not find this in the documents" is normal behavior.

→ Document Search (RAG)

Document Understanding — 2 document_ tools​

ToolWhat it does
document_understandConverts a single document at a URL into structured markdown — recognizing tables, layout, and formulas. PDF · DOCX · PPTX · XLSX · images
document_profilesList of selectable parsing profiles
ProfileUse
defaultSame options as RAG indexing — for checking "how did RAG read this document?"
fastFast — OCR off, tables handled roughly
ocrText only — reads characters from images (table structure recognition off)
scanScanned originals — ignores the text layer and OCRs everything
Why profiles exist as a separate concept

If each caller picked its own parsing options, the same document would be read differently depending on who called. So the policies are bundled into profiles — for anything in the "tables come out broken" category, switching profiles is the first move.

Zero extracted characters counts as «failure»

Even if the parser reports success, an empty body comes back as ok: false (the REST response is status: "empty"). This usually means a scan with no text layer was read without OCR, so call again with the scan or ocr profile.

The per-document limit defaults to 200 MiB (MAX_DOCUMENT_BYTES); anything larger is rejected (413 over REST). The agent path waits for the result but returns a failure once MCP_WAIT_TIMEOUT (300 seconds by default) is exceeded.

Vision — 5 vision_ tools​

Looks at photos. Stateless — images are processed and discarded, never stored.

ToolWhat it does
vision_read_meterReads the indicated value on an instrument (gauge or digital display)
vision_inspectFinds defects in equipment photos — oil leaks, corrosion, cracks, breakage, foreign matter, overheating
vision_ocrReads text in a photo — nameplates, labels, signage, screens. Korean is transcribed as Korean
vision_classifyClassifies into one of the supplied labels (requires 2 or more labels)
vision_analyzeAsk anything about a photo
When judgments disagree, it refuses

Vision does not guess at ambiguous cases. If the same photo is judged several times and no consensus is reached, it refuses rather than inventing an answer — because in field judgment, a "plausible wrong answer" costs far more than "I don't know."

ToolConsensus rule
vision_read_meter4 out of 5 — value and unit must match exactly (strictest)
vision_inspect · vision_classify2 out of 3 — the judgment (label) must match
vision_analyzeNo consensus — free-form description, so do not use it for readings or pass/fail decisions
vision_ocr2 out of 3 — the strings must match with whitespace removed. From the 2026.10 re-release, the served LLM does the reading (before that it was Document Understanding's docling OCR — which could not read Korean). The engine can be reverted with VISION_OCR_ENGINE → Environment Variable Settings

Digital Thread — 4 to 9 thread_ tools​

Shows what happened in the plant, in what order, and what is connected to what. It returns references to events and connections rather than values — measurements and KPIs belong to Platform Integration MCP or Time Series Insights.

ToolWhat it doesDefault
thread_get_timelineWhat happened, in chronological order, to one piece of equipment, order, or tag — state changes, alarms raised/cleared, order start/finish, planned stops, plus copilot incidents, suggestions, and findings. The window is at most 31 daysOn
thread_trace_linksHow objects are connected — equipment hierarchy, tags, supply/dependency between equipment, work instructions tied to equipment, processes, parts, orders run on equipment, incidents raised against equipment, suggestions. Give it two objects and it returns the shortest pathOn
thread_today_workThe supervisor's work list for today (today when date is omitted) — for each process planned that day or running on Platform: readiness, equipment status, the slack days and risk of the customer order it fulfills, the material POs being waited on, and the drawings and revision labels to use. Tightest customer slack firstOn
thread_impact_rangeHow far a late PO · supplier · equipment · defective lot reaches — work orders · customer orders · customers. Forward (where a delay reaches: from PO lines · suppliers · parts · equipment · design changes · maintenance work orders) or backward (quality trace: from lots · serial numbers · nonconformities · tools · samples). With as_of it gives the links as of a past point in time, and customer order lines carry the ERP due date and days remaining (D-n). Families that are not connected are «unknown», not «none»On
thread_interval_productionWhat was being made on that equipment during an equipment anomaly · alarm · stop interval — the work orders · lots · serial numbers in that interval (MES execution times) and the customer orders · customers those lots reach. The interval is at most 31 days. Without MES it is «unknown», not «nothing ran», and customers reached only through links created after the interval are listed separately from confirmed impactOn
thread_explain_recoveryHow far milestones slip when a part is late, plus recovery options (what-if) — the numbers come from the server's optimization solver and the AI only relays them. With PLM · QM connectors enabled it also reports added delay from design changes and nonconformities, and if SCM supplies supplier capacity it answers whether a late part can be pulled in. It also includes the affected customer order lines (customer_orders[]) and PO values where ERP and SCM disagree (purchase_order_conflicts[])On
thread_work_readinessSupervisor work readiness — GO · AT_RISK · NO_GO · UNKNOWN per process with item-level reasonsOn
thread_part_revision_statusWhether a part number · revision is the one currently approved for use — current · outdated · change_open · unknownOn
thread_check_toolingFrom the tool management connector — measurements taken with instruments that are overdue for calibration or have been dropped, tools used on a work order, candidate causes of nonconformitiesOn
  • All are read-only (called without approval). Results are trimmed to under 16,000 characters.
  • The conditions for appearing in the server list differ. the four get_timeline · trace_links · impact_range · interval_production are always present; explain_recovery appears when a source for its input (such as the connector registry) is configured; and the four today_work · work_readiness · part_revision_status · check_tooling appear only when the connector registry (DT_PG_* · PI_DT_SECRET_KEY) is configured. Hence the range of 4 to 9.
  • From re-release (2026-10-20), all nine are on from the start (gateway policy). The place to turn them off is AI Admin Console › MCP Gateway › Tools → MCP Gateway
  • Objects in the results of trace_links · get_timeline · impact_range · interval_production (for the timeline, the events' subjects and the head) get the source system screen address open_url and the button text open_label only when that system's connector has a link template. Otherwise neither field is present → Digital Thread — External links
  • Attaching connectors and populating the mirror is done in the admin console → Digital Thread

Engineering Calculation — 4 eng_ tools​

Computes engineering values from formulas — bearing fault frequencies, NPSH, and the like. This is the server that keeps the model from estimating in its head. The server is plantpulse-engcalc-api (:7150 inside the stack, not exposed externally) and runs without a DB, volumes, or an LLM. There is no separate switch — it comes up with the stack, always.

ToolDisplay nameWhat it doesDefault
eng_list_formulasEngineering formula listList of formulas available for calculationOn
eng_formulaEngineering formula calculation29 named formulas — returns the answer along with units, substitution steps, and the sourceOn
eng_unit_convertUnit conversionConvert unitsOn
eng_calc_evalExpression evaluationEvaluates expressions such as arithmetic and exponentiation. Only permitted operations are solved, with limits on exponents, length, and time (it does not run programs)On
  • All are read-only and are therefore called without approval.
  • The key is the same PI_INBOUND_API_KEY used by the other backends. If it is empty, the server refuses to start.

External system connectors are not attached here​

MCP connectors for external systems such as MES · SCM · ERP · PLM · QM are registered under AI Admin Console → Digital Thread → Integration Map. They are enabled only after passing a conformance test there, and the copilot uses them through the Digital Thread server.

  • If you attach one to the MCP Gateway as an external server, its connector tools (those starting with mes_ · scm_ · sched_ · erp_ · plm_ · qm_ · cmms_ · tool_ · wms_ · lims_ · ehs_) cannot be enabled — only the Digital Thread relays these tools.
  • If you had external connectors registered with the copilot in an older release, those records are deleted in re-release (2026-10-20). Register them again in the Integration Map and re-enter the credentials → Digital Thread

Tools that take a URL — internal addresses are rejected​

The Document Understanding and Vision tools take a URL, not a file. That URL is a string the AI produced, so accepting it without restriction would let the AI have something read on its behalf that is only reachable from inside the container. So it is blocked at the entry point.

  • Only http · https are accepted.
  • If the address resolves to loopback · private ranges (10/8 · 172.16/12 · 192.168/16) · link-local (including cloud metadata), it is rejected. Redirects are re-checked at every hop.
  • Size limits — 200 MiB for documents, 32 MiB for photos.

On rejection the tool returns ok: false and a refused to fetch … reason.

URLs on an internal file server are readable only if «added to the allowlist»

Documents and photos at internal addresses, such as http://192.168.x.x/…, are rejected by default. List the hosts you want opened in FETCH_ALLOWED_HOSTS (comma-separated for multiple; empty by default) in /etc/kopens/plantpulse-ai.env, and compose passes it to both Document Understanding and Vision (as of the 2026.10 re-release).

  • The entry must exactly match the URL's host name (case-insensitive). Appending a port, as in files.example.local:8080, allows only that port. For a server addressed by IP, write the IP as-is. There are no wildcards or ranges.
  • Allowed hosts are still subject to http · https and the size limits, and a redirect to another internal address is rejected at that point.
  • After editing, recreate the two services with bin/restart.sh plantpulse-document-understanding-api plantpulse-vision-api.

→ Environment Variable Settings

Naming convention​

Backend tool names are snake_case (vision_read_meter). The prefix is added by the MCP Gateway, so the name you see in the server documentation (read_meter) may differ from the name used in chat (vision_read_meter).

  • If two servers expose the same name, the one registered first wins and the later one is not exposed (shown as a conflict on the Tools screen). Resolve it by changing the later server's prefix.

🔴 Do not transcribe tool lists by hand. The source of truth for the installation's state (what is on) is the gateway DB; the screen is AI Admin Console › MCP Gateway › Tools, and the complete list is the gateway REST GET /api/v1/tools. The gateway re-reads each server's tool list at startup and every 5 minutes, and you can also make it re-read on the spot with Rediscover on the Servers screen.

The other direction — the copilot is also an MCP server​

Everything so far has been about the copilot «using» tools. In the other direction, another AI agent can use the copilot as a tool, because the copilot exposes its own capabilities over MCP.

ItemValue
EndpointPOST /mcp (a trailing-slash /mcp/ is also accepted)
ProtocolJSON-RPC 2.0
AuthenticationSame as /api/v1 — X-API-Key only (from 2026.10 re-release 6, login sessions get 403)
ToolWhat it does
ask_plantNatural-language question → answer. The copilot picks the query tools it needs on its own, and the supporting evidence comes with the answer. It asks with the permissions of the API key's principal (the person the key was issued to), and leaving sessionId empty opens a new conversation owned by that principal
list_plant_toolsList of query tools the copilot can reach «right now»
daily_tasksMorning card (KST)
Why only three — read access only

Tools that change things have a human approval step attached, and a caller coming in over MCP knows nothing about that step. So only queries are exposed.

The three are functionally identical to /api/v1 and delegate to the same implementation — the same capability exposed over two protocols, with one copy of the code. Two copies means only one of them gets fixed.

Both trailing-slash forms are accepted

Both /mcp and /mcp/ work. Clients differ in which form they call, and that single character bouncing every call with a 307 has actually happened. Callers of our endpoint will not step into that trap.