버전: 0.68.0

MCP 세션 상태 확인 API (Ping)

개요

MCP 세션 상태 확인 API는 특정 MCP 세션의 연결 상태를 실시간으로 확인하는 기능을 제공합니다. 이 API는 클라이언트가 에이전트 보드와의 연결 상태를 모니터링하고, 세션 만료나 연결 끊김을 감지할 수 있도록 도와줍니다.

주요 특징

실시간 상태 확인: 메모리와 Redis 저장소에서 세션 상태를 빠르게 확인
다중 계층 검증: 메모리(SSE 연결) → Redis → 세션 없음 순서로 정확한 상태 확인
세션 정보 제공: 세션이 존재하는 경우 프로토콜 버전, 생성/만료 시간 정보 제공
에러 처리: 세션 확인 실패 시 상세한 에러 정보 제공

데이터 활용

세션 상태 정보는 다음과 같은 용도로 활용됩니다:

연결 상태 모니터링: 클라이언트의 MCP 세션 연결 상태 실시간 확인
세션 복구: 연결이 끊어진 세션의 복구 필요성 판단
리소스 관리: 만료된 세션의 정리 및 메모리 관리
사용자 경험 개선: 연결 상태에 따른 적절한 UI 표시

제약사항

세션 ID가 없거나 유효하지 않은 경우 오류 반환
사용자는 자신의 세션만 확인 가능
세션 생성 후에만 상태 확인 가능

세션 상태 확인

특정 MCP 세션의 연결 상태를 확인합니다.

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

Headers

Header	Type	Description	Required
`Authorization`	`Bearer {accessToken}`	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
`Mcp-Session-Id`	`string`	상태를 확인할 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`	세션 상태 확인 성공 (세션이 존재하고 연결됨)	-
`400 Bad Request`	잘못된 요청 (세션 ID 누락 또는 세션이 존재하지 않음)	`12020`, `12023`
`401 Unauthorized`	인증 실패 (유효하지 않은 액세스 토큰)	`10001`
`403 Forbidden`	권한 없음 (다른 사용자의 세션 접근)	`10030`
`500 Internal Server Error`	서버 내부 오류	`10000`

200 OK - 세션 상태 확인 성공

연결된 세션:

{
  "sessionId": "agentboard-1234567890-abc123",
  "connected": true,
  "timestamp": "2025-01-07T02:00:00.000Z",
  "sessionInfo": {
    "protocolVersion": "2025-03-26",
    "createdAt": "2025-01-07T01:00:00.000Z",
    "expiresAt": "2025-01-08T01:00:00.000Z"
  }
}

필드	타입	설명	필수
`sessionId`	string	확인한 세션의 고유 ID	Yes
`connected`	boolean	세션 연결 상태 (항상 true)	Yes
`timestamp`	string	상태 확인 시각 (ISO 8601 형식)	Yes
`sessionInfo`	object	세션 정보	Yes
`sessionInfo.protocolVersion`	string	MCP 프로토콜 버전	Yes
`sessionInfo.createdAt`	string	세션 생성 시각 (ISO 8601 형식)	Yes
`sessionInfo.expiresAt`	string	세션 만료 시각 (ISO 8601 형식)	Yes

400 Bad Request - 잘못된 요청

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

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

예시 2: 세션이 존재하지 않음 (SESSION_NOT_FOUND - 12023)

{
  "jsonrpc": "2.0",
  "error": {
    "code": 12023,
    "message": "세션을 찾을 수 없습니다.",
    "data": {
      "context": "ping",
      "sessionId": "agentboard-1234567890-abc123"
    }
  }
}

401 Unauthorized - 인증 실패

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

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

500 Internal Server Error - 서버 내부 오류

예시: 일반 서버 오류 (SERVER_ERROR - 10000)

{
  "code": 10000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류가 발생했습니다."
}

설명

이 API는 MCP 세션의 연결 상태를 실시간으로 확인하는 핵심 기능입니다.
동작 방식:
- 세션이 존재하고 연결된 경우: 200 OK 응답과 함께 세션 정보 반환
- 세션 ID가 누락된 경우: 400 Bad Request 에러 반환
- 세션이 존재하지 않거나 만료된 경우: 400 Bad Request 에러 반환
다중 계층 검증 방식:
- 1단계: 메모리(SSE 연결) 확인 - 가장 신속하고 정확한 상태
- 2단계: Redis 세션 정보 확인 - 연결이 끊어졌지만 세션은 유효한 상태
- 3단계: 세션 없음 - 세션이 존재하지 않거나 만료된 상태 (400 에러 반환)
세션 정보 제공:
- 세션이 존재하는 경우 프로토콜 버전, 생성/만료 시간 정보 제공
- 세션 만료 시간을 통해 클라이언트가 세션 갱신 필요성 판단 가능
클라이언트 사용법:
- HTTP Status Code만 확인하여 세션 상태 판단 가능
- 200 OK: 세션 활성, 400 Bad Request: 세션 없음 또는 재연결 필요
- Response body 파싱 불필요로 빠른 상태 확인 가능
사용 사례:
- 주기적인 연결 상태 모니터링 (heartbeat)
- 세션 만료 전 사전 알림 및 갱신
- 연결 끊김 감지 후 재연결 로직 트리거
- 앱 복구 시 기존 세션 유효성 검증

개요​

주요 특징​

데이터 활용​

제약사항​

세션 상태 확인​

Headers​

Responses​

설명​

개요