버전: 0.68.0

MCP 세션 초기화 API (POST)

개요

MCP 세션 초기화 API는 클라이언트가 에이전트 보드와의 MCP(Model Context Protocol) 세션을 시작하는 기능을 제공합니다. 이 API는 initialize 메서드를 통해 고유한 세션 ID를 생성하고 반환하여, 이후 모든 MCP 통신에서 사용할 세션 식별자를 제공합니다.

주요 특징

MCP 표준 준수: initialize 메서드 지원
고유 세션 ID 생성: mcp-{uuid} 형태의 안전한 세션 식별자 제공
기존 세션 정리: 한 유저당 하나의 세션 보장을 위한 자동 정리
Redis 최적화: 단순화된 세션 관리 구조로 성능 향상

데이터 활용

생성된 세션 정보는 다음과 같은 용도로 활용됩니다:

세션 관리: 이후 모든 MCP 요청에서 세션 식별자로 사용
SSE 연결: Server-Sent Events 연결 시 Mcp-Session-Id 헤더로 사용
상태 추적: 세션 상태 확인 및 관리를 위한 기준값
리소스 격리: 사용자별 MCP 리소스 분리 및 관리
캐시 관리: Redis에 sse:user:session:{userId} 키로 저장

제약사항

유효한 액세스 토큰 필요
사용자 인증이 선행되어야 함
initialize 메서드 요청 필수
한 사용자당 하나의 활성 세션만 유지 (기존 세션 자동 삭제)
세션 유효기간: 24시간 (TTL)

세션 초기화

MCP 세션을 초기화하고 세션 ID를 생성합니다.

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

Headers

Header	Type	Description	Required
`Authorization`	`Bearer {accessToken}`	사용자 인증을 통해 발급받은 액세스 토큰입니다.	Yes
`Content-Type`	`application/json`	JSON-RPC 2.0 요청 형식을 지정합니다.	Yes
`Accept`	`application/json, text/event-stream`	응답 형식을 지정합니다. MCP 표준에 따라 두 형식 모두 포함해야 합니다.	Yes
`Accept-Language`	`de-DE`, `en-US`, `ko-KR`	오류 메시지의 언어를 지정합니다. 지역 코드를 포함한 형식(예: de-DE, en-US, ko-KR)만 지원합니다.	No

Request Body

initialize 메서드 요청을 전송해야 합니다.

{
  "method": "initialize"
}

필드	타입	설명	필수
`method`	string	MCP 메서드명 (반드시 "initialize")	Yes

Responses

HTTP Status Code	설명	Error Code(s)
`200 OK`	세션 초기화 성공	-
`400 Bad Request`	잘못된 요청 형식	`-32602`
`401 Unauthorized`	인증 실패 (유효하지 않은 액세스 토큰)	`10001`
`500 Internal Server Error`	서버 내부 오류	`-32603`

200 OK - 세션 초기화 성공

{
  "result": {
    "protocolVersion": "2025-03-26",
    "sessionId": "mcp-550e8400-e29b-41d4-a716-446655440000",
    "instructions": "Session initialized successfully. Use the provided sessionId for subsequent requests."
  }
}

필드	타입	설명	필수
`result`	object	응답 결과 객체	Yes
`protocolVersion`	string	서버가 지원하는 MCP 프로토콜 버전	Yes
`sessionId`	string	생성된 MCP 세션 고유 식별자 (`mcp-{uuid}`)	Yes
`instructions`	string	클라이언트를 위한 안내 메시지	Yes

Response Headers:

Header	Value	Description
`Mcp-Session-Id`	mcp-550e8400-e29b-41d4-a716-446655440000	생성된 세션 ID
`Content-Type`	application/json	응답 콘텐츠 타입

400 Bad Request - 잘못된 요청 형식

예시: 요청 형식 오류 (INVALID_REQUEST - 12000)

{
  "error": {
    "code": 12000,
    "message": "Invalid JSON-RPC request format",
    "data": "method field is required"
  }
}

401 Unauthorized - 인증 실패

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

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

500 Internal Server Error - 서버 내부 오류

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

{
  "error": {
    "code": 12001,
    "message": "Session initialization failed",
    "data": "Internal error processing request"
  }
}

설명

이 API는 MCP 세션을 시작하는 첫 번째 단계입니다.
요청 형식:
- initialize 메서드 요청 필수
- Content-Type: application/json 헤더 필수
- Accept: application/json, text/event-stream 헤더 필수
세션 ID 생성 방식:
- mcp-{uuid} 형태의 고유한 세션 식별자 생성
- 응답 헤더에 Mcp-Session-Id로 자동 설정
- 이후 모든 MCP 요청에서 이 세션 ID 사용 필요
세션 관리 최적화:
- 한 사용자당 하나의 활성 세션만 유지
- 새 세션 생성 시 기존 세션 자동 삭제
- Redis에 sse:user:session:{userId} 키로 효율적 저장
표준 준수:
- 간소화된 JSON 형식 사용
- MCP 프로토콜 버전 정보 포함
후속 작업:
- 세션 초기화 후 SSE 연결을 위해 GET 요청 사용
- 세션 상태 확인을 위해 ping API 사용
- 세션 종료를 위해 DELETE 요청 사용
보안 고려사항:
- 유효한 액세스 토큰 필수
- 사용자별 세션 격리 보장
- UUID 기반의 예측 불가능한 세션 ID
- 24시간 자동 만료 (TTL)
사용 사례:
- 앱 시작 시 MCP 세션 초기화
- 세션 만료 후 재초기화
- 새로운 사용자 로그인 시 세션 생성
- MCP 기능 사용 전 필수 선행 작업

개요​

주요 특징​

데이터 활용​

제약사항​

세션 초기화​

Headers​

Request Body​

Responses​

설명​

개요