버전: 개발 버전 (최신)

MCP SSE 스트림 연결 API (GET)

개요

MCP SSE 스트림 연결 API는 클라이언트가 에이전트 보드와 Server-Sent Events(SSE) 실시간 스트림 연결을 설정하는 기능을 제공합니다. 이 API는 MCP 세션 초기화 후 실시간 메시지 수신을 위해 사용되며, 지속적인 연결을 통해 서버에서 클라이언트로 메시지를 푸시할 수 있습니다.

주요 특징

SSE 스트림 연결: Server-Sent Events를 통한 실시간 양방향 통신
세션 등록: 기존 세션 ID를 사용한 SSE 연결 등록
자동 연결 상태 관리: 연결 해제 감지 및 자동 정리
초기 연결 확인: 연결 성공 시 초기 메시지 전송

데이터 활용

SSE 연결을 통해 수신되는 데이터는 다음과 같은 용도로 활용됩니다:

실시간 메시지 수신: 서버에서 푸시되는 에이전트 보드 메시지
연결 상태 확인: 초기 연결 확인 및 하트비트
오프라인 메시지 동기화: 재연결 시 누락된 메시지 전달
브로드캐스트 메시지: 시스템 알림 및 공지사항 수신

제약사항

유효한 세션 ID 필요 (POST API로 먼저 세션 초기화 필요)
Accept 헤더에 text/event-stream 포함 필수
연결 후 지속적인 스트림 유지 필요
네트워크 연결 끊김 시 재연결 필요

SSE 스트림 연결

기존 MCP 세션에 대한 SSE 스트림 연결을 설정합니다.

HTTP Method: GET
Path: /v1/agent-board/mcp/messages
인증: 액세스 토큰 (accessToken) 필요

Headers

Header	Type	Description	Required
`Authorization`	`Bearer {accessToken}`	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
`Accept`	`text/event-stream`	SSE 연결을 위해 `text/event-stream`이 포함되어야 합니다.	Yes
`Mcp-Session-Id`	`string`	POST API로 생성된 MCP 세션 ID입니다.	Yes
`Accept-Language`	`de-DE`, `en-US`, `ko-KR`	오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.	No

Responses

HTTP Status Code	설명	Error Code(s)
`200 OK`	SSE 스트림 연결 성공 (지속적인 연결 유지)	-
`400 Bad Request`	잘못된 요청 (헤더 누락 또는 잘못된 형식)	`12040`, `12020`, `12070`
`401 Unauthorized`	인증 실패 (유효하지 않은 액세스 토큰)	`10001`
`500 Internal Server Error`	서버 내부 오류 또는 SSE 연결 설정 실패	`12001`, `12025`, `12071`, `12075`, `12074`

200 OK - SSE 스트림 연결 성공

초기 연결 메시지:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {"type":"connected","sessionId":"user_12345678-1234-1234-1234-123456789abc","timestamp":"2025-01-07T02:00:00.000Z"}

필드	타입	설명	필수
초기 연결 메시지
`type`	string	메시지 타입 (`connected`)	Yes
`sessionId`	string	연결된 세션 ID	Yes
`timestamp`	string	연결 시각 (ISO 8601 형식)	Yes

Response Headers:

Header	Value	Description
`Content-Type`	text/event-stream	SSE 스트림 콘텐츠 타입
`Cache-Control`	no-cache	캐시 비활성화
`Connection`	keep-alive	지속적인 연결 유지

400 Bad Request - 잘못된 요청

예시: Accept 헤더 누락 또는 잘못된 형식 (INVALID_ACCEPT_HEADER - 12040)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12040,
    "message": "SSE connection error",
    "data": "Accept header must include text/event-stream"
  }
}

예시: 세션 ID 누락 (SESSION_ID_REQUIRED - 12020)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12020,
    "message": "Session ID required",
    "data": "Mcp-Session-Id header is required for SSE stream"
  }
}

401 Unauthorized - 인증 실패

예시: 유효하지 않은 액세스 토큰 (INVALID_ACCESS_TOKEN - 10001)

{
  "code": 10001,
  "message": "INVALID_ACCESS_TOKEN",
  "detail": "유효하지 않은 액세스 토큰입니다.",
  "metadata": {
    "context": "authentication"
  }
}

500 Internal Server Error - 서버 내부 오류

예시: SSE 연결 설정 실패 (SSE_CONNECTION_ERROR - 12070)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12070,
    "message": "Failed to establish SSE connection",
    "data": "SSE connection setup failed"
  }
}

예시: 세션 등록 실패 (SSE_REGISTRATION_FAILED - 12071)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12071,
    "message": "Session registration failed",
    "data": "SSE registration failed: connection error"
  }
}

예시: 일반 서버 오류 (INTERNAL_ERROR - 12001)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12001,
    "message": "Unexpected error during SSE connection setup",
    "data": "Internal server error"
  }
}

예시: 세션 초기화 실패 (SESSION_INITIALIZATION_FAILED - 12025)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12025,
    "message": "Session initialization failed",
    "data": "Failed to initialize MCP session"
  }
}

예시: 스트림 연결 끊김 (STREAM_CONNECTION_LOST - 12074)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12074,
    "message": "Stream connection lost",
    "data": "SSE connection was closed unexpectedly"
  }
}

설명

이 API는 MCP 세션 초기화 후 실시간 메시지 수신을 위한 SSE 연결을 설정합니다.
연결 설정 과정:
- Accept 헤더에 text/event-stream 포함 여부 검증
- Mcp-Session-Id 헤더 검증 (POST API로 먼저 생성된 세션 ID 필요)
- RegisterSessionCommand 실행하여 세션 등록 및 SSE 연결 설정
- 초기 연결 확인 메시지 전송
SSE 헤더 설정:
- Content-Type: text/event-stream
- Cache-Control: no-cache
- Connection: keep-alive
- CORS 헤더 자동 설정
연결 상태 관리:
- 연결 끊김 자동 감지 및 세션 정리
- 헤더 전송 상태 확인 후 에러 응답 처리
- 연결 실패 시 적절한 Agent Board 에러 코드 반환
에러 처리:
- JSON-RPC 2.0 응답 형식 유지, Agent Board 도메인 에러 코드 사용 (12xxx)
- SseConnectionError: SSE 연결 관련 에러 (12070)
- SseRegistrationFailedError: 세션 등록 실패 (12071)
- SessionInitializationFailedError: 세션 초기화 실패 (12025)
- InvalidAcceptHeaderError: Accept 헤더 오류 (12040)
- SessionIdRequiredError: 세션 ID 누락 (12020)
- StreamConnectionLostError: 스트림 연결 끊김 (12074)
메시지 타입:
- 초기 연결: {"type": "connected"} 형태
- 실시간 메시지: JSON-RPC 2.0 형식의 method call
- 브로드캐스트: messages/broadcast 메서드
- 새 메시지: messages/new 메서드
사용 사례:
- 앱 시작 후 실시간 메시지 수신 대기
- 오프라인 메시지 동기화
- 시스템 브로드캐스트 메시지 수신
- 에이전트 치료 플로우 메시지 실시간 푸시

개요​

주요 특징​

데이터 활용​

제약사항​

SSE 스트림 연결​

Headers​

Responses​

설명​

개요