API Integration Guide

This guide describes how to call PlantPulse AI's MCP and APIs directly from external systems.

warning

2026-07 revision: MCP and ontology tools are now provided by the PlantPulse platform's server-web integrated MCP (/api/v5/mcp, api_key authentication). The former standalone services MCP Server (:50000) and Ontology (:8888) have been archived, and RAG has been replaced by the LightRAG server.

API Endpoint List

Service	URL	Protocol	Authentication
Integrated MCP (Platform)	`<platform>/api/v5/mcp`	MCP (JSON-RPC 2.0)	api_key (`Authorization: Bearer`)
TimeSeries	`http://<server>:8970`	MCP (JSON-RPC 2.0) / REST	Internal network
RAG (LightRAG)	`http://<server>:7114`	REST + WebUI (`/webui`)	X-API-Key
LiteLLM (LLM)	`http://<server>:4000`	OpenAI-compatible	API Key

Calling the MCP Protocol

The integrated MCP and TimeSeries-Insight follow the MCP (Model Context Protocol) standard. Factory data and ontology tools are called through the platform's integrated MCP endpoint (/api/v5/mcp).

Basic MCP Structure

MCP uses HTTP POST communication based on JSON-RPC 2.0. The integrated MCP requires api_key authentication (Authorization: Bearer <token>).

POST /api/v5/mcp HTTP/1.1
Content-Type: application/json
Authorization: Bearer <mcp.api.token>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool-name>",
    "arguments": {
      "<param1>": "<value1>",
      "<param2>": "<value2>"
    }
  }
}

Listing Tools

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Tool Call Examples

Retrieving the Site List

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_site_list",
      "arguments": {}
    }
  }'

Searching Equipment

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_asset_search",
      "arguments": {
        "keyword": "DJ",
        "page": 1,
        "size": 10
      }
    }
  }'

Retrieving the Latest Sensor Value

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "api_read_point_latest",
      "arguments": {
        "tag_id": "TAG_DJ_M_01_1_1093"
      }
    }
  }'

Integrated MCP Authentication

The integrated MCP requires api_key authentication. Tokens are managed in AI Chat Web under web/config/application.properties (mcp.api.url/mcp.api.token).

Authentication Header

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{ ... }'

Calling the Ontology (Knowledge Graph)

Ontology tools have been merged into the integrated MCP. Call the ontology_* tools through the integrated MCP endpoint.

Retrieving Graph Statistics

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ontology_get_stats",
      "arguments": {}
    }
  }'

Exploring a Subgraph

curl -X POST <platform>/api/v5/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <mcp.api.token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ontology_get_subgraph",
      "arguments": {
        "label": "Equipment",
        "id": "ASSET_DJ_M_01_1",
        "depth": 2
      }
    }
  }'

Calling the TimeSeries MCP

Equipment Anomaly Detection

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "detect_asset_anomaly",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1",
        "lookback_minutes": 1440,
        "threshold": 0,
        "top_k": 5
      }
    }
  }'

Equipment Sensor Prediction

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "forecast_asset",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1",
        "prediction_length": 96,
        "enable_bounds": true
      }
    }
  }'

Equipment Health Score

curl -X POST http://127.0.0.1:8970/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_asset_health",
      "arguments": {
        "asset_id": "ASSET_DJ_M_01_1"
      }
    }
  }'

Calling RAG (LightRAG)

The RAG engine is the LightRAG 1.5.4 server. Document upload, listing, deletion, and other management tasks are performed in the WebUI (http://<server>:7114/webui), while searches are called via the REST /query (X-API-Key authentication).

info

The agent built into AI Chat Web queries LightRAG automatically through the rag_search tool, with no separate call required. The examples below are for calling it directly from outside; refer to the official LightRAG documentation for detailed schemas.

Text Search

curl -X POST http://127.0.0.1:7114/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <rag.api.key>" \
  -d '{
    "query": "펌프 정비 절차",
    "mode": "hybrid"
  }'

Supported search modes are hybrid (default), naive, local, and global.

