---
title: "MCP (Model Context Protocol) — Streamable HTTP"
method: POST
path: "/mcp"
tags: ["MCP"]
---

# MCP (Model Context Protocol) — Streamable HTTP

`POST /mcp`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/mcp`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

MCP JSON-RPC 2.0 엔드포인트.

인증: `Authorization: Basic <base64(client_id:client_secret)>`
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

## Response `200`

JSON-RPC 2.0 봉투. `Accept: text/event-stream` 으로 협상하면 같은 200 이 SSE 스트림이고, **이 모양은 그 스트림의 마지막 `data:` 프레임**이다 (`result` 또는 `error` 를 든 프레임). 그 앞의 프레임은 모양이 다르다 - `method: notifications/progress` 와 `params` 를 들고 `result`·`error`·`id` 가 없으며, keepalive 는 `:` 로 시작하는 주석 줄이라 JSON 이 아니다.

- McpJsonRpcResponse: ``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: ...}`` 로 **문서만** 더한다 (그 자리는 런타임을 건드리지 않는다).
  - `jsonrpc` '2.0', required: 늘 "2.0" 이다.
  - `id` union: 요청의 id. 요청을 파싱하지 못했으면 null 이다.
    - string
    - integer
  - `result` unknown
  - `error` McpJsonRpcErrorBody: 오류 봉투의 ``error`` 칸 - ``McpError.to_dict()`` 가 만드는 모양 그대로.
    - `code` integer, required: JSON-RPC 오류 코드. 우리 코드는 -32001 대역을 쓴다.
    - `message` string, required: 고객 AI 에게 보이는 한국어 문장.
    - `data` object, nullable: 구조화 칸. 없으면 키 자체가 없다. reason · error_code · safe_to_retry · next_action · "xdata.kr/next" 가 여기 실린다.

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)