버전: 개발 버전 (최신)

MCP 세션 삭제 API (DELETE)

개요

MCP 세션 삭제 API는 클라이언트가 에이전트 보드와의 MCP(Model Context Protocol) 세션을 명시적으로 종료하는 기능을 제공합니다. 이 API는 MCP 표준에 따른 세션 종료 방식으로, 활성 SSE 연결을 해제하고 Redis 캐시에서 세션 데이터를 삭제하며, Redis pub/sub을 통해 세션 종료 이벤트를 발행합니다.

주요 특징

MCP 표준 준수: MCP Streamable HTTP 표준에 따른 세션 종료 구현
완전한 정리: SSE 연결 해제, 캐시 삭제, 이벤트 발행을 포함한 포괄적 세션 정리
이벤트 기반: Redis pub/sub을 통한 세션 종료 이벤트 발행으로 마이크로서비스 간 상태 동기화
안전한 종료: 사용자별 세션 격리 보장 및 권한 검증을 통한 보안 강화

데이터 처리

세션 삭제 시 다음과 같은 처리가 수행됩니다:

SSE 연결 해제: 활성 Server-Sent Events 스트림 연결 종료
캐시 데이터 삭제: Redis에 저장된 sse:user:session:{userId} 키 삭제
이벤트 발행: session-events 채널로 세션 종료 이벤트 pub/sub 발행
연결 상태 정리: 세션과 관련된 모든 메타데이터 및 상태 정보 정리
리소스 해제: 세션과 연관된 메모리 및 네트워크 리소스 해제

제약사항

유효한 액세스 토큰 필요
세션 소유자만 삭제 가능 (사용자별 권한 검증)
Mcp-Session-Id 헤더 필수
이미 종료된 세션에 대한 DELETE 요청 시 에러 반환
세션 삭제 후 복구 불가능

세션 삭제

기존 MCP 세션을 종료하고 관련 리소스를 정리합니다.

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

Headers

Header	Type	Description	Required
`Authorization`	`Bearer {accessToken}`	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
`Mcp-Session-Id`	`string`	삭제할 MCP 세션의 고유 식별자입니다. 세션 초기화 시 받은 `mcp-{uuid}` 형태의 값을 사용해야 합니다.	Yes
`Accept-Language`	`de-DE`, `en-US`, `ko-KR`	오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.	No

Request Body

DELETE 요청은 Request Body를 사용하지 않습니다.

Responses

HTTP Status Code	설명	Error Code(s)
`204 No Content`	세션 삭제 성공	-
`400 Bad Request`	세션 ID 누락 또는 잘못된 요청	`12020`
`401 Unauthorized`	인증 실패 (유효하지 않은 액세스 토큰)	`10001`
`404 Not Found`	세션을 찾을 수 없음	`12023`
`500 Internal Server Error`	세션 삭제 실패 또는 서버 내부 오류	`12024`

204 No Content - 세션 삭제 성공

세션이 성공적으로 삭제되었을 때 반환되는 응답입니다. 응답 본문은 비어있습니다.

Response Headers:

Header	Value	Description
`Content-Length`	0	응답 본문이 비어있음을 나타냄

Response Body:

(empty body)

세션 삭제 시 수행되는 작업:

SSE 연결 해제: 활성 Server-Sent Events 스트림 연결 종료
캐시 데이터 삭제: Redis의 sse:user:session:{userId} 키 삭제

이벤트 발행: Redis pub/sub을 통해 세션 종료 이벤트 발행

{
  "type": "session.terminated",
  "userId": "user-uuid",
  "sessionId": "mcp-session-uuid",
  "wasActive": true,
  "terminatedAt": "2025-01-07T03:30:00.000Z",
  "timestamp": "2025-01-07T03:30:00.000Z"
}

리소스 정리: 메모리 및 네트워크 리소스 해제

400 Bad Request - 세션 ID 누락

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

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 12020,
    "message": "SESSION_ID_REQUIRED",
    "data": "세션 ID가 필요합니다."
  }
}

