MCP 연동 개요
AI 앱이 XBOSS 를 도구로 부르는 방법입니다. 주소, 인증, 환경 헤더, 전송 방식을 한 곳에 모았습니다.
MCP 란
MCP(Model Context Protocol)는 AI 앱이 외부 도구를 부르는 표준입니다. XBOSS MCP 서버를 연결하면 Claude·ChatGPT·Cursor 같은 앱에서 사람이 말로 요청한 일을 XBOSS 작업으로 실행할 수 있습니다.
REST 로 직접 호출하는 것과 같은 작업을 부르고, 같은 자격증명·환경·한도를 씁니다.
| 엔드포인트 | POST https://api.xdata.kr/mcp |
|---|---|
| 프로토콜 | JSON-RPC 2.0 · Streamable HTTP |
| 인증 | Authorization: Basic |
| 환경 헤더 | X-MCP-Env-Scope (선택) |
| 헤더를 생략하면 | 스탠다드는 데모(real_test), PRO는 정식(production) |
- STEP 01AI 앱 연결
MCP 주소와 인증 헤더를 설정 파일에 넣습니다.
- STEP 02tools/list
앱이 쓸 수 있는 도구 목록을 받습니다.
- STEP 03tools/call
사용자의 요청에 맞는 도구를 부릅니다.
- STEP 04결과 반환
XBOSS 가 기관을 호출하고 결과를 돌려줍니다.
연동 방식 고르기
| 방식 | 하는 일 |
|---|---|
| AI 에디터 / 앱 | 설정 파일만 추가 |
| 서버에서 직접 호출 | 자사 AI 서비스에 연동 |
| AI 프레임워크 | MCP 어댑터 연결 |
| 노코드 자동화 | HTTP 요청 노드 설정 |
메서드
| 메서드 | 인증 | 설명 |
|---|---|---|
| initialize | 필요 없음 | 서버 정보를 확인합니다. |
| ping | 필요 없음 | 서버가 살아 있는지 확인합니다. |
| tools/list | 선택 | 인증하면 계정이 쓸 수 있는 도구 목록을 받고, 인증 정보 없이 부르면 공개 도구 목록을 받습니다. |
| tools/call | 필요 | 도구 하나를 실행합니다. 단일 도구는 최대 60초, 여러 기관을 묶은 팩 도구는 최대 90초까지 기다립니다. |
환경
| 환경 | X-MCP-Env-Scope 헤더 | 한도 |
|---|---|---|
| 데모(real_test) | real_test — 스탠다드 자격증명은 헤더를 생략해도 이 환경입니다. | REST 와 함께 쓰는 하루 100 사용 토큰 한도를 나눠 씁니다. |
| 정식(production) | production — PRO 자격증명은 헤더를 생략해도 이 환경입니다. | 유료 플랜 이용 중이면 일일 한도가 없습니다. |
샌드박스는 MCP 에서 쓸 수 없습니다. 헤더에 sandbox 를 넣으면 오류로 돌아옵니다 — MCP 오류 코드.
응답에 실리는 _meta
| 자리 | 키 | 내용 |
|---|---|---|
| tools/list 결과 | xdata.kr/lane | env_scope(이 연결이 도는 환경)와 source(그 환경이 정해진 방식: header, credential, oauth_grant, 인증 정보 없이 부르면 anonymous)입니다. 헤더를 보내지 않는 앱은 여기서 자기 환경을 압니다. |
| tools/list 의 각 도구 | xdata.kr/credential | required(부르기 전에 자격증명 등록이 필요한지), providers(등록할 상품 이름), windows_pc_needed(공동인증서로 등록하는 상품이 있으면 true, 그 등록은 Windows PC 에서 합니다), register_url(등록 화면 주소)입니다. 필요 없는 도구는 required 가 false 이고 register_url 이 null 입니다. |
| 성공한 tools/call | xdata.kr/quota_after | 남은 데모 호출량 limit, used, remaining, reset_at 입니다. 한도가 적용되는 데모 환경에서만 실리고, 같은 값이 두 번째 content 블록에도 실립니다. 정식 환경에는 없습니다. |
인증
Authorization 헤더에 REST 와 같은 API 키를 Basic 으로 넣습니다.
토큰 칸 하나만 있는 앱에서는 같은 Base64 값을 Bearer 로 보내도 됩니다 — 서버가 Basic 과 같게 처리합니다. OAuth 로 연결하는 앱은 콘솔에서 연결 승인을 처리합니다.
전송 방식
JSON — 기본값입니다. 도구 실행이 끝날 때까지 기다렸다가 한 번에 응답을 받습니다.
SSE — Accept: text/event-stream 을 보내면 진행 상황을 이벤트로 받습니다. 오래 걸리는 작업의 진행률을 화면에 보여 줄 때 씁니다.
연결 확인
# MCP 연결 확인 (tools/list)
# echo -n "<client_id>:<client_secret>" | base64
export MCP_URL="https://api.xdata.kr/mcp"
export AUTH_B64="<base64_결과_붙여넣기>"
curl -sS -X POST "$MCP_URL" \
-H "Authorization: Basic $AUTH_B64" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'데모 환경으로 확인
# MCP 연결 확인 (tools/list)
# echo -n "<client_id>:<client_secret>" | base64
export MCP_URL="https://api.xdata.kr/mcp"
export AUTH_B64="<base64_결과_붙여넣기>"
curl -sS -X POST "$MCP_URL" \
-H "Authorization: Basic $AUTH_B64" \
-H "Content-Type: application/json" \
-H "X-MCP-Env-Scope: real_test" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'도구 목록이 돌아오면 주소가 맞는 것입니다. 인증 헤더를 넣고 불렀다면 인증도 맞습니다 — 헤더 없이 부르면 공개 목록이 오며 _meta["xdata.kr/lane"].source 가 anonymous 입니다. 환경 권한과 한도는 도구를 부를 때 다시 확인됩니다. 앱별 설정 파일은 AI 에디터 · 앱 연동에 있습니다.