본문으로 건너뛰기

MCP 도구 지도

묻기(채팅)의 AI 와 자동화가 부를 수 있는 도구는 MCP 서버 일곱 곳에서 옵니다. 어느 서버가 무엇을 맡는지와, 왜 도구가 있는데도 AI 가 안 쓰는지를 여기서 정리합니다.

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

코파일럿은 이 서버들을 직접 붙이지 않습니다. 2026.10 재릴리즈(2026-10-20) 부터 MCP 게이트웨이(plantpulse-mcp-gateway-api, 내부 7160) 하나가 플랫폼 · 내장 서버 · 운영자가 붙인 외부 서버의 도구를 모아 내고, 코파일럿은 그 주소 하나만 봅니다. 내장 서버는 게이트웨이가 설치 때 스스로 등록합니다.


처음 켜 두는 도구 — 게이트웨이 정책​

도구가 처음 발견될 때 켤지 끌지는 MCP 게이트웨이의 정책이 정합니다. 켬/끔을 바꾸는 자리는 AI 관리 콘솔 › MCP 게이트웨이 › 도구 입니다 → AI 관리 콘솔 — MCP 게이트웨이

서버처음 발견될 때
플랫폼 통합 MCP전부 켬
시계열 인사이트 insight_34종 켬 — 39종 가운데 쓰기 하나(trigger_feature_pipeline, 켤 수 없음)와 forecast_order_completion · autonomy_status · get_oee_losses · get_spc_chart 넷은 꺼짐 → 시계열 인사이트 도구
디지털 스레드 thread_9종 켬 — 읽기 도구 전부
공학 계산 eng_4종 켬 — 넷 다
RAG rag_2종 켬 — rag_search(문서 검색) · rag_list_documents
문서 이해 document_2종 켬 — document_understand · document_profiles
비전 vision_5종 켬 — vision_read_meter · vision_inspect · vision_ocr · vision_analyze · vision_classify
운영자가 붙인 외부 서버꺼짐 — 도구마다 설명을 읽고 켭니다
  • 목록은 이름으로 적혀 있습니다. 내장 서버에 새 도구가 생기면 꺼진 채 들어옵니다.
  • 관리자가 한 번 바꾼 값은 게이트웨이 DB 에 남고, 기동이나 판 올림이 덮지 않습니다.
  • 🔴 채팅의 문서 검색은 rag_search 한 길입니다. 이 도구가 꺼져 있거나 계정에 허용되지 않으면 매뉴얼 · 도면 · 절차 질문에 「문서 검색 도구가 꺼져 있거나 이 계정에 허용되지 않았습니다」 로 답합니다.
  • 🔴 이만큼 켜 두는 것은 도구 검색이 켜져 있다는 전제입니다. 게이트웨이가 질문마다 맞는 도구를 20개(예산)까지 골라 모델에 싣고, 이름 → ID 를 찾는 search_domains 와 문서 검색 rag_search 는 예산과 상관없이 늘 따로 싣습니다(허용된 계정일 때). 검색 설정에서 검색을 끄면 모델이 질문마다 켜진 도구 70여 종을 다 받습니다.
  • 검색은 도구 이름 · 설명에 더해 검색어로 고릅니다. 도구 설명이 영어라 한국어 질문을 도구에 잇는 낱말이고, 낱말 검색에만 쓰여 모델에게는 보이지 않습니다. 출처는 이 설치의 덮어쓰기 › 서버 선언 › 게이트웨이 기본값(플랫폼 통합 MCP) 순으로 이깁니다. 외부 MCP 서버는 도구의 _meta["io.plantpulse/search_terms"] 에 {"ko": ["알람 확인 처리"]} 처럼 선언할 수 있습니다. 도구 하나에 언어 4개, 모든 언어를 합쳐 8개 · 64자까지이고 넘으면 통째로 버립니다 → AI 관리 콘솔 — 도구 검색어

