호스트 백엔드가 AX Flow API GW 를 직접 호출하는 형태이다. 본 모드는 모드 (A) 의 FastMCP 도구를 FastAPI POST endpoint 로 1:1 자동 매핑한 결과이며, 도구 명세는 2.4 / 2.5 와 동일하다. 단 모든 FastMCP 도구가 REST 로 노출되는 것은 아니며(3.1 노출 컬럼 — 현재 retriever 는 MCP 전용), 또한 FastAPI 단독 정의 REST 라우트는 MCP 로 자동 노출되지 않는다(0.1 노출 방향성 참조).
3.1 엔드포인트 (REST)
MCP 도구 ↔ REST 엔드포인트 매핑은 다음과 같다. 노출 컬럼은 0.1 의 노출 방향성에 따른 도구별 인터페이스 가용 상태이다 (양쪽 = MCP+REST 동시 제공 / MCP 전용 = REST 미노출, wrapper route 협의 필요 / 예정 = 미구현 또는 PoC 단계 협의).
경로 규약 — 자동 매핑되는 REST 엔드포인트는 POST /mcpapi/rag/<tool_name>** 단일 패턴**이다 (모든 MCP 도구는 JSONRPC 의 POST 요청을 그대로 REST 로 노출하므로, GET/PATCH/DELETE 등 별도 HTTP 메서드는 사용하지 않는다). 식별자·필터·페이로드는 모두 JSON body 로 전달한다 (예: delete_document body 에 id). /mcpapi 는 백엔드 hardcoded, /rag 는 마운트 prefix (0.1).
| MCP 도구 | REST 엔드포인트 (모두 POST) | 노출 | 비고 |
|---|---|---|---|
retriever | - | MCP 전용 | 검색 — 6.2 출력 |
index_local_files | /mcpapi/rag/index_local_files | 양쪽 | 로컬 파일 인입 |
index_data_files | /mcpapi/rag/index_data_files | 양쪽 | 데이터 파일 인입 |
get_indexed_file | /mcpapi/rag/get_indexed_file | 양쪽 | 인입 파일 조회 (body: filename) |
get_rag_status | /mcpapi/rag/get_rag_status | 양쪽 | 인입 진행 상태 (body: data_uuid) |
delete_document | /mcpapi/rag/delete_document | 양쪽 | 문서 삭제 (body: id) |
get_document_metadata | /mcpapi/rag/get_document_metadata | 양쪽 | 문서 메타 조회 |
update_document_metadata | /mcpapi/rag/update_document_metadata | 양쪽 | 문서 메타 갱신 (body: doc_id, fields) |
get_graph_labels | /mcpapi/rag/get_graph_labels | 양쪽 | 노드 라벨 목록 |
get_knowledge_graph | /mcpapi/rag/get_knowledge_graph | 양쪽 | 그래프 구조 조회 |
get_document_graph | /mcpapi/rag/get_document_graph | 양쪽 | 문서별 그래프 (body: doc_id) |
search_graph_labels | /mcpapi/rag/search_graph_labels | 양쪽 | 라벨 퍼지 검색 |
get_entity | /mcpapi/rag/get_entity | 양쪽 | 단건 엔티티 (body: name) |
get_entity_edges | /mcpapi/rag/get_entity_edges | 양쪽 | 엔티티 엣지 (body: name) |
create_entity / edit_entity / delete_entity | /mcpapi/rag/create_entity · /edit_entity · /delete_entity | 양쪽 | 엔티티 편집 (각각 POST) |
merge_entities | /mcpapi/rag/merge_entities | 양쪽 | 별칭 통합 |
create_relation / edit_relation / delete_relation | /mcpapi/rag/create_relation · /edit_relation · /delete_relation | 양쪽 | 관계 편집 (각각 POST) |
get_section / edit_section / delete_section | /mcpapi/rag/get_section · /edit_section · /delete_section | 양쪽 | 섹션 편집 (각각 POST, body: section_id) |
위 표의 "양쪽" 행은 통합 시점의 /docs Swagger 와 /rag/mcp tools/list 양쪽에 동일 시그니처로 노출된다. 통합 검토 시 최종 노출 상태는 통합 시점의 /docs / tools/list 응답을 SoT 로 사용한다.
전체 24개 도구의 페이로드 단위 명세는 PoC 단계 별도 공유 (본문 3.1 매핑 표 + 6.2 응답 스키마 + 14.3 핵심 4개 도구 입출력 표로 PoC 통합 시작 가능).
3.2 인증
- OAuth 2.0 Client Credentials Grant — 모드 (A) 2.3과 동일 정책.
client_id/client_secret으로/api/v1/user/auth/token에서 발급받은access_token을Authorization: Bearer헤더로 전달 - 토큰 만료 시 — 동일 토큰 엔드포인트로 재발급
- 전송 — TLS 1.2+
3.3 호출 예시
# 1단계 — 토큰 발급
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단계 — REST 호출
# 주의: `/v1/retriever` 는 wrapper route 협의 후 활성 (3.1 노출 컬럼). 그 전까지는 10.3 MCP `tools/call` 로 동일 시그니처 호출.
curl -X POST https://<host>/mcpapi/rag/retriever \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"2026 1분기 마케팅 예산 결재선","mode":"deep","top_k":10}'3.4 Rate Limit / 페이지네이션
- Rate Limit — 테넌트 등급별 한도. 착수 단계에서 협의
- 페이지네이션 — cursor 기반 (
after,limit)