개발자 문서
개발자 문서

MCP 연동 개요

AI 앱이 XBOSS 를 도구로 부르는 방법입니다. 주소, 인증, 환경 헤더, 전송 방식을 한 곳에 모았습니다.

MCP 란

MCP(Model Context Protocol)는 AI 앱이 외부 도구를 부르는 표준입니다.

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)
  1. STEP 01
    AI 앱 연결

    MCP 주소와 인증 헤더를 설정 파일에 넣습니다.

  2. STEP 02
    tools/list

    앱이 쓸 수 있는 도구 목록을 받습니다.

  3. STEP 03
    tools/call

    사용자의 요청에 맞는 도구를 부릅니다.

  4. STEP 04
    결과 반환

    XBOSS 가 기관을 호출하고 결과를 돌려줍니다.

AI 앱이 도구 목록을 받아 사용자의 요청에 맞는 도구를 부르면, 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)입니다.

응답에 실리는 _meta

자리키내용
tools/list 결과xdata.kr/laneenv_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/credentialrequired(부르기 전에 자격증명 등록이 필요한지), providers(등록해야 하는 기관의 식별자, 예: hometax), windows_pc_needed(공동인증서로 등록하는 상품이 있으면 true, 그 등록은 Windows PC 에서 합니다), register_url(등록 화면 주소)입니다. 필요 없는 도구는 required 가 false 이고 register_url 이 null 입니다.
성공한 tools/callxdata.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_authenticateOAuth 로그인 연결에 쓰는 인증 도전(RFC 6750 형식의 문자열)의 목록입니다. ChatGPT 처럼 openai/* 메타를 보내는 앱이 로그인 연결을 시작하려고 읽는 값이라 직접 다룰 일은 드뭅니다. 401 응답에서는 같은 문자열이 WWW-Authenticate 헤더로 옵니다.

인증

Authorization 헤더에 REST 와 같은 API 키를 Basic 으로 넣습니다.

토큰 칸 하나만 있는 앱에서는 같은 Base64 값을 Bearer 로 보내도 됩니다 — 서버가 Basic 과 같게 처리합니다. OAuth 로 연결하는 앱은 콘솔에서 연결 승인을 처리합니다.

계정 없이 맛보기

가입하기 전에 써 볼 수 있도록 일부 도구는 인증 정보 없이도 부를 수 있게 열어 둡니다.

  • 열려 있는 도구는 tools/list 의 도구 선언에서 securitySchemes에 noauth가 포함되고 기관 자격증명이 필요하지 않은 도구입니다.
  • 하루 몫이 있습니다. 호출자별 몫을 다 쓰면 TASTE_DAILY_LIMIT, 서비스 전체 또는 같은 AI 앱의 손님들이 함께 쓰는 몫이 차면 TASTE_GLOBAL_LIMIT 으로 거절됩니다.
  • 성공 응답과 거절 응답의 본문에는 이용약관에 동의한 것으로 본다는 한 줄이 붙고, 가입을 권하는 「다음 행동 안내」 칸이 함께 옵니다.
  • 현재 혜택은 요금제에서 확인해 주세요. 기관 연동이 필요한 도구는 자격증명을 등록한 뒤에 부를 수 있습니다.

AI 에이전트가 사용자의 이메일 하나로 계정과 키를 받는 절차는 auth.md에 있습니다. 읽는 쪽이 에이전트라 영어로 적힌 문서입니다.

브라우저에서 입력하고 결과를 받는 무료도구와 실행 명세도 제공합니다.

전송 방식

JSON — 기본값입니다. 도구 실행이 끝날 때까지 기다렸다가 한 번에 응답을 받습니다.

SSE — Accept: text/event-stream 을 보내면 진행 상황을 이벤트로 받습니다. 오래 걸리는 작업의 진행률을 화면에 보여 줄 때 씁니다.

연결 확인

bash
# 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":{}}'

데모 환경으로 확인

bash
# 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":{}}'

도구 목록이 돌아오면 주소가 맞는 것입니다.

  • 인증 헤더를 넣고 불렀다면 인증도 맞습니다.
  • 환경 권한과 한도는 도구를 부를 때 다시 확인됩니다.

앱별 설정 파일은 AI 에디터 · 앱 연동에 있습니다.