옛 판(재릴리즈 8 까지)은 코파일럿이 켬/끔을 들고 있었고, 시계열 인사이트는 get_attention_ranking 등 몇 개만 켰습니다. 재릴리즈(2026-10-20) 로 올리면 그 값은 옮겨지지 않고 위 정책으로 다시 시작합니다. 옛 판에서 일부러 끈 도구가 있었다면 올린 뒤 다시 끄십시오.

이유는 둘입니다.

  1. AI 에게 도구를 수십 개 던지면 고르는 데 실패합니다.
  2. 쓰지 않을 도구의 설명이 매 요청마다 토큰을 먹습니다.

그래서 켤 도구를 정책으로 정해 두고, 켠 것 가운데서도 검색이 질문마다 좁힙니다.

새로 붙인 외부 서버는 꺼진 채, 아무에게도 허용되지 않은 채 시작합니다

게이트웨이에 외부 서버를 추가하고 도구를 읽어 와도 AI 도 자동화도 아무것도 못 씁니다. 서버를 켜고, 도구마다 켜고, 권한에서 호출자(코파일럿)에게 허용해야 합니다. 외부 도구의 설명은 모델 프롬프트에 그대로 들어가므로 읽어 보고 켜십시오.

「도구가 있는데 AI 가 안 쓴다」의 첫 확인 지점이 여기입니다 → AI 관리 콘솔 — MCP 게이트웨이

쓰기 도구는 켤 수 없습니다

상태를 바꾸는 도구는 자동으로 가려져 정책상 차단됩니다. 예외는 알람 확인(ack_alarm) 하나뿐이고, 그것도 대상 설비 범위까지 확인한 뒤에야 통과합니다. 설비를 제어하거나 설정을 바꾸는 수단은 아예 없습니다.


플랫폼 통합 MCP — 22개​

공장의 실제 데이터입니다. 플랫폼(server-web)이 /api/v5/mcp 로 내주고, api_key 로 인증합니다.

축도구하는 일
시간get_current_time서버 현재 시각
구조search_domains이름으로 찾아 ID 를 해소한다 (대개 여기서 시작한다)
구조get_asset_tree자산 계층 트리
구조get_ontology사이트 온톨로지 개요
구조query_ontology자산 관계 그래프 탐색
구조query_sparql온톨로지 SPARQL 질의
구조get_asset_documents설비에 붙은 문서 목록
연결get_edge_status엣지 게이트웨이 상태
연결get_edge_health_history엣지 건강 이력(일자별 구간)
연결list_connectionsOPC 수집 연결 목록
태그get_tag_values태그 현재값
태그get_tag_history태그 기간 이력
알람list_alarms알람 목록
알람get_alarm_context알람 원인 진단 번들
알람ack_alarm알람 확인 처리 — 🔴 유일한 쓰기 도구
설비get_asset_snapshot설비 전 태그 스냅샷
설비get_asset_timeline설비 이벤트 타임라인
설비get_asset_stats설비 기간 비즈니스 통계
생산list_orders워크오더 목록
생산get_order_metrics워크오더 상세·KPI
생산get_asset_kpi설비 오더별 KPI (OEE/EMS/RAM)
롤업get_health자산 계층 건강 롤업
이름을 ID 로 바꾸는 것이 거의 항상 첫 단계입니다

사람은 「3라인 압축기」라고 말하고 도구는 ID 를 받습니다. search_domains 가 그 사이를 잇습니다 — AI 가 엉뚱한 설비를 집었다면 대개 이 단계에서 갈린 것입니다.

사용법은 MCP 서버 관리, 온톨로지 도구의 자세한 쓰임은 온톨로지 에 있습니다.


시계열 인사이트 — insight_ 39개​

파형을 보고 판단하는 쪽입니다. 이상 탐지·예측·과거 대조·설비 종합·알람 통계·프로파일, 그리고 2026.10 부터 AI 발견 · 주의 설비 · 생산 분석(오더 완료 예측 · OEE 손실 · 관리도).

→ 시계열 인사이트 도구 전체 목록


RAG — rag_ 2개​

도구하는 일
rag_search관련 문서를 하이브리드 모드로 찾아 답과 출처를 낸다. 출처마다 reference_id 가 답 본문의 [n] 과 짝을 이룹니다
rag_list_documents색인된 문서 목록
못 찾으면 «실패» 로 돌아옵니다

