Skip to main content
Glama

K-AIR MCP

에이전트가 데이터허브 조회만 하도록 여는 공식 MCP 서버입니다. 카탈로그 서빙 및 질의 실행은 robo-meta-api와 연계하여 동작하며, 특정 물리 DB에 종속되지 않습니다. SQL 문자열은 직접 받지 않습니다.

도구 인자로 SELECT를 조립한 뒤 robo-meta-api POST /query_execute로 실행합니다. 에이전트에 자유 SQL 문자열 도구는 없습니다.

업데이트 이력: change_log.md

최근 변경 (2026-09-05)

  • 죽은 물리 DB 경로 제거. pg_store·tb_store, MCP_PG_*/MCP_TB_*, JDBC/JRE/psycopg를 삭제했다. 허용 표는 POST /meta/catalog만 본다.

  • 조회 표면. list_tables/describe_table이 논리명·설명을 주고, 카탈로그는 45초 캐시한다. /health에 robo_catalog probe가 있다.

  • 고유값. DISTINCT 별칭은 distinct_value다. IS NOT NULL/ORDER BY를 붙이지 않는다.

  • 상세는 change_log.md 2026-09-05.

Related MCP server: Governor SQL MCP

이 서비스가 하는 일

  • 에이전트에 표 목록·컬럼 상세·고유값·제한 SELECT·집계 도구를 줍니다.

  • 허용 표 = POST /meta/catalog에 등록된 표·컬럼 (단일 진실 공급원).

  • HTTP는 Streamable HTTP(/mcp) + X-Api-Key. stdio는 같은 PC IDE용입니다.

  • AI는 MCP URL과 API Key만 압니다. DB 비밀번호는 필요하지 않으며 도구 결과에도 없습니다.

하지 않는 일: 자유 SQL, DML/DDL, dump/보내기, t2s·argus_catalog 데이터 조회, 특정 물리 DB 직접 커넥션 요구.

도구

도구

역할

list_tables

허용 표 목록. 물리 3키와 논리명·설명. 선택 schema_name. 응답에 engine

describe_table

표 논리명·설명, 컬럼 타입·PK·논리명·코멘트. 카탈로그 한 번만 읽음

get_distinct_values

허용 컬럼 DISTINCT. 별칭 distinct_value. 상한은 MCP_ROW_LIMIT

query_table

조립 SELECT. columns, filters {column,op,value}, order_by {column,dir}

aggregate_table

count/sum/avg/max/min. 선택 filters {column,op,value}. 전체 행 수는 func=count 그리고 column 없음

행 상한은 MCP_ROW_LIMIT(기본 200). 실행 SELECT는 POST /query_execute. filters.op: eq, ne, gt, gte, lt, lte, like, in, is_null, is_not_null.

데이터소스 구분

/meta/catalog의 sources[].engine이 정본입니다. 에이전트가 엔진을 고르지 않습니다. 플랫폼에 등록된 Postgres, Tibero 등 모든 데이터소스가 카탈로그를 통해 균일하게 서빙됩니다.

허용 표는 카탈로그에 등록된 표·컬럼입니다. MCP가 물리 DB에 직접 붙어 실존 여부를 재확인하지 않습니다. 실행은 robo-meta-api POST /query_execute입니다.

구성

app/                 FastMCP 서버 (stdio / Streamable HTTP)
tests/               단위·계약 테스트
docker-compose.yml   네트워크용 http :8110
mcp.cursor.example.json       같은 PC stdio
mcp.cursor.http.example.json  다른 PC HTTP

전제: robo-meta-api와 kair-metadata-platform_control-plane 네트워크. 필수 설정은 MCP_API_KEYS와 ROBO_META_URL. 포털·OASIS는 이 저장소 범위가 아닙니다.

실행

copy .env.example .env
# MCP_API_KEYS 필수. 따옴표 넣지 않음
docker compose up -d --build
curl.exe -fsS http://127.0.0.1:8110/health

헬스 본문은 backend=robo-meta-api와 robo_catalog(ok/unreachable)입니다. 물리 엔진 목록을 넣지 않습니다.

같은 PC CLI(stdio, 기본):

python -m app.main

컨테이너 HTTP:

python -m app.main --transport http

MCP 등록

같은 PC(권장 stdio). 컨테이너가 떠 있어야 합니다. URL·키·.env를 넣지 않습니다.

{
  "mcpServers": {
    "kair-query": {
      "command": "docker",
      "args": ["exec", "-i", "kair-mcp-query", "python", "-m", "app.main", "--transport", "stdio"]
    }
  }
}

다른 PC(Streamable HTTP). DB 비밀번호는 넣지 않습니다.

{
  "mcpServers": {
    "kair-query": {
      "url": "http://<MCP띄운PC의IP>:8110/mcp",
      "headers": {
        "X-Api-Key": "<MCP_API_KEYS 값만>"
      }
    }
  }
}

mcp.json은 JSON이라 키를 "…"로 감쌉니다. 서버가 받는 값은 따옴표 없는 키입니다.

설정

.env.example을 Git에서 제외된 .env로 복사합니다. 비밀번호·API Key는 코드와 Git 추적 문서에 저장하지 않습니다.

변수

역할

MCP_API_KEYS

HTTP X-Api-Key. 로컬 스모크 키. 포털 dh_·tm_po_api_key가 아님

ROBO_META_URL

POST /meta/catalog와 POST /query_execute 공통. 기본 http://robo-meta-api:8100

MCP_ROW_LIMIT

행 상한. env 값을 그대로 씀

API_HOST / API_PORT

HTTP 바인드. 기본 0.0.0.0:8110

접속 정본은 플랫폼 Serving과 robo-meta-api입니다. MCP에 DB 비밀번호를 넣지 않습니다.

테스트

python -m pytest tests -q

알려진 이슈·한계

항목

설명

상태

실행면

행·집계·고유값은 /query_execute

카탈로그에 있는 표만 조립 SELECT

포털 키·감사

tm_po_api_key / th_po_api_call / 등급·활용신청

미구현. 로컬 키는 폐기 대상

자유 SQL

Gemini 피드백의 execute_read_only_sql

넣지 않음

행 상한 1000

Gemini 피드백

하드캡 200 해제. MCP_ROW_LIMIT를 따름

관련

데이터허브 조회 셋: 플랫폼(메타 적재·Serving) → robo-meta-api(카탈로그·실행 API) → 이 MCP(에이전트 도구). 메타스토어 DSN·MindsDB 접속은 MCP에 없다. ROBO_META_URL(http://robo-meta-api:8100)만 본다.

  • robo-meta-api — POST /meta/catalog, POST /query_execute

  • K-AIR-metadata-platform — Serving t2s_*

  • K-AIR-Portal — 이후 정본 창구 POST /api/v1/mcp, 키 원장

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to inspect schemas, walk Delta table history, run read-only DuckDB queries, and check data-quality and job-run status safely.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to safely query SQL databases through read-only tools for describing entities, reading records, and aggregating records, with view-based access and fail-closed per-user row-level security.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to query Postgres, BigQuery and DuckDB read-only through policy-checked SQL, with AST-based guards that refuse writes and dangerous functions, column masking on the way out, and an audit log of every query. Also exposes schema browsing and query-planning tools so agents can see allowed tables, columns and costs before running anything.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to inspect database schemas and run strictly read-only SQL queries with guardrails against destructive statements, multi-statement chaining, and unbounded scans. Supports SQLite natively and PostgreSQL optionally.
      4
      84 PyPI
      MIT