K-AIR MCP

An official MCP server that opens only for agents to query the data hub. There is a single entry point, and the catalog source engine internally distinguishes between Postgres (analytics mart) and Tibero (collection). SQL strings are not accepted.

The role is similar to robo-meta-api's T2SQL and query_execute, but the server does not generate SQL; it assembles SELECT statements from tool arguments. It does not replicate the portal POST /mcp mockup as the canonical version.

Update history: change_log.md

What this service does

• Provides agents with table lists, column details, distinct values, limited SELECT, and aggregation tools.

• Allowed tables = POST /meta/catalog ∩ tables and columns that actually exist in the corresponding engine source.

• HTTP uses Streamable HTTP (/mcp) + X-Api-Key. stdio is for same-PC IDEs.

• AI only knows the MCP URL and API Key. DB passwords and robo addresses are not present in tool results.

What it does not do: free SQL, DML/DDL, dump/send, operational Tibero, querying t2s·argus_catalog data, or splitting MCP per engine.

Related MCP server: SQLite Read-Only MCP Server

Tools

Row limit 200. Read-only (default_transaction_read_only), statement_timeout 15 seconds. filters.op: eq, ne, gt, gte, lt, lte, like, in, is_null, is_not_null.

Engine distinction

sources[].engine in /meta/catalog is the canonical source. Agents do not choose the engine.

If the engine is missing or unknown, it is excluded from the list. Even if a Tibero table has the same name as an existing Postgres table, they are not mixed.

Locally, only Postgres is available. If there is no Tibero connection or JDBC, catalog Tibero sources do not appear in the list. JDBC JARs are not included in the image.

Configuration

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

Prerequisites: robo-meta-api and kair-metadata-platform_control-plane network. The data side is local kair-postgis-16 (host 5434). The portal, OASIS, and operational Tibero are outside the scope of this repository.

Execution

copy .env.example .env
# MCP_API_KEYS · MCP_PG_* 실제 값만 채움. 따옴표 넣지 않음
docker compose up -d --build
curl.exe -fsS http://127.0.0.1:8110/health

Health: {"status":"ok","server":"kair-mcp-query","transport":"streamable-http","engines":["postgres"]}

Same-PC CLI (stdio, default):

python -m app.main

Container HTTP:

python -m app.main --transport http

MCP registration

Same PC (stdio recommended). The container must be running. URL, key, and .env are not included.

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

Another PC (Streamable HTTP). DB passwords are not included.

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

mcp.json is JSON, so keys are wrapped in "…". The values the server receives are keys without quotes.

Settings

Copy .env.example to .env, which is excluded from Git. Passwords and API keys are not stored in code or Git-tracked documents.

The connection canonical source is SourceDbConn in OA. Locally it is env/CLI.

Tests

python -m pytest tests -q

Known issues and limitations

Related

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

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

• K-AIR-Portal — Future canonical entry point POST /api/v1/mcp, key ledger