검색이 아무것도 못 가져오면 rag_search 는 success: false · retrieved: false 와 code(NO_CONTEXT · EMPTY_ANSWER) · reason 을 돌려주고 answer 를 싣지 않습니다. 빈 결과를 «검색 결과» 로 받아 AI 가 자기 지식으로 답을 지어내는 것을 막기 위해서입니다 — AI 가 「문서에서 찾지 못했습니다」라고 답하는 것은 정상 동작입니다.

→ 문서 검색(RAG)


문서 이해 — document_ 2개​

도구하는 일
document_understandURL 의 문서 한 건을 구조화된 markdown 으로 바꾼다 — 표·레이아웃·수식을 인식. PDF · DOCX · PPTX · XLSX · 이미지
document_profiles고를 수 있는 파싱 프로필 목록
프로필쓰임
defaultRAG 색인과 같은 옵션 — 「RAG 는 이 문서를 어떻게 읽었나」를 볼 때
fast빠르게 — OCR 끔, 표는 대충
ocr글자만 — 이미지에서 글자를 읽습니다(표 구조 인식 끔)
scan스캔본 — 텍스트 층을 무시하고 전부 OCR
프로필이 따로 있는 이유

파싱 옵션을 부르는 쪽이 각자 고르면 같은 문서가 부르는 곳마다 다르게 읽힙니다. 그래서 정책을 프로필로 묶어 두었습니다 — 「표가 깨진다」 류는 프로필을 바꿔 보는 것이 첫 수입니다.

글자가 하나도 안 나오면 «실패» 입니다

파서가 성공이라고 해도 본문이 비어 있으면 ok: false 로 돌아옵니다(REST 응답은 status: "empty"). 대개 글자 층이 없는 스캔본을 OCR 없이 읽은 경우이니, scan 이나 ocr 프로필로 다시 부르십시오.

문서 한 건의 상한은 기본 200 MiB(MAX_DOCUMENT_BYTES)이고, 넘으면 거절됩니다(REST 는 413). 에이전트 경로는 결과가 나올 때까지 기다리되 MCP_WAIT_TIMEOUT(기본 300초) 을 넘기면 실패로 돌려줍니다.


비전 — vision_ 5개​

사진을 봅니다. 무상태입니다 — 이미지를 저장하지 않고 처리한 뒤 버립니다.

도구하는 일
vision_read_meter계기(게이지·디지털 표시기)의 지시값을 읽는다
vision_inspect설비 사진에서 결함을 찾는다 — 누유·부식·균열·파손·이물·과열
vision_ocr사진 속 글자를 읽는다 — 명판·라벨·표지·화면. 한국어는 한국어 그대로 옮깁니다
vision_classify주어진 라벨 중 하나로 분류한다 (라벨 2개 이상 필요)
vision_analyze사진에 대해 자유롭게 묻는다
판정이 갈리면 거부합니다

비전은 애매한 것을 찍지 않습니다. 같은 사진을 여러 번 판정시켜 합의에 이르지 못하면 답을 만들어 내는 대신 거부합니다 — 현장 판정에서 「그럴듯한 오답」이 「모르겠다」보다 훨씬 비싸기 때문입니다.

도구합의 규칙
vision_read_meter5번 중 4번 — 값과 단위가 정확히 같아야 합니다(가장 엄격)
vision_inspect · vision_classify3번 중 2번 — 판정(라벨)이 같아야 합니다
vision_analyze합의 없음 — 자유 서술이라 판독값·합격 판정에 쓰지 마십시오
vision_ocr3번 중 2번 — 공백을 뺀 글자열이 같아야 합니다. 2026.10 재릴리즈부터 서빙 중인 LLM 이 읽습니다(그 전에는 문서 이해의 docling OCR — 한국어를 못 읽었습니다). 엔진은 VISION_OCR_ENGINE 으로 되돌릴 수 있습니다 → 환경 변수 설정

디지털 스레드 — thread_ 4~9개​

