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 <base64(client_id:client_secret)> |
| 환경 헤더 | X-MCP-Env-Scope (선택) |
| 헤더를 생략하면 | 요금제를 시작하기 전의 계정은 데모(real_test), 요금제를 시작한 계정은 정식(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초까지 기다립니다. 응답을 받지 못해 같은 요청을 다시 보낼 때의 규칙은 재시도의 「도구 호출(MCP)의 재시도」 에 있습니다. |
환경
| 환경 | X-MCP-Env-Scope 헤더 | 한도 |
|---|---|---|
| 데모(real_test) | real_test — 요금제를 시작하기 전의 계정은 헤더를 생략해도 이 환경입니다. | 현재 혜택은 요금제에서 확인해 주세요. REST와 MCP가 같은 사용량을 공유합니다. |
| 정식(production) | production — 요금제를 시작한 계정은 헤더를 생략해도 이 환경입니다. | 일일 한도 — 현재 혜택은 요금제에서 확인해 주세요. 한 달 한도 — 현재 혜택은 요금제에서 확인해 주세요. 구독 한도는 결제일 기준으로 다시 채워집니다. |
MCP 환경은 데모(real_test)와 정식(production)입니다.그 밖의 값을 헤더에 넣으면 오류로 돌아옵니다 — MCP 오류 코드.
응답에 실리는 _meta
| 자리 | 키 | 내용 |
|---|---|---|
| tools/list 결과 | xdata.kr/lane | env_scope(이 연결이 도는 환경)와 source(그 환경이 정해진 방식: header, credential, oauth_grant, 인증 정보 없이 부르면 anonymous, 인증 정보는 읽었지만 계정에서 먼저 할 일이 있으면 refused)입니다. 헤더를 보내지 않는 앱은 여기서 자기 환경을 압니다. |
| 거절된 tools/list 결과(source 가 refused 일 때) | xdata.kr/refusal | 거절 이유입니다. message(사용자에게 전할 문장)와 있으면 data(error_code, link_url 같은 코드와 주소)가 실립니다. 이 목록은 공개 도구 목록이고 env_scope 도 공개 목록의 것이라 계정의 환경이 바뀐 것으로 알리지 않습니다. 사용자가 조치한 뒤에는 tools/list 를 다시 받습니다. 그 도구를 부르면 같은 이유가 isError 결과로 옵니다. |
| tools/list 의 각 도구 | xdata.kr/credential | required(부르기 전에 자격증명 등록이 필요한지), providers(등록해야 하는 기관의 식별자, 예: hometax), windows_pc_needed(공동인증서로 등록하는 상품이 있으면 true, 그 등록은 Windows PC 에서 합니다), register_url(등록 화면 주소)입니다. 필요 없는 도구는 required 가 false 이고 register_url 이 null 입니다. |
| 성공한 tools/call | xdata.kr/quota_after | 남은 사용 토큰입니다(limit, used, remaining, reset_at, period). 사용 토큰을 세는 환경에서 실립니다 - 데모 환경, 그리고 하루 한도가 정해진 요금제의 정식 환경입니다. 같은 값이 두 번째 content 블록에도 실립니다. 하루 한도가 정해지지 않은 요금제의 정식 환경에는 없습니다. |
| 안내가 따라오는 tools/call 결과(인증 정보 없이 부른 호출이 isError 로 올 때, 맛보기로 성공했을 때, 남은 사용 토큰이 적을 때) | xdata.kr/next | 사용자에게 안내할 다음 행동입니다(stage, say_to_user, who, action_url). 같은 칸이 오류에는 error.data 로 실립니다 — MCP 오류 코드의 「다음 행동 안내 칸」. |
| 인증 정보 없이 부른 tools/call 이 isError 결과로 올 때 | mcp/www_authenticate | OAuth 로그인 연결에 쓰는 인증 도전(RFC 6750 형식의 문자열)의 목록입니다. ChatGPT 처럼 openai/* 메타를 보내는 앱이 로그인 연결을 시작하려고 읽는 값이라 직접 다룰 일은 드뭅니다. 401 응답에서는 같은 문자열이 WWW-Authenticate 헤더로 옵니다. |
인증
Authorization 헤더에 REST 와 같은 API 키를 Basic 으로 넣습니다.
토큰 칸 하나만 있는 앱에서는 같은 Base64 값을 Bearer 로 보내도 됩니다 — 서버가 Basic 과 같게 처리합니다. OAuth 로 연결하는 앱은 콘솔에서 연결 승인을 처리합니다.
계정 없이 맛보기
가입하기 전에 써 볼 수 있도록 일부 도구는 인증 정보 없이도 부를 수 있게 열어 둡니다.
- 열려 있는 도구는 tools/list 의 도구 선언에서 securitySchemes에 noauth가 포함되고 기관 자격증명이 필요하지 않은 도구입니다.나머지 도구를 인증 정보 없이 부르면 가입을 안내하며 거절됩니다(MCP 오류 코드의 HTTP 상태 표).
- 하루 몫이 있습니다. 호출자별 몫을 다 쓰면 TASTE_DAILY_LIMIT, 서비스 전체 또는 같은 AI 앱의 손님들이 함께 쓰는 몫이 차면 TASTE_GLOBAL_LIMIT 으로 거절됩니다.코드별 설명은 MCP 오류 코드에 있습니다.
- 성공 응답과 거절 응답의 본문에는 이용약관에 동의한 것으로 본다는 한 줄이 붙고, 가입을 권하는 「다음 행동 안내」 칸이 함께 옵니다.
- 현재 혜택은 요금제에서 확인해 주세요. 기관 연동이 필요한 도구는 자격증명을 등록한 뒤에 부를 수 있습니다.
AI 에이전트가 사용자의 이메일 하나로 계정과 키를 받는 절차는 auth.md에 있습니다. 읽는 쪽이 에이전트라 영어로 적힌 문서입니다.
브라우저에서 입력하고 결과를 받는 무료도구와 실행 명세도 제공합니다.브라우저 전용 도구는 HTTP API나 MCP 도구로 호출할 수 없습니다. 무료 결과 뒤의 관련 상품 안내는 기존 가입과 선택한 업무로 이어집니다.
전송 방식
JSON — 기본값입니다. 도구 실행이 끝날 때까지 기다렸다가 한 번에 응답을 받습니다.
SSE — Accept: text/event-stream 을 보내면 진행 상황을 이벤트로 받습니다. 오래 걸리는 작업의 진행률을 화면에 보여 줄 때 씁니다.
연결 확인
# MCP 연결 확인 (tools/list)
# echo -n "<client_id>:<client_secret>" | base64
export XBOSS_MCP_URL="https://api.xdata.kr/mcp"
export XBOSS_MCP_AUTH_B64="<base64_결과_붙여넣기>"
curl -sS -X POST "$XBOSS_MCP_URL" \
-H "Authorization: Basic $XBOSS_MCP_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 XBOSS_MCP_URL="https://api.xdata.kr/mcp"
export XBOSS_MCP_AUTH_B64="<base64_결과_붙여넣기>"
curl -sS -X POST "$XBOSS_MCP_URL" \
-H "Authorization: Basic $XBOSS_MCP_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 입니다. refused 이면 인증 정보는 읽혔지만 계정에서 먼저 할 일이 있다는 뜻입니다(예: 갱신된 약관에 동의).목록은 공개 도구만 담고, 이유와 안내 주소는 도구를 불렀을 때 result.isError 로 옵니다.
- 환경 권한과 한도는 도구를 부를 때 다시 확인됩니다.
앱별 설정 파일은 AI 에디터 · 앱 연동에 있습니다.