발생 조건:

Mcp-Session-Id 헤더가 누락된 경우
Mcp-Session-Id 헤더 값이 빈 문자열인 경우

401 Unauthorized - 인증 실패

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

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

예시: 사용자 정보 없음 (USER_NOT_FOUND)

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 12031,
    "message": "USER_ID_REQUIRED",
    "data": "사용자 ID가 필요합니다."
  }
}

404 Not Found - 세션을 찾을 수 없음

예시: 존재하지 않는 세션 (SESSION_NOT_FOUND - 12023)

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 12023,
    "message": "SESSION_NOT_FOUND",
    "data": "세션을 찾을 수 없습니다."
  }
}

발생 조건:

제공된 세션 ID에 해당하는 세션이 존재하지 않는 경우
이미 삭제된 세션에 대해 DELETE 요청을 수행한 경우
다른 사용자의 세션에 대해 DELETE 요청을 수행한 경우

500 Internal Server Error - 세션 삭제 실패

예시: 세션 종료 실패 (SESSION_TERMINATION_FAILED - 12024)

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 12024,
    "message": "SESSION_TERMINATION_FAILED",
    "data": "세션 종료에 실패했습니다."
  }
}

예시: 내부 서버 오류 (INTERNAL_ERROR - 12001)

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 12001,
    "message": "INTERNAL_ERROR",
    "data": "내부 처리 중 오류가 발생했습니다."
  }
}

발생 조건:

Redis 연결 실패
SSE 연결 해제 실패
이벤트 발행 실패
기타 예상치 못한 서버 오류

설명

이 API는 MCP 세션의 생명주기를 완료하는 마지막 단계입니다.
요청 특성:
- DELETE HTTP 메서드 사용
- Request Body 없음 (헤더만 사용)
- Mcp-Session-Id 헤더 필수
- Authorization 헤더를 통한 사용자 인증 필요
세션 삭제 프로세스:
- 세션 소유권 검증 (요청한 사용자와 세션 소유자 일치 확인)
- DeleteSessionCommand 실행을 통한 도메인 로직 처리
- McpProtocolAdapter.unregisterSseConnection() 호출로 SSE 연결 해제
- Redis에서 sse:user:session:{userId} 키 삭제
- RedisSessionEventService.publishSessionTerminated() 호출로 이벤트 발행
이벤트 기반 아키텍처:
- Redis pub/sub을 통해 session-events 채널로 종료 이벤트 발행
- 다른 마이크로서비스에서 세션 종료 이벤트 수신 가능
- 이벤트 페이로드에 userId, sessionId, wasActive 등 포함
보안 고려사항:
- 세션 소유자만 해당 세션 삭제 가능
- JWT 토큰을 통한 사용자 인증 및 권한 검증
- 세션 ID 유효성 검사 수행
- CORS 헤더 설정으로 브라우저 보안 정책 준수
리소스 정리:
- SSE 스트림 연결 완전 해제
- Redis 캐시 데이터 삭제
- 메모리 및 네트워크 리소스 해제
- 관련 메타데이터 정리
멱등성 (Idempotency):
- 동일한 세션에 대한 여러 DELETE 요청 시 404 반환
- 이미 삭제된 세션은 SESSION_NOT_FOUND 에러 반환
- 시스템 상태에 부작용 없음
사용 사례:
- 앱 종료 시 명시적 세션 정리
- 사용자 로그아웃 시 세션 종료
- 장시간 비활성 상태 후 세션 정리
- 에러 발생 시 세션 강제 종료
- 관리자에 의한 세션 강제 해제
후속 작업:
- 세션 삭제 후 새로운 세션 사용 시 POST 요청으로 재초기화 필요
- 클라이언트에서 세션 ID 저장소 정리
- 관련 UI 상태 초기화

개요​

주요 특징​

데이터 처리​

제약사항​

세션 삭제​

Headers​

Request Body​

Responses​

설명​

개요

주요 특징

데이터 처리

제약사항

세션 삭제

Headers

Request Body

Responses

설명