본 문서는 통합 파트너 사전 미팅에서 요청 주신 "가져다 쓸 수 있는 형태(라이브러리/SDK/API/서비스)"에 대한 단일 명세이다. 통합 파트너 개발팀이 통합 모드를 짧은 시간 안에 비교·선택할 수 있도록 매트릭스를 우선 노출하고, 모드별 인터페이스·인증·예시를 그 뒤에 둔다.
경로 prefix 설정 가능성 — /mcpapi 는 백엔드 hardcoded prefix (REST 노출 네임스페이스). /rag 는 FastMCP 서버 마운트 시 옵션으로 결정되는 prefix 이며, 마운트 옵션 변경 시 다른 이름 가능 (예: /raganything → MCP 진입점 /raganything/mcp + REST /mcpapi/raganything/<tool_name>). 본 문서는 현행 /rag 마운트 기준으로 기재한다.
0.1 SDK 문서 원본 (SSOT) — FastMCP 도구 정의 → FastAPI 1:1 자동 라우팅 (단방향)
본 SDK 명세는 도입사 측 통합 검토용 휴먼 가이드이지만, AX Flow 측 원본(SSOT, Single Source of Truth)은 FastMCP 도구 정의이며, OpenAPI 스펙·SDK 가이드는 모두 FastMCP 도구의 Pydantic 모델·docstring 에서 자동 파생된다. FastMCP 인스턴스(현재 raganything_server 의 mcp 객체)는 FastAPI 에 **마운트 prefix **/rag 로 마운트되며, 그 결과 /rag/mcp 가 MCP JSONRPC 마운트 포인트로 노출된다 — 호스트 LLM/에이전트는 이 경로로 JSONRPC tools/list / tools/call 요청을 송신한다. 동시에 각 FastMCP 도구가 FastAPI POST endpoint 로 1:1 자동 매핑되어 REST 인터페이스(/mcpapi/rag/<tool_name> — 모든 도구 POST, JSONRPC 래핑)를 함께 제공한다.
경로 prefix 설정 가능성 — /mcpapi 는 백엔드 hardcoded prefix (REST 노출 네임스페이스). /rag 는 FastMCP 서버 마운트 시 옵션으로 결정되는 prefix 이다. 동일 백엔드에 별개의 MCP 서버를 추가 마운트할 경우 prefix 마다 별도 진입점이 생성된다 — 예: 새 MCP 서버 example_mcp 를 /exam 으로 마운트 → MCP JSONRPC 진입점 /exam/mcp + REST /mcpapi/exam/<tool_name> 로 노출. 본 문서는 현행 raganything_server 의 /rag 마운트 기준으로 기재한다.
FastMCP 도구 정의 (Pydantic + @mcp.tool + docstring) — 원본 (SSOT)
│
├─→ FastAPI 마운트
│ └─→ /rag/mcp MCP 서버 진입점 (`tools/list`, `tools/call`)
│
└─→ FastMCP 도구 → FastAPI POST endpoint 1:1 자동 매핑
└─→ POST /mcpapi/rag/<tool_name> 도구별 REST 엔드포인트 (전부 POST, JSONRPC 래핑)
└─→ app.openapi()
├─→ /docs Swagger UI (인터랙티브 문서)
├─→ /redoc ReDoc (정적 문서)
└─→ /openapi.json OpenAPI 3.1 스펙 (기계 가독)
※ `/mcpapi` = 백엔드 hardcoded prefix / `/rag` = 현행 `raganything_server` 마운트 prefix (다른 MCP 서버 마운트 시 다른 이름 — 예: `example_mcp` → `/exam` → `/exam/mcp`)
※ FastAPI 단독 정의 라우트(`@app.post` 등)는 MCP 로 자동 노출되지 않는다 (FastAPI → MCP 역방향 자동 파생 현재 미지원).노출 방향성 주의 — 자동 파생은 FastMCP → FastAPI 단방향만 지원한다. 결과적으로 모든 기능이 MCP·REST 양쪽으로 동일하게 제공되는 것은 아니며, 도구별 노출 상태는 다음 3가지로 구분된다.
| 상태 | 의미 | 예시 |
|---|---|---|
| 양쪽 | FastMCP 도구 → MCP tools/list + REST /v1/* 자동 매핑 (대다수 도구) | index_local_files, delete_document 등 |
| MCP 전용 | FastMCP 도구이나 REST 노출 보류 — wrapper route 협의 필요 | retriever (현재) |
| REST 전용 / 예정 | FastAPI 단독 라우트 또는 미구현 항목 — MCP 자동 노출 없음 | PoC 단계 별도 협의 |
통합 검토 시 도구별 노출 상태는 3.1 매핑 표 및 부록 A 의 노출 컬럼 또는 통합 시점의 /docs / /rag/mcp tools/list 응답으로 직접 확인한다.
통합 파트너 개발팀은 통합 시점에 다음 진입점으로 정식 명세를 직접 수신할 수 있다.
| 진입점 | 용도 |
|---|---|
https://<host>/docs | Swagger UI — 인터랙티브 테스트 |
https://<host>/redoc | ReDoc — 정적 문서 페이지 |
https://<host>/openapi.json | OpenAPI 3.1 스펙 export — 클라이언트 코드 자동 생성용 (yaml 지원) |
https://<host>/rag/mcp (tools/list) | MCP JSONRPC 마운트 포인트 (tools/list / tools/call) — raganything_server 의 mcp 인스턴스가 /rag prefix 로 마운트된 결과. Pydantic 필드 설명이 도구 inputSchema 에 그대로 노출 |
본 명세서의 6. 데이터 입출력 스펙 · 부록 A 도구 카탈로그 · 16. 트러블슈팅 에러 코드 표는 모두 위 자동 파생물의 사람용 발췌이며, 정식 스키마는 /docs 인터랙티브 문서를 단일 기준으로 사용한다.