모드 A · MCP 서브에이전트

호스트 앱(도입사) 변경을 최소화하는 통합이다. AX Flow의 설계 원칙은 "특정 앱 안에 갇힌 지식이 아니라, 어떤 에이전트가 와도 같은 인터페이스로 읽을 수 있는 지식층"이며, 본 모드가 그 원칙에 가장 직접적으로 부합한다.

2.1 아키텍처

┌───────────────────────┐                  ┌───────────────────────┐
│  Host App     │   MCP            │  AX Flow MCP Server   │
│  (LLM / 에이전트)      │  (streamable_   │   • OAuth 2.0 CC      │
│                       │   http, JSONPRC) │   • Retriever Tool    │
│  사용자 질의           │ ───────────────▶ │   • 인입 / 운영 도구   │
└───────────────────────┘                  └───────────┬───────────┘
                                                       │
                                                       ▼
                                          ┌───────────────────────┐
                                          │  그래프 저장소         │
                                          │  벡터 저장소           │
                                          │  로컬 임베딩          │
                                          │  사내 LLM 서빙        │
                                          └───────────────────────┘

2.2 연결 설정

표준 MCP 클라이언트가 streamable_http 트랜스포트로 본 서버에 연결한다. 인증은 2.3의 OAuth 2.0 Client Credentials Grant 흐름으로 발급된 access_token을 Authorization: Bearer 헤더로 전달한다. 예를 들어서 /rag 로 마운트된 rag mcp는 다음과 같이 클라이언트 측에서 설정을 한다.

{
  "mcpServers": {
    "axflow": {
      "transport": "streamable_http",
      "url": "https://<host>/rag/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

2.3 인증 — OAuth 2.0 Client Credentials Grant

본 서버는 OAuth 2.0 Client Credentials Grant 흐름을 정식 인증 방식으로 사용한다. 도입사 측은 발급받은 client_id / client_secret으로 토큰 엔드포인트에서 short-lived access_token을 받아 MCP 호출 시 Authorization: Bearer 헤더로 전달한다. 1단계 — 토큰 발급

POST /api/v1/user/auth/token
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials
&client_id=<client-id>
&client_secret=<client-secret>
&scope=rag:read rag:write

응답:

{
  "access_token": "<access_token>", # lba.xxx
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "rag:read rag:write"
}

2단계 — MCP 호출 헤더

헤더	값
`Authorization`	`Bearer <access_token>`

Credential 발급 / 정책

항목	발급 / 정책
`client_id` / `client_secret`	AX Flow 콘솔에서 도입사 테넌트별 발급. 장기 credential — 토큰 발급 전용
`access_token`	short-lived (기본 만료 `expires_in` 초). 만료 시 토큰 엔드포인트에서 재발급

Claims	`access_token` claims에 user / service workspace / scope 포함. 서비스는 사용자 식별자 기반으로 RBAC 매핑
인증 주체	client credential은 내부 사용자 또는 service account에 매핑 — M2M 통합은 service account, end-user-facing 통합은 사용자 매핑

기본 사용자 인증 (옵션) — End-user가 브라우저로 직접 인증하는 시나리오에서는 표준 OAuth 사용자 로그인으로 발급된 Authorization: Bearer <user_access_token>을 직접 사용할 수 있다. 호스트 자동화 / M2M 통합에서는 OAuth2 Client Credentials Grant(M2M)가 권장 흐름이다.

2.4 핵심 도구 — retriever

검색은 retriever 도구 단일 진입점으로 노출된다.

파라미터	타입	기본값	설명
`query`	string	(필수)	자연어 질의
`mode`	enum	`smart`	검색 모드: `smart` / `deep`
`top_k`	int	10	그래프 엔티티/관계 최대 수
`collection_list`	string[] \	null	null
`filter_metadata`	object \	null	null
`engine_slug`	string	`default`	RAG 엔진 식별자 (다중 엔진 운영 시 선택)
`response_format`	enum	`text`	응답 형태 — `text` (마크다운 4섹션 단일 문자열, 기본) / `json` (`entities` / `relationships` / `chunks` / `references` 4섹션 dict). 도입사 UI 가 섹션별 렌더링을 직접 제어할 경우 `json` 권장
`score_threshold`	float \	null	null

mode 의미 (호스트 UI 토글과 직접 대응)

⚡ smart (기본) — 가장 빠른 엔진 우선, 균형 모드. 평균 응답 ~0.9초. 일반 질의·일상 화면 권장
🧠 deep — 합성 + 재정렬, 정밀도 우선. 평균 응답 ~3.2초. 계약·SOP·규제 등 근거 정밀도가 필요한 질의 권장 서버 내부에서는 본 두 모드를 검색 엔진별 정책으로 라우팅한다 — 호출자는 smart / deep만 결정하면 된다.

2.5 보조 도구 (개요)

retriever 외에 인입·문서 운영·그래프 조회·엔티티·관계·섹션 도구가 함께 노출된다 (전체 23개 도구의 시그니처·응답 스키마는 PoC 단계 별도 공유 — 핵심 4개 도구는 14.3에 입출력 명세 표 노출).

도구군	대표 도구	용도
인입 (4)	`index_local_files`, `index_data_files`, `get_indexed_file`, `get_rag_status`	파일 인입 + 진행 상태
문서 운영 (3)	`delete_document`, `get_document_metadata`, `update_document_metadata`	문서 삭제·메타
그래프 조회 (4)	`get_graph_labels`, `get_knowledge_graph`, `get_document_graph`, `search_graph_labels`	노드·엣지·라벨 조회
엔티티 운영 (6)	`get_entity`, `get_entity_edges`, `create_entity`, `edit_entity`, `delete_entity`, `merge_entities`	엔티티 별칭 통합·편집
관계 운영 (3)	`create_relation`, `edit_relation`, `delete_relation`	엔티티 간 관계 편집
섹션 운영 (3)	`get_section`, `edit_section`, `delete_section`	섹션 단위 편집

2.6 호출 예시 — Python (개념)

# 개념 예시. 실제 라이브러리는 표준 MCP 클라이언트 SDK를 사용한다.
import httpx
from mcp_client import Client
 
# 1단계 — Client Credentials Grant 으로 access_token 발급
token_resp = httpx.post(
    "https://<host>/api/v1/user/auth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": "host-agent",
        "client_secret": "<client-secret>",
        "scope": "rag:read rag:write",
    },
)
token_resp.raise_for_status()
access_token = token_resp.json()["access_token"]   # "lba.<...>"
 
# 2단계 — MCP 호출 (Authorization: Bearer 한 줄)
client = Client(
    server="https://<host>/rag/mcp",
    transport="streamable_http",
    headers={
        "Authorization": f"Bearer {access_token}",
    },
)
result = client.call_tool(
    "retriever",
    query="2026년 1분기 마케팅 예산 결재선",
    mode="deep",      # smart | deep
    top_k=10,
)
print(result["content"])         # 답변·컨텍스트
print(result["metadata"])        # references[]
print(result["score"])           # 청크별 점수
print(result["latency"])         # 검색 지연 (초)

2.7 권한 모델

ORM 레이어 RBAC가 응답 합성 전 단계에서 권한 없는 노드를 컨텍스트에 진입시키지 않는다. 노드 단위 4단계 — public / team / private / device-only — 가 호출자(호스트 사용자) 권한과 매칭되어 통과한 노드만 응답에 포함된다. 사용자 권한은 2.3 OAuth access_token claims의 사용자 식별자를 통해 매핑된다.

모드 개요 B · REST API