AX Flow SDK 명세서 v2.0 · 통합 파트너 검토용 — 정식 스키마는 /docs Swagger UI를 단일 기준으로 사용합니다.
Quickstart
5분 Quickstart

본 절은 도입사 개발자가 5분 안에 첫 응답을 검증하기 위한 step-by-step 가이드이다.

10.1 전제

항목발급 / 용도
client_id / client_secretAX Flow 콘솔에서 도입사 테넌트 등록 후 발급 (장기 credential)
access_token1단계 토큰 엔드포인트 호출로 발급 (short-lived)

10.2.1 curl 한 줄로 첫 응답

# 1단계 — 토큰 발급 (OAuth 2.0 Client Credentials Grant)
ACCESS_TOKEN=$(curl -s -X POST https://<host>/api/v1/user/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=host-agent&client_secret=<client-secret>&scope=rag:read rag:write" \
  | jq -r '.access_token')
 
# 2단계 — MCP 도구 호출 (via REST API)
curl -X POST https://<host>/mcpapi/rag/retriever \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "2026년 1분기 마케팅 예산 결재선",
    "mode": "smart",
    "top_k": 10
  }'

10.2.2 curl + JSONRPC

이 경우 JSONRPC로 SESSION 정보를 얻은 후에 mcp를 다시 호출함

out=$(curl -X POST https://<host>/rag/mcp \
 -H "accept: application/json, text/event-stream" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "content-type: application/json" \
 -d '{
   "jsonrpc": "2.0",
   "method": "initialize",
   "params": {
     "protocolVersion": "2024-11-05",
     "capabilities": {},
     "clientInfo": { "name": "curl-client", "version": "1.0.0" }
   },
   "id": 1
}' -i 2>/dev/null)
 
echo "$out"
 
sess=$(echo "$out" |grep mcp-session-id | cut -d: -f2 | sed 's/ //g')
 
echo "export SESSION=$sess"
# 위의 출력된 내용을 export SESSION=XXXXXXX 식으로 쉘에서 실행한 후에 다음 실행.
#!/bin/sh
 
curl -X POST https://<host>/rag/mcp \
 -H "accept: application/json, text/event-stream" \
 -H "content-type: application/json" \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Mcp-Session-Id: $SESSION" \
 -d '{
   "jsonrpc": "2.0",
   "method": "tools/call",
   "params": {
     "name": "retriever",
     "arguments": { "query": "2026년 1분기 마케팅 예산 결재선", "mode": "smart", "top_k": 10 }
   },
   "id": 4
}'

10.3 Python MCP 클라이언트로 첫 응답

import asyncio
from contextlib import AsyncExitStack
 
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client as mcp_client
 
async def main():
    async with AsyncExitStack() as stack:
        http_client = await stack.enter_async_context(
            httpx.AsyncClient(base_url="https://<host>", timeout=None, follow_redirects=True),
        )
 
        # 1단계 — Client Credentials Grant 으로 access_token 발급
        token_resp = await http_client.post(
            "/api/v1/user/auth/token",
            data={
                "grant_type": "client_credentials",
                "client_id": "host-agent",
                "client_secret": "<client-secret>",
            },
            headers={"Content-Type": "application/x-www-form-urlencoded"},
        )
        token_resp.raise_for_status()
        access_token = token_resp.json()["access_token"]   # "lba.<...>"
        http_client.headers["Authorization"] = f"Bearer {access_token}"
        # 옵션: 서비스 키가 별도 발급된 경우
        # http_client.headers["X-MCP-API-Key"] = "<mcp-api-key>"
 
        # 2단계 — MCP 세션 수립 (streamable-http transport)
        read, write, _ = await stack.enter_async_context(
            mcp_client("https://<host>/rag/mcp", http_client=http_client),
        )
        session = await stack.enter_async_context(ClientSession(read, write))
        await asyncio.wait_for(session.initialize(), timeout=15.0)
 
        # 3단계 — retriever 호출 (인자는 dict 로 전달)
        result = await asyncio.wait_for(
            session.call_tool("retriever", {
                "query": "2026년 1분기 마케팅 예산 결재선",
                "mode": "smart",
                "top_k": 10,
            }),
            timeout=120.0,
        )
 
        for content in result.content:
            if content.type == "text":
                print(content.text)
 
asyncio.run(main())

10.4 첫 응답 검증 체크

항목정상비정상 → 16. 트러블슈팅
응답 200401 / 403 → 16.1
content 비어있지 않음비어있음 → 16.2
metadata.references[] 1건 이상0건 → 16.2 / 16.4
latency 기준치 (Smart ~0.9s / Deep ~3.2s) 부근큰 폭 초과 → 17.1