공장에서 무슨 일이 어떤 순서로 일어났고, 무엇이 무엇과 이어져 있는지를 봅니다. 값이 아니라 사건과 연결의 참조를 돌려줍니다 — 측정값 · KPI 는 플랫폼 통합 MCP 나 시계열 인사이트 쪽입니다.

도구하는 일기본
thread_get_timeline설비 · 오더 · 태그 하나에 일어난 일을 시간순으로 — 상태 변화 · 알람 발생/해제 · 오더 시작/종료 · 계획 정지, 코파일럿의 이상 접수 · 제안 · 발견. 창은 최대 31일켜짐
thread_trace_links객체가 어떻게 이어져 있는지 — 설비 계층 · 태그 · 설비 사이 공급/의존 · 설비에 묶인 작업지시 · 공정 · 부품 · 설비에서 돈 오더 · 설비에 걸린 이상 접수 · 제안. 두 객체를 주면 최단 경로켜짐
thread_today_work반장의 오늘 작업 목록(date 생략 시 오늘) — 그날 계획되었거나 플랫폼에서 돌고 있는 공정마다 준비도 · 설비 상태 · 이행하는 고객 주문의 여유일과 위험 · 기다리는 자재 PO · 쓸 도면과 판 표찰. 고객 여유일이 빠듯한 것부터켜짐
thread_impact_range늦은 PO · 협력사 · 설비 · 불량 로트가 어디까지 닿는지 — 작업지시 · 고객 주문 · 고객. 앞으로(지연이 닿는 곳: PO 줄 · 협력사 · 부품 · 설비 · 설계 변경 · 정비 작업지시에서) 또는 뒤로(품질 추적: 로트 · 일련번호 · 부적합 · 공구 · 시료에서). as_of 로 지난 시점의 연결을, 고객 주문 줄에는 ERP 납기와 남은 날(D-n)을 싣습니다. 연결되지 않은 가족은 «없음» 이 아니라 «모름» 입니다켜짐
thread_interval_production설비 이상 · 알람 · 정지 구간에 그 설비에서 무엇을 만들고 있었나 — 그 구간의 작업지시 · 로트 · 일련번호(MES 실행 시각)와 그 로트가 닿는 고객 주문 · 고객. 구간은 최대 31일. MES 가 없으면 «아무것도 안 돌았다» 가 아니라 «모름» 이고, 구간 뒤에 생긴 연결로만 닿은 고객은 확정 영향과 갈라 적습니다켜짐
thread_explain_recovery부품이 늦을 때 마일스톤이 얼마나 밀리는지와 회복안(what-if) — 숫자는 서버의 최적화 풀이가 내고 AI 는 옮기기만 합니다. PLM · QM 커넥터가 켜져 있으면 설계 변경 · 부적합이 더한 지연을, SCM 이 협력사 공급 능력을 내면 늦은 부품을 당겨 받을 수 있는지도 답합니다. 영향이 닿는 고객 주문 줄(customer_orders[])과 ERP · SCM 이 어긋난 PO 값(purchase_order_conflicts[])도 싣습니다켜짐
thread_work_readiness반장 작업 준비도 — 공정마다 GO · AT_RISK · NO_GO · UNKNOWN 과 항목별 사유켜짐
thread_part_revision_status품번 · 판이 지금 써도 되는 판인지 — current · outdated · change_open · unknown켜짐
thread_check_tooling공구 관리 커넥터에서 — 교정이 늦었거나 떨어진 계측기로 잰 측정, 작업지시에 들어간 공구, 부적합의 원인 후보켜짐
  • 모두 읽기 전용입니다(승인 없이 불립니다). 결과는 16,000자 안으로 줄여 돌려줍니다.
  • 서버 목록에 나오는 조건이 다릅니다. get_timeline · trace_links · impact_range · interval_production 넷은 늘 있고, explain_recovery 는 입력을 읽을 곳(커넥터 등록부 등)이 설정돼 있을 때, today_work · work_readiness · part_revision_status · check_tooling 넷은 커넥터 등록부(DT_PG_* · PI_DT_SECRET_KEY)가 설정돼 있을 때만 나옵니다. 그래서 개수가 4~9개입니다.
  • 재릴리즈(2026-10-20) 부터 아홉 다 처음부터 켜져 있습니다(게이트웨이 정책). 끄는 자리는 AI 관리 콘솔 › MCP 게이트웨이 › 도구 입니다 → MCP 게이트웨이
  • trace_links · get_timeline · impact_range · interval_production 결과의 객체(타임라인은 사건의 대상과 머리)에는 그 시스템의 커넥터에 링크 틀이 있을 때만 원 시스템 화면 주소 open_url 과 버튼 글 open_label 이 붙습니다. 없으면 두 칸 모두 없습니다 → 디지털 스레드 — 외부 링크
  • 커넥터를 붙이고 거울을 채우는 것은 관리 콘솔 쪽입니다 → 디지털 스레드

