본 절은 도입사 개발자가 5분 안에 첫 응답을 검증하기 위한 step-by-step 가이드이다.
10.1 전제
| 항목 | 발급 / 용도 |
|---|---|
client_id / client_secret | AX Flow 콘솔에서 도입사 테넌트 등록 후 발급 (장기 credential) |
access_token | 1단계 토큰 엔드포인트 호출로 발급 (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. 트러블슈팅 |
|---|---|---|
| 응답 200 | ✓ | 401 / 403 → 16.1 |
content 비어있지 않음 | ✓ | 비어있음 → 16.2 |
metadata.references[] 1건 이상 | ✓ | 0건 → 16.2 / 16.4 |
latency 기준치 (Smart ~0.9s / Deep ~3.2s) 부근 | ✓ | 큰 폭 초과 → 17.1 |