Calling the LLM API (OpenAI-Compatible)

The LiteLLM proxy provides an OpenAI-compatible API. You can use the existing OpenAI SDK as-is.

Chat Completion

curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 설치-시-변경" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "주입기 베어링 교체 주기를 알려줘."}
    ],
    "temperature": 0.7
  }'

Generating Embeddings

curl http://127.0.0.1:4000/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 설치-시-변경" \
  -d '{
    "model": "text-embedding-3-large",
    "input": "주입기 베어링 교체 절차"
  }'

Checking the Model List

curl http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer 설치-시-변경"

Available Models

Model Name	Purpose	Description
`gpt-4o`	LLM (conversation/analysis)	AURA LLM main model
`gpt-4o-mini`	VLM (vision)	AURA vision model
`text-embedding-3-large`	Embedding	Generates 2560-dimensional vectors
`rerank-multilingual-v3.0`	Reranking	Reranks search results

info

Model names are set to values such as gpt-4o for OpenAI compatibility, but the actual models used are on-premises AURA models (served via vLLM).

Python SDK Examples

Calling the LLM with the OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:4000/v1",
    api_key="설치-시-변경"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "주입기 상태를 분석해줘."}
    ]
)

print(response.choices[0].message.content)

Calling MCP Tools

import requests

def call_mcp_tool(url, tool_name, arguments=None, headers=None):
    response = requests.post(
        url,
        headers=headers or {},
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": tool_name,
                "arguments": arguments or {}
            }
        }
    )
    return response.json()

# 사이트 목록 조회 (통합 MCP — api_key 필요)
result = call_mcp_tool(
    "<platform>/api/v5/mcp",
    "api_read_site_list",
    headers={"Authorization": "Bearer <mcp.api.token>"}
)
print(result)

# 설비 이상 탐지 (TimeSeries-Insight)
result = call_mcp_tool("http://127.0.0.1:8970/mcp", "detect_asset_anomaly", {
    "asset_id": "ASSET_DJ_M_01_1",
    "lookback_minutes": 1440,
    "threshold": 0
})
print(result)

Response Formats

MCP Success Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... 도구 실행 결과 JSON ... }"
      }
    ]
  }
}

MCP Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": "상세 오류 메시지"
  }
}

Pagination

Use pagination when retrieving large volumes of data.

{
  "name": "api_read_asset_search",
  "arguments": {
    "keyword": "DJ",
    "page": 1,
    "size": 10
  }
}

Parameter	Description	Default	Maximum
`page`	Page number	1	-
`size`	Items per page	10	50
`limit`	General query limit	10	100

Time Format

Time-related parameters in the integrated MCP are based on KST (Korea Standard Time).

{
  "name": "api_read_point_range",
  "arguments": {
    "tag_id": "TAG_DJ_M_01_1_1093",
    "start_time": "2026-03-29T00:00:00",
    "end_time": "2026-03-29T23:59:59"
  }
}

In responses, fields with the _iso suffix are in human-readable KST format:

{
  "timestamp": 1711641600000,
  "timestamp_iso": "2026-03-29 09:00:00"
}

API Endpoint List​

Calling the MCP Protocol​

Basic MCP Structure​

Listing Tools​

Tool Call Examples​

Retrieving the Site List​

Searching Equipment​

Retrieving the Latest Sensor Value​

Integrated MCP Authentication​

Authentication Header​

Calling the Ontology (Knowledge Graph)​

Retrieving Graph Statistics​

Exploring a Subgraph​

Calling the TimeSeries MCP​

Equipment Anomaly Detection​

Equipment Sensor Prediction​

Equipment Health Score​

Calling RAG (LightRAG)​

Text Search​

Calling the LLM API (OpenAI-Compatible)​

Chat Completion​

Generating Embeddings​

Checking the Model List​

Available Models​

Python SDK Examples​

Calling the LLM with the OpenAI SDK​

Calling MCP Tools​

Response Formats​

MCP Success Response​

MCP Error Response​

Pagination​

Time Format​