xdata-kr MCP API

openapi: 3.2.0
info:
  title: XBOSS MCP API
  description: '통합 REST API 서버 (홈택스 등). Human API guide: https://developer.xdata.kr · OpenAPI Reference: /docs'
  version: 2.0.0
security:
- basicClientCredential: []
- mcpOAuth2: []
tags:
- name: MCP
paths:
  /v1/mcp/entitled-tools:
    get:
      tags:
      - MCP
      summary: 내 MCP 사용 가능 도구 메타데이터 조회
      description: Return Console-safe MCP metadata from entitlement and registry SSOTs.
      operationId: get_mcp_entitled_tools_v1_v1_mcp_entitled_tools_get
      parameters:
      - name: env_scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: Env Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Env-Scope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: X-Env-Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/mcp/capability-catalog:
    get:
      tags:
      - MCP
      summary: Console MCP capability package + atomic catalog
      description: Return tool-ready MCP package hero cards and atomic grid for console marketing.
      operationId: get_mcp_capability_catalog_v1_v1_mcp_capability_catalog_get
      parameters:
      - name: env_scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: Env Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Env-Scope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: X-Env-Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /mcp:
    post:
      tags:
      - MCP
      summary: MCP (Model Context Protocol) — Streamable HTTP
      description: 'MCP JSON-RPC 2.0 엔드포인트.


        인증: `Authorization: Basic `

        Token/API-key 전용 클라이언트는 동일 base64 값을 `Authorization: Bearer ` 으로 보내도 됩니다 (MCP 진입점에서 Basic 으로 정규화).


        환경: 헤더가 없으면 계정의 레인에서 돈다 — 가입 직후의 데모 단계는 `real_test` (REST 와 동일 카운터), 라이트, 스탠다드, PRO 또는 멀티계정 요금제 중 하나를 시작한 뒤에는 `production`. `X-MCP-Env-Scope` 를 보내면 그 값이 우선한다. tools/list 결과 `_meta["xdata.kr/lane"]` 가 실제 레인을 알려 준다.


        지원 메서드: `initialize`, `tools/list`, `tools/call`, `ping`


        tools/call Option A (JSON): default Accept — no progress events

        tools/call Option B (SSE, recommended for products): `Accept: text/event-stream` — `notifications/progress` + keepalive'
      operationId: mcp_handler_mcp_post
      responses:
        '200':
          description: 'JSON-RPC 2.0 봉투. `Accept: text/event-stream` 으로 협상하면 같은 200 이 SSE 스트림이고, **이 모양은 그 스트림의 마지막 `data:` 프레임**이다 (`result` 또는 `error` 를 든 프레임). 그 앞의 프레임은 모양이 다르다 - `method: notifications/progress` 와 `params` 를 들고 `result`·`error`·`id` 가 없으며, keepalive 는 `:` 로 시작하는 주석 줄이라 JSON 이 아니다.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcResponse'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    McpJsonRpcResponse:
      properties:
        jsonrpc:
          type: string
          const: '2.0'
          title: Jsonrpc
          description: 늘 "2.0" 이다.
        id:
          anyOf:
          - type: string
          - type: integer
          - type: 'null'
          title: Id
          description: 요청의 id. 요청을 파싱하지 못했으면 null 이다.
        result:
          anyOf:
          - {}
          - type: 'null'
          title: Result
          description: 성공일 때의 결과. 오류일 때는 키 자체가 없다.
        error:
          anyOf:
          - $ref: '#/components/schemas/McpJsonRpcErrorBody'
          - type: 'null'
          description: 오류일 때의 봉투. 성공일 때는 키 자체가 없다.
      type: object
      required:
      - jsonrpc
      title: McpJsonRpcResponse
      description: '``POST /mcp`` 의 200 응답 - JSON-RPC 2.0 봉투.


        ``result`` 와 ``error`` 는 **둘 중 하나만** 실린다(JSON-RPC 2.0 규약). 둘 다 선택으로

        둔 까닭: 하나를 필수로 하면 다른 갈래가 규격을 위반하게 되고, ``oneOf`` 로 쪼개면 같은

        봉투가 모델 둘이 되어 읽는 쪽이 그 둘을 맞춰야 한다. 그 배타는 문장으로 적는다.


        **이 모델은 ``response_model`` 로 달지 않는다.** 그 라우트 핸들러는

        ``Union[JSONResponse, StreamingResponse]`` 를 돌려주고, 같은 200 이 협상에 따라

        ``text/event-stream`` 일 수 있다 - ``response_model`` 은 미디어 하나를 강제하므로

        스트리밍 갈래에서 규격이 거짓이 된다. ``responses={200: ...}`` 로 **문서만** 더한다

        (그 자리는 런타임을 건드리지 않는다).'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    McpJsonRpcErrorBody:
      properties:
        code:
          type: integer
          title: Code
          description: JSON-RPC 오류 코드. 우리 코드는 -32001 대역을 쓴다.
        message:
          type: string
          title: Message
          description: 고객 AI 에게 보이는 한국어 문장.
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
          description: 구조화 칸. 없으면 키 자체가 없다. reason · error_code · safe_to_retry · next_action · "xdata.kr/next" 가 여기 실린다.
      type: object
      required:
      - code
      - message
      title: McpJsonRpcErrorBody
      description: 오류 봉투의 ``error`` 칸.
  securitySchemes:
    basicClientCredential:
      type: http
      scheme: basic
      description: 'Console-issued client credential. Send `Authorization: Basic base64(client_id:client_secret)`.'
    mcpOAuth2:
      type: oauth2
      description: For MCP clients. OAuth 2.0 authorization code flow with PKCE (S256) for public clients. The client_id is the HTTPS URL of an OAuth Client ID Metadata Document that XBOSS has allow-listed; dynamic client registration is not supported.
      flows:
        authorizationCode:
          authorizationUrl: https://api.xdata.kr/oauth/authorize
          tokenUrl: https://api.xdata.kr/oauth/token
          scopes: {}