공학 계산 — eng_ 4개​

베어링 결함 주파수 · NPSH 같은 공학 값을 공식으로 계산합니다. 모델이 머리로 어림하지 않게 하는 서버입니다. 서버는 plantpulse-engcalc-api(스택 안 :7150, 밖으로 열지 않음)이고 DB · 볼륨 · LLM 없이 돕니다. 따로 켜는 스위치는 없습니다 — 스택과 함께 늘 뜹니다.

도구화면 이름하는 일기본
eng_list_formulas공학 공식 목록계산할 수 있는 공식 목록켜짐
eng_formula공학 공식 계산이름 있는 공식 29종 — 답과 함께 단위 · 대입 단계 · 출처를 돌려줍니다켜짐
eng_unit_convert단위 변환단위 바꾸기켜짐
eng_calc_eval수식 계산사칙 · 지수 같은 수식 계산. 허용된 연산만 풀고 지수 · 길이 · 시간에 상한이 있습니다(프로그램을 돌리지 않습니다)켜짐
  • 모두 읽기 전용이라 승인 없이 불립니다.
  • 키는 다른 뒷단과 같은 PI_INBOUND_API_KEY 입니다. 비어 있으면 서버가 기동을 거부합니다.

외부 시스템 커넥터는 여기서 붙이지 않습니다​

MES · SCM · ERP · PLM · QM 같은 외부 시스템의 MCP 커넥터는 AI 관리 콘솔 → 디지털 스레드 → 연동 지도 에서 등록합니다. 거기서 적합성 시험을 통과해야 켜지고, 코파일럿은 그것을 디지털 스레드 서버를 통해 씁니다.

  • MCP 게이트웨이에 외부 서버로 붙이면 커넥터 도구(mes_ · scm_ · sched_ · erp_ · plm_ · qm_ · cmms_ · tool_ · wms_ · lims_ · ehs_ 로 시작하는 것)는 켤 수 없습니다 — 이 도구들은 디지털 스레드만 중계합니다.
  • 옛 판에서 코파일럿에 등록해 둔 외부 커넥터가 있었다면 재릴리즈(2026-10-20) 에서 그 기록이 지워집니다. 연동 지도에서 다시 등록하고 인증 값을 다시 넣으십시오 → 디지털 스레드

URL 로 받는 도구 — 내부 주소는 거절합니다​

문서 이해와 비전 도구는 파일을 받지 않고 URL 을 받습니다. 그 URL 은 AI 가 만든 문자열이라, 제한 없이 받아 오면 AI 가 컨테이너 안에서만 닿는 곳을 대신 읽어 줄 수 있습니다. 그래서 받는 입구에서 막습니다.

  • http · https 만 받습니다.
  • 주소가 루프백 · 사설망(10/8 · 172.16/12 · 192.168/16) · 링크로컬(클라우드 메타데이터 포함) 으로 풀리면 거절합니다. 리다이렉트도 한 번 넘어갈 때마다 다시 검사합니다.
  • 크기 상한 — 문서 200 MiB, 사진 32 MiB.

거절되면 도구가 ok: false 와 refused to fetch … 사유를 돌려줍니다.

