MCP 서버 (AI 어시스턴트 연동)

엣지 박스 자체가 MCP 서버입니다. Claude 같은 AI 어시스턴트가 현장의 박스에 직접 물어봅니다 — OPC 연결이 몇 개인지, 이 태그의 지금 값이 얼마인지, 수집이 밀리고 있는지.

플랫폼을 거치지 않습니다. 박스가 플랫폼과 끊겨 있어도, 박스에 닿을 수만 있으면 답합니다.

항목	값
엔드포인트	`POST https://<엣지>/api/v1/mcp`
전송	Streamable HTTP, stateless
서버 이름	`plantpulse-edge` (버전은 박스의 것을 그대로 알립니다)
제공	도구 6종 — 전부 읽기
인증	`/api/` 와 같은 API 키.* MCP 전용 인증은 없습니다

붙이는 법

# Claude Code
claude mcp add --transport http plantpulse-edge "https://<엣지>/api/v1/mcp" \
  --header "X-API-Key: <edge.rest.api.key>"

// Claude Desktop — .mcp.json
{
  "mcpServers": {
    "plantpulse-edge": {
      "type": "http",
      "url": "https://<엣지>/api/v1/mcp",
      "headers": { "X-API-Key": "<edge.rest.api.key>" }
    }
  }
}

X-API-Key 대신 Authorization: Bearer <키> 도 됩니다. 키는 REST API 와 같은 값(edge.rest.api.key)입니다 — REST API 를 보십시오.

🔴 http:// 로 붙으면 403 입니다 — 키가 맞아도 거부됩니다

edge.rest.api.https_only 의 기본값이 true 라, 외부 클라이언트(X-API-Key·Bearer) 호출은 반드시 HTTPS 여야 합니다. 평문으로 오면 키를 보기도 전에 403 HTTPS_REQUIRED 로 끊습니다.

리버스 프록시 뒤라면 X-Forwarded-Proto: https 도 인정합니다. 연결이 거부되면 키부터 의심하지 마시고 스킴을 먼저 보십시오 — 401 이 아니라 403 이면 이 경우입니다.

키가 비어 있으면 /api/* 전체가 500 입니다

edge.rest.api.auth 는 기본 true(fail-closed)이고, 이때 edge.rest.api.key 가 비어 있으면 박스는 모든 /api/* 요청을 500 MISCONFIGURED 로 막습니다. 「설정이 없으면 허용」이 아니라 「설정이 없으면 차단」입니다 — 설정 파일이 유실된 박스가 무인증으로 열리는 것을 막기 위한 의도된 동작입니다.

브라우저로 콘솔에 로그인해 두었다면 키 없이도 됩니다

같은 도메인의 /ui/* 화면이 부르는 /api/* 는 이미 로그인된 세션이라 통과합니다. API 키는 외부 호출(REST 클라이언트 · Node-RED · MCP)을 지키는 장치입니다.

도구 6종 — 전부 읽기

도구	하는 일	필수 인자
`list_opcs`	이 박스에 설정된 OPC 연결 목록	—
`get_opc`	OPC 연결 하나를 id 로 조회	`opcId`
`list_tags`	한 OPC 연결의 태그 목록	`opcId`
`get_tag_value`	태그 하나의 지금 값 — 캐시가 아니라 장치에서 새로 읽습니다	`tagId`
`get_monitoring`	이 박스의 수집 파이프라인 건강 상태	—
`get_transfer_status`	플랫폼으로의 store-and-forward 전송 상태	—

도구가 새 코드가 아닙니다. AI 채팅이 쓰는 바로 그 서비스(ConnectService · MonitoringQueryService)를 그대로 부릅니다 — 같은 질문에 두 경로가 다르게 답하는 것을 피하려는 것입니다.

🔴 PLC 를 움직이는 도구는 일부러 없습니다

엣지의 도구 집합에는 start_opc · stop_opc · write_tag 도 있습니다. MCP 에는 열려 있지 않습니다.

채팅 경로에서 그 셋은 사람의 승인 화면(/ui/ai/approve)을 지납니다. MCP 클라이언트는 그 화면을 지나지 않습니다. 그리고 write_tag 는 PLC 에 씁니다 — 물리적인 것이 움직입니다. 승인이 없는 경로가 거기 닿으면 안 됩니다.

나중에 쓰기 도구가 정말 필요해지면 승인을 MCP 안으로 먼저 옮기고 그 다음에 엽니다. 도구를 먼저 추가하는 것은 안전장치를 우회하는 가장 쉬운 길입니다. 제품에는 이것을 지키는 회귀 테스트가 있습니다.

왜 stateless 인가

현장 박스에 맞는 모양이라서입니다. 세션을 쓰는 전송은 서버가 세션별 상태를 들고 있어야 하는데, 현장 회선은 끊겼다 붙는 것이 일상이고 그때마다 클라이언트를 알아보고 이어 붙여야 합니다. 박스가 재기동하면 모든 세션이 한꺼번에 사라집니다.

stateless 는 요청 하나하나를 따로 봅니다 — 이어 붙일 것도, 잃을 것도 없고, 힙 2GB 짜리 장치에 세션 표가 자라지 않습니다.

잘 붙었는지 보기

tools/list 가 6종을 돌려주는지 보십시오.

도구 목록이 «비어 있는데» 서버는 멀쩡해 보일 수 있습니다

도구 스캔이 아무것도 못 찾아도 MCP 서버는 정상적으로 뜹니다 — 빈 tools/list 를 알릴 뿐입니다. 클라이언트는 그것을 「이 엣지에는 도구가 없구나」와 구별하지 못합니다. 배선이 끊긴 것이 제품의 사실처럼 읽힙니다.

그래서 박스는 그 상태를 로그에 ERROR 로 크게 남깁니다. 목록이 비면 엣지 로그에서 MCP tool scan produced NO tools 를 찾으십시오.

함께 보기

REST API (v1) · 플랫폼 MCP 서버 — 플랫폼 쪽은 도구 22종이고 자산·알람·온톨로지까지 봅니다

붙이는 법​

도구 6종 — 전부 읽기​

🔴 PLC 를 움직이는 도구는 일부러 없습니다​

왜 stateless 인가​

잘 붙었는지 보기​

함께 보기​