사내 파일 서버의 URL 은 «허용 목록에 적어야» 읽힙니다

http://192.168.x.x/… 처럼 사내 주소에 있는 문서·사진은 기본으로 거절됩니다. 열어 줄 호스트를 /etc/kopens/plantpulse-ai.env 의 FETCH_ALLOWED_HOSTS(쉼표로 여럿, 기본 비어 있음)에 적으면, compose 가 문서 이해와 비전에 같이 넘깁니다(2026.10 재릴리즈부터).

  • URL 의 호스트 이름과 정확히 같아야 합니다(대소문자 무시). files.example.local:8080 처럼 포트를 붙이면 그 포트만 허용합니다. IP 로 부르는 서버는 IP 를 그대로 적습니다. 와일드카드 · 대역은 없습니다.
  • 허용한 호스트도 http · https 와 크기 상한은 그대로이고, 리다이렉트로 다른 내부 주소에 넘어가면 거기서 거절됩니다.
  • 적은 뒤 bin/restart.sh plantpulse-document-understanding-api plantpulse-vision-api 로 두 서비스를 다시 만듭니다.

→ 환경 변수 설정


이름 규칙​

뒷단 도구 이름은 snake_case 입니다(vision_read_meter). 접두어는 MCP 게이트웨이가 붙이므로, 서버 문서에서 본 이름(read_meter)과 채팅에서 부르는 이름(vision_read_meter)이 다를 수 있습니다.

  • 두 서버가 같은 노출 이름을 내면 먼저 등록된 쪽이 이기고 나중 것은 노출되지 않습니다(도구 화면에 충돌로 표시). 나중 서버의 접두사를 바꿔 풉니다.

🔴 도구 목록을 손으로 옮겨 적지 마십시오. 설치 상태(무엇이 켜져 있나)의 정본은 게이트웨이 DB 이고, 화면은 AI 관리 콘솔 › MCP 게이트웨이 › 도구, 전수는 게이트웨이 REST GET /api/v1/tools 입니다. 게이트웨이는 기동할 때와 5분마다 각 서버의 도구 목록을 다시 읽고, 서버 화면의 재발견으로 그 자리에서 다시 읽게 할 수도 있습니다.


반대 방향 — 코파일럿도 MCP 서버입니다​

여기까지는 코파일럿이 도구를 «쓰는» 이야기였습니다. 반대로 다른 AI 에이전트가 코파일럿을 도구로 쓸 수도 있습니다. 코파일럿이 자기 능력을 MCP 로 내주기 때문입니다.

항목값
엔드포인트POST /mcp (끝슬래시 /mcp/ 도 받습니다)
프로토콜JSON-RPC 2.0
인증/api/v1 과 같습니다 — X-API-Key 만(2026.10 재릴리즈 6 부터 로그인 세션은 403)
도구하는 일
ask_plant자연어 질문 → 답. 필요한 조회 도구는 코파일럿이 알아서 고릅니다, 근거가 함께 실립니다. 부른 API 키의 주체(그 키를 발급받은 사람)의 권한으로 묻고, sessionId 를 비우면 그 주체 소유로 새 대화를 엽니다
list_plant_tools코파일럿이 «지금» 닿을 수 있는 조회 도구 목록
daily_tasks아침 카드(KST 기준)
왜 셋뿐인가 — 읽기만 냅니다

바꾸는 도구에는 사람이 승인하는 절차가 붙어 있는데, MCP 로 부르는 쪽은 그 절차를 모릅니다. 그래서 조회만 내줍니다.

셋은 /api/v1 과 같은 기능이고 같은 구현에 위임합니다 — 같은 능력을 두 프로토콜로 내되 코드는 한 벌입니다. 두 벌이 되면 한쪽만 고쳐집니다.

끝슬래시를 둘 다 받습니다

/mcp 와 /mcp/ 가 모두 동작합니다. 클라이언트마다 어느 쪽을 부르는지가 달라 그 한 글자로 매 호출이 307 로 튕기는 일이 실제로 있었습니다. 우리를 부르는 쪽은 그 함정을 밟지 않습니다.


관련 문서​