MCP 클라이언트 구현 완벽 가이드

Model Context Protocol 클라이언트를 Java/Spring 환경에서 구현하는 방법을 다룹니다. 서버 디스커버리부터 멀티 서버 관리까지 실무에서 바로 사용할 수 있는 패턴을 학습합니다.

1. MCP 클라이언트 아키텍처

김개발 씨는 최근 AI 에이전트 프로젝트에 투입되었습니다. 팀장님이 "MCP 클라이언트를 구현해 봐"라고 했는데, 도대체 어디서부터 시작해야 할지 막막했습니다.

서버와 통신하고, 도구를 호출하고, 응답을 처리하는 것까지... 복잡해 보이는 이 구조를 어떻게 체계적으로 설계할 수 있을까요?

MCP 클라이언트 아키텍처는 AI 모델이 외부 도구와 소통하기 위한 중앙 관제탑입니다. 마치 공항의 관제탑이 수많은 비행기의 이착륙을 조율하듯, MCP 클라이언트는 여러 서버와의 연결, 도구 호출, 응답 처리를 일관된 방식으로 관리합니다.

이 아키텍처를 이해하면 확장 가능하고 유지보수하기 쉬운 AI 통합 시스템을 구축할 수 있습니다.

다음 코드를 살펴봅시다.

// MCP 클라이언트의 핵심 구조를 정의합니다
public class McpClient {
    private final McpTransport transport;
    private final ToolRegistry toolRegistry;
    private final ResponseHandler responseHandler;

    // 클라이언트 초기화 - 전송 계층과 레지스트리 설정
    public McpClient(McpClientConfig config) {
        this.transport = createTransport(config.getTransportType());
        this.toolRegistry = new ToolRegistry();
        this.responseHandler = new ResponseHandler();
    }

    // 서버와 연결하고 사용 가능한 도구 목록을 가져옵니다
    public CompletableFuture<Void> connect(String serverUri) {
        return transport.connect(serverUri)
            .thenCompose(v -> discoverTools())
            .thenAccept(tools -> toolRegistry.registerAll(tools));
    }
}

김개발 씨는 입사 6개월 차 백엔드 개발자입니다. 최근 회사에서 AI 기반 고객 서비스 시스템을 구축하게 되었는데, 여러 외부 서비스와 연동해야 하는 상황이었습니다.

데이터베이스 조회, 이메일 발송, 재고 확인까지... 이 모든 것을 AI가 자연스럽게 사용할 수 있어야 했습니다.

팀장 박시니어 씨가 화이트보드 앞에 섰습니다. "MCP 클라이언트를 제대로 설계하려면 먼저 전체 그림을 이해해야 해요." 그렇다면 MCP 클라이언트 아키텍처란 정확히 무엇일까요?

쉽게 비유하자면, MCP 클라이언트는 마치 대형 호텔의 컨시어지 데스크와 같습니다. 고객이 "맛집 예약해 주세요"라고 하면, 컨시어지는 어떤 레스토랑에 연락해야 하는지 알고, 적절한 방식으로 예약을 요청하며, 결과를 고객에게 전달합니다.

MCP 클라이언트도 AI 모델의 요청을 받아 적절한 서버에 전달하고 결과를 돌려주는 역할을 합니다. MCP 클라이언트가 없던 시절에는 어땠을까요?

개발자들은 각 외부 서비스마다 별도의 연동 코드를 작성해야 했습니다. 데이터베이스 연동 코드, 이메일 API 코드, 재고 시스템 코드가 모두 제각각이었습니다.

새로운 서비스가 추가될 때마다 AI 모델 코드를 수정해야 했고, 이는 유지보수의 악몽이었습니다. 바로 이런 문제를 해결하기 위해 MCP가 등장했습니다.

MCP 클라이언트의 아키텍처는 세 가지 핵심 컴포넌트로 구성됩니다. 첫째, **전송 계층(Transport)**은 서버와의 실제 통신을 담당합니다.

HTTP, WebSocket, stdio 등 다양한 방식을 지원합니다. 둘째, **도구 레지스트리(Tool Registry)**는 사용 가능한 모든 도구의 정보를 관리합니다.

셋째, **응답 핸들러(Response Handler)**는 서버로부터 받은 응답을 처리합니다. 위의 코드를 살펴보겠습니다.

생성자에서는 설정에 따라 적절한 전송 계층을 생성합니다. 이렇게 하면 나중에 통신 방식을 바꾸더라도 클라이언트 코드를 수정할 필요가 없습니다.

connect 메서드는 비동기로 동작하며, 연결 후 자동으로 사용 가능한 도구를 검색하여 등록합니다. 실제 현업에서는 이 아키텍처를 어떻게 활용할까요?

예를 들어 고객 서비스 챗봇을 만든다고 가정해봅시다. 주문 조회 서버, 배송 추적 서버, FAQ 서버가 각각 MCP 프로토콜을 지원한다면, 하나의 MCP 클라이언트로 이 모든 서버와 통신할 수 있습니다.

AI 모델은 "주문 상태 확인해 줘"라는 요청을 받으면 클라이언트를 통해 적절한 도구를 호출합니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수는 모든 로직을 하나의 클래스에 몰아넣는 것입니다. 전송, 도구 관리, 응답 처리를 분리하지 않으면 나중에 테스트하기도 어렵고 확장하기도 힘들어집니다.

반드시 관심사 분리 원칙을 지켜야 합니다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다.

"아, 그래서 인터페이스를 분리하는 거군요!" MCP 클라이언트 아키텍처를 제대로 이해하면, 확장 가능하고 테스트하기 쉬운 AI 통합 시스템을 구축할 수 있습니다.

실전 팁

💡 - 전송 계층은 인터페이스로 추상화하여 나중에 교체 가능하게 설계하세요

비동기 패턴(CompletableFuture)을 사용하여 블로킹 없이 여러 서버와 통신하세요
클라이언트 설정은 외부 파일로 분리하여 환경별로 관리하세요

2. 서버 디스커버리

김개발 씨가 MCP 클라이언트의 기본 구조를 잡고 나니, 다음 문제가 생겼습니다. "서버가 어떤 도구를 제공하는지 어떻게 알 수 있지?" 서버마다 제공하는 기능이 다른데, 일일이 문서를 보고 하드코딩하는 건 너무 비효율적으로 느껴졌습니다.

서버 디스커버리는 MCP 서버가 제공하는 도구, 리소스, 프롬프트 목록을 자동으로 탐색하는 과정입니다. 마치 새로운 도시에 도착해서 관광 안내소에서 지도와 명소 정보를 받는 것처럼, 클라이언트는 연결 직후 서버에게 "무엇을 할 수 있나요?"라고 물어봅니다.

이를 통해 런타임에 동적으로 기능을 파악할 수 있습니다.

다음 코드를 살펴봅시다.

// 서버 디스커버리를 담당하는 클래스입니다
public class ServerDiscovery {
    private final McpTransport transport;

    // 서버의 capabilities를 조회합니다
    public CompletableFuture<ServerCapabilities> initialize() {
        InitializeRequest request = new InitializeRequest(
            "my-client", "1.0.0",  // 클라이언트 정보
            ClientCapabilities.builder().build()
        );
        return transport.send("initialize", request)
            .thenApply(response -> response.as(ServerCapabilities.class));
    }

    // 사용 가능한 모든 도구 목록을 가져옵니다
    public CompletableFuture<List<Tool>> listTools() {
        return transport.send("tools/list", new ListToolsRequest())
            .thenApply(response -> response.as(ToolListResult.class).getTools());
    }
}

김개발 씨는 고민에 빠졌습니다. 현재 연동해야 할 MCP 서버가 5개인데, 각 서버가 제공하는 도구가 수십 개에 달했습니다.

이걸 모두 코드에 하드코딩해야 할까요? 박시니어 씨가 웃으며 말했습니다.

"서버 디스커버리라는 게 있어요. 서버한테 직접 물어보면 돼요." 서버 디스커버리란 정확히 무엇일까요?

쉽게 비유하자면, 서버 디스커버리는 마치 스마트폰의 블루투스 검색 기능과 같습니다. 블루투스를 켜면 주변에 연결 가능한 기기가 자동으로 나타나죠.

각 기기가 "나는 스피커야", "나는 키보드야"라고 자신을 소개합니다. MCP 서버도 마찬가지로 "나는 이런 도구들을 제공해"라고 클라이언트에게 알려줍니다.

서버 디스커버리가 없다면 어떤 문제가 생길까요? 개발자는 각 서버의 문서를 일일이 확인하고, 도구 정보를 코드에 직접 입력해야 합니다.

서버가 업데이트되어 새로운 도구가 추가되면? 클라이언트 코드도 함께 수정해야 합니다.

서버와 클라이언트가 강하게 결합되어 버리는 것입니다. MCP 프로토콜은 이 문제를 우아하게 해결합니다.

클라이언트가 서버에 연결하면 가장 먼저 initialize 요청을 보냅니다. 이 요청에서 클라이언트는 자신의 정보(이름, 버전)를 알리고, 서버는 자신이 지원하는 기능(capabilities)을 응답합니다.

그 다음 tools/list 요청으로 구체적인 도구 목록을 가져옵니다. 코드를 자세히 살펴보겠습니다.

initialize 메서드에서는 클라이언트 이름과 버전을 포함한 요청을 보냅니다. 서버는 자신이 도구 호출을 지원하는지, 리소스를 제공하는지 등의 정보를 담아 응답합니다.

listTools 메서드는 실제로 사용 가능한 도구의 상세 정보를 가져옵니다. 각 도구의 이름, 설명, 파라미터 스키마가 모두 포함됩니다.

실무에서는 이 정보를 어떻게 활용할까요? AI 에이전트 프레임워크에서는 디스커버리로 얻은 도구 정보를 프롬프트에 자동으로 주입합니다.

AI 모델이 "사용 가능한 도구: 주문조회, 배송추적, 환불처리..."와 같은 정보를 보고 적절한 도구를 선택할 수 있게 되는 것입니다. 도구가 추가되거나 변경되어도 코드 수정 없이 자동으로 반영됩니다.

주의할 점이 있습니다. 디스커버리 결과를 캐싱하는 것이 좋습니다.

매번 도구 목록을 요청하면 불필요한 네트워크 비용이 발생합니다. 다만 서버가 동적으로 도구를 변경할 수 있다면, 주기적으로 갱신하거나 서버의 알림을 받는 구조를 고려해야 합니다.

김개발 씨는 감탄했습니다. "와, 이러면 서버가 업데이트되어도 클라이언트는 건드릴 필요가 없겠네요!" 서버 디스커버리를 활용하면 유연하고 확장 가능한 클라이언트를 구축할 수 있습니다.

실전 팁

💡 - 디스커버리 결과는 캐싱하되, TTL을 설정하여 주기적으로 갱신하세요

서버의 capabilities를 먼저 확인하고, 지원하는 기능만 사용하세요
도구 스키마 정보를 활용하여 요청 파라미터의 유효성을 미리 검증하세요

3. 도구 호출 인터페이스

서버가 어떤 도구를 제공하는지 알게 된 김개발 씨는 이제 실제로 도구를 호출해야 했습니다. "도구를 호출하는 건 그냥 API 호출이랑 비슷한 거 아닌가?" 그런데 막상 구현하려니 생각보다 고려할 게 많았습니다.

파라미터 검증, 타임아웃 처리, 에러 핸들링까지...

도구 호출 인터페이스는 MCP 서버의 도구를 실행하기 위한 표준화된 방법입니다. 마치 리모컨의 버튼을 누르면 TV가 원하는 동작을 하는 것처럼, 정해진 형식으로 요청을 보내면 서버가 해당 도구를 실행하고 결과를 반환합니다.

일관된 인터페이스 덕분에 어떤 서버의 어떤 도구든 같은 방식으로 호출할 수 있습니다.

다음 코드를 살펴봅시다.

// 도구 호출을 담당하는 서비스 클래스입니다
public class ToolInvoker {
    private final McpTransport transport;
    private final ToolRegistry registry;

    // 도구를 이름으로 호출합니다
    public CompletableFuture<ToolResult> invoke(String toolName, Map<String, Object> arguments) {
        // 도구 존재 여부 확인
        Tool tool = registry.getTool(toolName)
            .orElseThrow(() -> new ToolNotFoundException(toolName));

        // 요청 생성 및 전송
        CallToolRequest request = new CallToolRequest(toolName, arguments);
        return transport.send("tools/call", request)
            .thenApply(response -> parseToolResult(response))
            .exceptionally(ex -> ToolResult.error(ex.getMessage()));
    }
}

김개발 씨는 드디어 첫 번째 도구 호출을 시도했습니다. 주문 조회 도구에 주문 번호를 전달하면 주문 정보가 반환되어야 합니다.

그런데 처음 작성한 코드에서 에러가 발생했습니다. "Invalid tool name"이라니, 분명히 이름을 맞게 적은 것 같은데...

박시니어 씨가 코드를 보더니 말했습니다. "도구 호출 전에 레지스트리에서 확인하는 과정이 빠졌네요." 도구 호출 인터페이스란 무엇일까요?

쉽게 비유하자면, 도구 호출은 마치 음식 배달 앱에서 주문하는 것과 같습니다. 앱에서 메뉴를 선택하고(도구 이름), 옵션을 지정하고(파라미터), 주문 버튼을 누르면(호출), 잠시 후 음식이 도착합니다(결과).

MCP도 마찬가지로 tools/call이라는 표준 메서드로 모든 도구를 호출합니다. 도구 호출에서 가장 중요한 것은 일관성입니다.

MCP 프로토콜 덕분에 어떤 서버의 어떤 도구든 같은 방식으로 호출할 수 있습니다. 주문 조회 도구든, 이메일 발송 도구든, 날씨 조회 도구든 모두 동일한 형식의 요청을 사용합니다.

이것이 MCP의 핵심 가치입니다. 코드를 단계별로 살펴보겠습니다.

invoke 메서드는 먼저 레지스트리에서 해당 도구가 존재하는지 확인합니다. 존재하지 않는 도구를 호출하려 하면 즉시 예외가 발생합니다.

도구가 확인되면 CallToolRequest 객체를 생성하여 서버에 전송합니다. 응답이 오면 결과를 파싱하고, 에러가 발생하면 에러 결과로 변환합니다.

실무에서 도구 호출 시 고려할 점은 무엇일까요? 첫째, 파라미터 검증입니다.

디스커버리에서 얻은 스키마 정보를 활용하여 호출 전에 파라미터를 검증하면 불필요한 네트워크 요청을 줄일 수 있습니다. 둘째, 타임아웃 설정입니다.

외부 서버 호출은 언제든 지연될 수 있으므로 적절한 타임아웃을 설정해야 합니다. 셋째, 재시도 로직입니다.

일시적인 네트워크 문제로 실패한 경우 재시도하면 성공할 수 있습니다. AI 에이전트에서는 도구 호출이 어떻게 이루어질까요?

AI 모델이 "주문 12345의 상태를 확인해 줘"라는 사용자 요청을 받으면, 모델은 적절한 도구(예: getOrderStatus)를 선택하고 파라미터(orderId: "12345")를 생성합니다. 에이전트 프레임워크는 이 정보를 MCP 클라이언트에 전달하고, 클라이언트는 도구 호출 인터페이스를 통해 서버에 요청합니다.

주의해야 할 점이 있습니다. 도구 호출은 **부작용(side effect)**을 일으킬 수 있습니다.

이메일 발송, 데이터 수정, 결제 처리 같은 도구는 한 번 실행되면 되돌리기 어렵습니다. 따라서 AI가 이런 도구를 호출하기 전에 사용자 확인을 받는 것이 좋습니다.

김개발 씨는 레지스트리 확인 로직을 추가한 후 다시 실행했습니다. 이번에는 성공적으로 주문 정보가 반환되었습니다.

도구 호출 인터페이스를 잘 설계하면, 안정적이고 예측 가능한 AI 에이전트를 구축할 수 있습니다.

실전 팁

💡 - 호출 전 파라미터 스키마 검증으로 잘못된 요청을 사전에 차단하세요

타임아웃과 재시도 로직을 반드시 구현하세요
부작용이 있는 도구는 호출 전 사용자 확인 단계를 추가하세요

4. 응답 처리

김개발 씨가 도구 호출을 성공적으로 구현하고 나니, 새로운 고민이 생겼습니다. 서버에서 돌아오는 응답의 형태가 도구마다 제각각이었습니다.

어떤 건 텍스트, 어떤 건 JSON, 어떤 건 이미지... 이걸 어떻게 일관되게 처리할 수 있을까요?

MCP 응답 처리는 서버가 반환한 다양한 형태의 결과를 해석하고 활용하는 과정입니다. 마치 통역사가 여러 나라의 언어를 한국어로 번역해주는 것처럼, 응답 핸들러는 텍스트, 이미지, 임베딩 등 다양한 콘텐츠 타입을 일관된 방식으로 처리합니다.

이를 통해 AI 모델이 결과를 쉽게 이해하고 활용할 수 있습니다.

다음 코드를 살펴봅시다.

// 다양한 응답 타입을 처리하는 핸들러입니다
public class ResponseHandler {

    // 도구 실행 결과를 처리합니다
    public ProcessedResult handle(ToolResult result) {
        List<String> textContents = new ArrayList<>();
        List<byte[]> imageContents = new ArrayList<>();

        // 각 콘텐츠 타입별로 분류 처리
        for (Content content : result.getContent()) {
            switch (content.getType()) {
                case "text" -> textContents.add(content.getText());
                case "image" -> imageContents.add(decodeBase64(content.getData()));
                case "resource" -> textContents.add(fetchResource(content.getUri()));
            }
        }
        return new ProcessedResult(textContents, imageContents, result.isError());
    }
}

김개발 씨는 날씨 조회 도구를 호출했는데, 예상과 다른 응답이 돌아왔습니다. 단순한 텍스트가 아니라 텍스트 설명과 날씨 아이콘 이미지가 함께 포함된 복합 응답이었습니다.

"이걸 어떻게 처리하지?" 박시니어 씨가 설명했습니다. "MCP 응답은 여러 콘텐츠 블록으로 구성될 수 있어요.

각각을 적절히 처리해야 해요." MCP 응답의 구조는 어떻게 되어 있을까요? 쉽게 비유하자면, MCP 응답은 마치 택배 상자 안의 여러 물건과 같습니다.

하나의 상자(응답) 안에 책(텍스트), 사진(이미지), 영수증(메타데이터)이 함께 들어있을 수 있습니다. 상자를 열어서 각 물건을 종류별로 정리하는 것이 응답 처리입니다.

MCP 프로토콜은 세 가지 주요 콘텐츠 타입을 정의합니다. 첫째, text 타입은 가장 일반적인 형태로, 도구 실행의 텍스트 결과를 담습니다.

둘째, image 타입은 Base64로 인코딩된 이미지 데이터입니다. 차트, 그래프, 스크린샷 등을 반환할 때 사용됩니다.

셋째, resource 타입은 외부 리소스에 대한 참조입니다. URI를 통해 별도로 내용을 가져와야 합니다.

코드를 살펴보겠습니다. handle 메서드는 ToolResult에 포함된 모든 콘텐츠를 순회합니다.

각 콘텐츠의 타입을 확인하고 적절한 컬렉션에 분류합니다. 텍스트는 그대로 저장하고, 이미지는 Base64 디코딩을 거쳐 바이트 배열로 변환합니다.

리소스 타입의 경우 URI를 통해 실제 내용을 가져옵니다. AI 에이전트에서 응답 처리는 왜 중요할까요?

AI 모델은 처리된 결과를 바탕으로 다음 행동을 결정합니다. 만약 이미지 데이터가 제대로 처리되지 않으면 모델이 시각적 정보를 활용할 수 없습니다.

또한 에러 응답을 적절히 감지하지 못하면 모델이 잘못된 정보를 기반으로 답변할 수 있습니다. 실무에서 흔히 마주치는 상황이 있습니다.

데이터베이스 조회 도구는 보통 JSON 형태의 텍스트를 반환합니다. 이 경우 텍스트를 한 번 더 파싱하여 구조화된 데이터로 변환하면 활용하기 편합니다.

또한 도구가 에러를 반환했을 때 isError 플래그를 확인하여 적절히 처리해야 합니다. 주의할 점도 있습니다.

이미지 데이터는 크기가 클 수 있으므로 메모리 관리에 신경 써야 합니다. 불필요하게 큰 이미지를 메모리에 유지하면 OutOfMemoryError가 발생할 수 있습니다.

필요한 경우 이미지를 파일로 저장하고 경로만 유지하는 방식을 고려하세요. 김개발 씨는 응답 핸들러를 구현한 후 날씨 조회 결과를 깔끔하게 처리할 수 있게 되었습니다.

텍스트 설명은 AI 모델에게 전달하고, 이미지는 사용자에게 직접 보여주었습니다. 응답 처리를 체계적으로 구현하면, 다양한 도구의 결과를 유연하게 활용할 수 있습니다.

실전 팁

💡 - 에러 응답(isError: true)을 반드시 확인하고 적절히 처리하세요

이미지 데이터는 메모리 사용량을 고려하여 필요시 파일로 저장하세요
JSON 형태의 텍스트 응답은 추가 파싱하여 구조화하면 활용도가 높아집니다

5. 연결 관리

김개발 씨의 MCP 클라이언트가 어느 정도 완성되어 갔습니다. 그런데 테스트 중 이상한 현상을 발견했습니다.

가끔 서버와의 연결이 끊어지면 클라이언트가 그대로 멈춰버리는 것이었습니다. "연결 관리를 제대로 하지 않으면 실서비스에서 큰 문제가 되겠군요."

연결 관리는 MCP 서버와의 연결 수명 주기를 관리하는 것입니다. 마치 전화 통화에서 연결 상태를 확인하고, 끊어지면 다시 거는 것처럼, MCP 클라이언트도 연결 상태를 모니터링하고 문제 발생 시 적절히 대응해야 합니다.

안정적인 연결 관리는 프로덕션 환경에서 필수적입니다.

다음 코드를 살펴봅시다.

// 연결 관리를 담당하는 매니저 클래스입니다
public class ConnectionManager {
    private final McpTransport transport;
    private final ScheduledExecutorService scheduler;
    private volatile ConnectionState state = ConnectionState.DISCONNECTED;

    // 연결 상태를 주기적으로 확인합니다
    public void startHealthCheck(Duration interval) {
        scheduler.scheduleAtFixedRate(() -> {
            if (state == ConnectionState.CONNECTED) {
                transport.ping().orTimeout(5, TimeUnit.SECONDS)
                    .exceptionally(ex -> {
                        handleDisconnection();
                        return null;
                    });
            }
        }, 0, interval.toMillis(), TimeUnit.MILLISECONDS);
    }

    // 재연결 로직 - 지수 백오프 적용
    private void reconnectWithBackoff(int attempt) {
        long delay = Math.min(1000 * (1L << attempt), 30000);
        scheduler.schedule(() -> attemptReconnect(), delay, TimeUnit.MILLISECONDS);
    }
}

김개발 씨는 개발 환경에서는 문제가 없었는데, 스테이징 환경에서 테스트하니 간헐적으로 연결 오류가 발생했습니다. 네트워크가 불안정한 상황을 시뮬레이션하니 클라이언트가 무한 대기 상태에 빠지기도 했습니다.

박시니어 씨가 진지하게 말했습니다. "프로덕션에서는 네트워크 문제가 일상이에요.

연결 관리를 튼튼하게 해야 해요." 연결 관리란 정확히 무엇을 의미할까요? 쉽게 비유하자면, 연결 관리는 마치 자동차의 계기판과 같습니다.

연료가 부족하면 경고등이 켜지고, 엔진에 문제가 생기면 알려줍니다. MCP 클라이언트도 마찬가지로 서버와의 연결 상태를 지속적으로 모니터링하고, 문제가 생기면 적절히 대응해야 합니다.

연결 관리에는 세 가지 핵심 요소가 있습니다. 첫째, **헬스체크(Health Check)**입니다.

주기적으로 서버에 ping을 보내 연결이 살아있는지 확인합니다. 둘째, 연결 해제 감지입니다.

헬스체크 실패나 통신 오류를 통해 연결이 끊어졌음을 인식합니다. 셋째, 재연결 로직입니다.

연결이 끊어지면 자동으로 다시 연결을 시도합니다. 코드를 살펴보겠습니다.

startHealthCheck 메서드는 설정된 간격으로 ping을 전송합니다. 5초 내에 응답이 없으면 타임아웃으로 처리하고 handleDisconnection을 호출합니다.

reconnectWithBackoff 메서드는 지수 백오프(Exponential Backoff) 전략을 사용합니다. 첫 번째 재시도는 1초 후, 두 번째는 2초 후, 세 번째는 4초 후...

이런 식으로 간격을 늘려갑니다. 최대 30초까지만 늘어납니다.

왜 지수 백오프를 사용할까요? 서버가 과부하 상태일 때 모든 클라이언트가 동시에 재연결을 시도하면 상황이 더 악화됩니다.

지수 백오프를 사용하면 재연결 시도가 분산되어 서버가 회복할 시간을 벌 수 있습니다. 이는 분산 시스템에서 널리 사용되는 안정성 패턴입니다.

실무에서 추가로 고려할 점이 있습니다. 연결 상태 변화를 구독할 수 있는 이벤트 메커니즘을 제공하면 좋습니다.

예를 들어 연결이 끊어지면 UI에 "재연결 중..." 메시지를 표시하고, 연결이 복구되면 "연결됨"으로 바꿀 수 있습니다. 또한 최대 재시도 횟수를 설정하여 무한 재시도를 방지해야 합니다.

주의할 점도 있습니다. 재연결 시 이전에 진행 중이던 요청의 상태를 적절히 처리해야 합니다.

연결이 끊어진 시점에 대기 중이던 요청들에게 에러를 반환하거나, 연결 복구 후 자동으로 재시도할지 결정해야 합니다. 김개발 씨는 연결 관리 로직을 추가한 후 스테이징 환경에서 다시 테스트했습니다.

네트워크가 불안정해도 클라이언트가 자동으로 재연결하며 안정적으로 동작했습니다. 연결 관리를 탄탄하게 구현하면, 어떤 네트워크 환경에서도 안정적인 서비스를 제공할 수 있습니다.

실전 팁

💡 - 헬스체크 간격은 너무 짧으면 오버헤드가 크고, 너무 길면 감지가 느립니다. 10-30초가 적당합니다

지수 백오프에 약간의 랜덤 지터(jitter)를 추가하면 동시 재연결을 더 효과적으로 분산시킬 수 있습니다
최대 재시도 횟수를 설정하고, 초과 시 관리자에게 알림을 보내세요

6. 실전: 멀티 서버 클라이언트

김개발 씨의 프로젝트가 점점 커지면서 연동해야 할 MCP 서버가 늘어났습니다. 주문 서버, 재고 서버, 배송 서버, 고객 서버...

각각 별도의 클라이언트를 만들어야 할까요? 아니면 하나의 클라이언트로 모든 서버를 관리할 수 있을까요?

멀티 서버 클라이언트는 여러 MCP 서버와 동시에 연결하여 통합 관리하는 패턴입니다. 마치 리모컨 하나로 TV, 에어컨, 조명을 모두 조작하는 것처럼, 단일 인터페이스로 여러 서버의 도구를 호출할 수 있습니다.

AI 에이전트가 다양한 외부 서비스를 활용해야 할 때 필수적인 구조입니다.

다음 코드를 살펴봅시다.

// 여러 MCP 서버를 통합 관리하는 클라이언트입니다
public class MultiServerMcpClient {
    private final Map<String, McpClient> clients = new ConcurrentHashMap<>();
    private final Map<String, String> toolToServerMap = new ConcurrentHashMap<>();

    // 서버를 등록하고 연결합니다
    public CompletableFuture<Void> addServer(String serverId, String uri) {
        McpClient client = new McpClient(createConfig(uri));
        clients.put(serverId, client);

        return client.connect(uri)
            .thenCompose(v -> client.listTools())
            .thenAccept(tools -> tools.forEach(tool ->
                toolToServerMap.put(tool.getName(), serverId)));
    }

    // 도구 이름으로 적절한 서버를 찾아 호출합니다
    public CompletableFuture<ToolResult> invokeTool(String toolName, Map<String, Object> args) {
        String serverId = toolToServerMap.get(toolName);
        if (serverId == null) throw new ToolNotFoundException(toolName);
        return clients.get(serverId).invoke(toolName, args);
    }
}

김개발 씨는 처음에 서버마다 별도의 클라이언트 인스턴스를 생성했습니다. 그런데 AI 모델에게 도구 목록을 전달할 때 문제가 생겼습니다.

어떤 도구가 어떤 서버에 있는지 일일이 관리해야 했고, 도구 호출 시에도 서버를 명시해야 했습니다. 박시니어 씨가 제안했습니다.

"멀티 서버 클라이언트 패턴을 써보세요. AI 입장에서는 서버 구분 없이 도구 이름만으로 호출할 수 있어요." 멀티 서버 클라이언트의 핵심 아이디어는 무엇일까요?

쉽게 비유하자면, 멀티 서버 클라이언트는 마치 대형 백화점의 안내 데스크와 같습니다. 고객이 "운동화 사고 싶어요"라고 하면, 안내 데스크에서 스포츠 용품 매장 위치를 알려줍니다.

"화장품 보러 왔어요"라고 하면 1층 화장품 매장으로 안내합니다. 고객은 어느 층 어느 매장인지 몰라도 됩니다.

멀티 서버 클라이언트도 마찬가지로 도구 이름만 알면 적절한 서버로 라우팅해줍니다. 이 패턴의 핵심 구성 요소는 두 가지입니다.

첫째, 서버 레지스트리입니다. 서버 ID와 클라이언트 인스턴스를 매핑합니다.

둘째, 도구-서버 매핑입니다. 각 도구가 어떤 서버에 속하는지 기록합니다.

서버를 추가할 때 자동으로 해당 서버의 도구 목록을 가져와 매핑을 구성합니다. 코드를 자세히 살펴보겠습니다.

addServer 메서드는 새로운 서버를 등록합니다. 연결이 완료되면 해당 서버의 도구 목록을 가져와 toolToServerMap에 등록합니다.

이제 도구 이름만으로 어떤 서버에 있는지 알 수 있습니다. invokeTool 메서드는 도구 이름을 받아 적절한 서버의 클라이언트를 찾고 호출을 위임합니다.

AI 에이전트에서 이 패턴이 왜 유용할까요? AI 모델에게는 "getOrderStatus, checkInventory, trackShipment, getCustomerInfo" 같은 도구 목록만 전달하면 됩니다.

모델이 "checkInventory" 도구를 선택하면, 멀티 서버 클라이언트가 자동으로 재고 서버에 요청을 보냅니다. 서버 구조의 복잡성이 AI 모델에게 노출되지 않습니다. 실무에서 고려할 추가 사항이 있습니다.

첫째, 도구 이름 충돌 문제입니다. 서로 다른 서버에 같은 이름의 도구가 있을 수 있습니다.

이 경우 네임스페이스를 도입하거나(예: "order.getStatus", "inventory.getStatus"), 먼저 등록된 것을 우선하는 정책을 정해야 합니다. 둘째, 서버 장애 처리입니다.

특정 서버가 다운되면 해당 서버의 도구만 비활성화하고 나머지는 계속 서비스할 수 있어야 합니다. 주의할 점도 있습니다.

서버가 많아지면 초기 연결 시간이 길어질 수 있습니다. 병렬로 연결을 시도하거나, 지연 로딩(lazy loading)을 적용하여 필요할 때 연결하는 방식을 고려하세요.

또한 전체 도구 목록이 커지면 AI 모델의 도구 선택 정확도가 떨어질 수 있으므로, 상황에 따라 관련 도구만 노출하는 것도 방법입니다. 김개발 씨는 멀티 서버 클라이언트를 구현한 후 코드가 훨씬 깔끔해졌습니다.

AI 모델 코드에서는 서버에 대한 언급이 사라지고, 순수하게 "어떤 도구를 호출할지"에만 집중할 수 있게 되었습니다. 박시니어 씨가 코드 리뷰를 마치며 말했습니다.

"이제 새 서버가 추가되어도 addServer 한 줄이면 끝이네요. 잘 만들었어요!" 멀티 서버 클라이언트 패턴을 활용하면, 복잡한 서버 구조도 깔끔하게 추상화할 수 있습니다.

실전 팁

💡 - 도구 이름 충돌을 방지하기 위해 서버별 네임스페이스 사용을 권장합니다

서버 연결은 병렬로 수행하여 초기화 시간을 단축하세요
서버 장애 시 해당 서버의 도구만 비활성화하고, 다른 서버는 정상 운영되도록 설계하세요

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

#MCP#Spring AI#Tool Calling#Protocol Client#Server Discovery#Spring,AI,MCP

MCP 클라이언트 구현 완벽 가이드

# MCP 클라이언트 구현 완벽 가이드 Model Context Protocol 클라이언트를 Java/Spring 환경에서 구현하는 방법을 다룹니다. 서버 디스커버리부터 멀티 서버 관리까지 실무에서 바로 사용할 수 있는 패턴을 학습합니다. --- ## 목차 1. [MCP 클라이언트 아키텍처](#mcp-클라이언트-아키텍처) 2. [서버 디스커버리](#서버-디스커버리) 3. [도구 호출 인터페이스](#도구-호출-인터페이스) 4. [응답 처리](#응답-처리) 5. [연결 관리](#연결-관리) 6. [실전: 멀티 서버 클라이언트](#실전:-멀티-서버-클라이언트) --- ## 1. MCP 클라이언트 아키텍처 김개발 씨는 최근 AI 에이전트 프로젝트에 투입되었습니다. 팀장님이 "MCP 클라이언트를 구현해 봐"라고 했는데, 도대체 어디서부터 시작해야 할지 막막했습니다. 서버와 통신하고, 도구를 호출하고, 응답을 처리하는 것까지... 복잡해 보이는 이 구조를 어떻게 체계적으로 설계할 수 있을까요? MCP 클라이언트 아키텍처는 AI 모델이 외부 도구와 소통하기 위한 중앙 관제탑입니다. 마치 공항의 관제탑이 수많은 비행기의 이착륙을 조율하듯, MCP 클라이언트는 여러 서버와의 연결, 도구 호출, 응답 처리를 일관된 방식으로 관리합니다. 이 아키텍처를 이해하면 확장 가능하고 유지보수하기 쉬운 AI 통합 시스템을 구축할 수 있습니다. 다음 코드를 살펴봅시다. ```java // MCP 클라이언트의 핵심 구조를 정의합니다 public class McpClient { private final McpTransport transport; private final ToolRegistry toolRegistry; private final ResponseHandler responseHandler; // 클라이언트 초기화 - 전송 계층과 레지스트리 설정 public McpClient(McpClientConfig config) { this.transport = createTransport(config.getTransportType()); this.toolRegistry = new ToolRegistry(); this.responseHandler = new ResponseHandler(); } // 서버와 연결하고 사용 가능한 도구 목록을 가져옵니다 public CompletableFuture connect(String serverUri) { return transport.connect(serverUri) .thenCompose(v -> discoverTools()) .thenAccept(tools -> toolRegistry.registerAll(tools)); } } ``` 김개발 씨는 입사 6개월 차 백엔드 개발자입니다. 최근 회사에서 AI 기반 고객 서비스 시스템을 구축하게 되었는데, 여러 외부 서비스와 연동해야 하는 상황이었습니다. 데이터베이스 조회, 이메일 발송, 재고 확인까지... 이 모든 것을 AI가 자연스럽게 사용할 수 있어야 했습니다. 팀장 박시니어 씨가 화이트보드 앞에 섰습니다. "MCP 클라이언트를 제대로 설계하려면 먼저 전체 그림을 이해해야 해요." 그렇다면 MCP 클라이언트 아키텍처란 정확히 무엇일까요? 쉽게 비유하자면, MCP 클라이언트는 마치 대형 호텔의 **컨시어지 데스크**와 같습니다. 고객이 "맛집 예약해 주세요"라고 하면, 컨시어지는 어떤 레스토랑에 연락해야 하는지 알고, 적절한 방식으로 예약을 요청하며, 결과를 고객에게 전달합니다. MCP 클라이언트도 AI 모델의 요청을 받아 적절한 서버에 전달하고 결과를 돌려주는 역할을 합니다. MCP 클라이언트가 없던 시절에는 어땠을까요? 개발자들은 각 외부 서비스마다 별도의 연동 코드를 작성해야 했습니다. 데이터베이스 연동 코드, 이메일 API 코드, 재고 시스템 코드가 모두 제각각이었습니다. 새로운 서비스가 추가될 때마다 AI 모델 코드를 수정해야 했고, 이는 유지보수의 악몽이었습니다. 바로 이런 문제를 해결하기 위해 MCP가 등장했습니다. MCP 클라이언트의 아키텍처는 세 가지 핵심 컴포넌트로 구성됩니다. 첫째, **전송 계층(Transport)**은 서버와의 실제 통신을 담당합니다. HTTP, WebSocket, stdio 등 다양한 방식을 지원합니다. 둘째, **도구 레지스트리(Tool Registry)**는 사용 가능한 모든 도구의 정보를 관리합니다. 셋째, **응답 핸들러(Response Handler)**는 서버로부터 받은 응답을 처리합니다. 위의 코드를 살펴보겠습니다. 생성자에서는 설정에 따라 적절한 전송 계층을 생성합니다. 이렇게 하면 나중에 통신 방식을 바꾸더라도 클라이언트 코드를 수정할 필요가 없습니다. connect 메서드는 비동기로 동작하며, 연결 후 자동으로 사용 가능한 도구를 검색하여 등록합니다. 실제 현업에서는 이 아키텍처를 어떻게 활용할까요? 예를 들어 고객 서비스 챗봇을 만든다고 가정해봅시다. 주문 조회 서버, 배송 추적 서버, FAQ 서버가 각각 MCP 프로토콜을 지원한다면, 하나의 MCP 클라이언트로 이 모든 서버와 통신할 수 있습니다. AI 모델은 "주문 상태 확인해 줘"라는 요청을 받으면 클라이언트를 통해 적절한 도구를 호출합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수는 모든 로직을 하나의 클래스에 몰아넣는 것입니다. 전송, 도구 관리, 응답 처리를 분리하지 않으면 나중에 테스트하기도 어렵고 확장하기도 힘들어집니다. 반드시 **관심사 분리 원칙**을 지켜야 합니다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다. "아, 그래서 인터페이스를 분리하는 거군요!" MCP 클라이언트 아키텍처를 제대로 이해하면, 확장 가능하고 테스트하기 쉬운 AI 통합 시스템을 구축할 수 있습니다. **실전 팁** 💡 - 전송 계층은 인터페이스로 추상화하여 나중에 교체 가능하게 설계하세요 - 비동기 패턴(CompletableFuture)을 사용하여 블로킹 없이 여러 서버와 통신하세요 - 클라이언트 설정은 외부 파일로 분리하여 환경별로 관리하세요 --- ## 2. 서버 디스커버리 김개발 씨가 MCP 클라이언트의 기본 구조를 잡고 나니, 다음 문제가 생겼습니다. "서버가 어떤 도구를 제공하는지 어떻게 알 수 있지?" 서버마다 제공하는 기능이 다른데, 일일이 문서를 보고 하드코딩하는 건 너무 비효율적으로 느껴졌습니다. 서버 디스커버리는 MCP 서버가 제공하는 도구, 리소스, 프롬프트 목록을 자동으로 탐색하는 과정입니다. 마치 새로운 도시에 도착해서 관광 안내소에서 지도와 명소 정보를 받는 것처럼, 클라이언트는 연결 직후 서버에게 "무엇을 할 수 있나요?"라고 물어봅니다. 이를 통해 런타임에 동적으로 기능을 파악할 수 있습니다. 다음 코드를 살펴봅시다. ```java // 서버 디스커버리를 담당하는 클래스입니다 public class ServerDiscovery { private final McpTransport transport; // 서버의 capabilities를 조회합니다 public CompletableFuture initialize() { InitializeRequest request = new InitializeRequest( "my-client", "1.0.0", // 클라이언트 정보 ClientCapabilities.builder().build() ); return transport.send("initialize", request) .thenApply(response -> response.as(ServerCapabilities.class)); } // 사용 가능한 모든 도구 목록을 가져옵니다 public CompletableFuture > listTools() { return transport.send("tools/list", new ListToolsRequest()) .thenApply(response -> response.as(ToolListResult.class).getTools()); } } ``` 김개발 씨는 고민에 빠졌습니다. 현재 연동해야 할 MCP 서버가 5개인데, 각 서버가 제공하는 도구가 수십 개에 달했습니다. 이걸 모두 코드에 하드코딩해야 할까요? 박시니어 씨가 웃으며 말했습니다. "서버 디스커버리라는 게 있어요. 서버한테 직접 물어보면 돼요." 서버 디스커버리란 정확히 무엇일까요? 쉽게 비유하자면, 서버 디스커버리는 마치 **스마트폰의 블루투스 검색** 기능과 같습니다. 블루투스를 켜면 주변에 연결 가능한 기기가 자동으로 나타나죠. 각 기기가 "나는 스피커야", "나는 키보드야"라고 자신을 소개합니다. MCP 서버도 마찬가지로 "나는 이런 도구들을 제공해"라고 클라이언트에게 알려줍니다. 서버 디스커버리가 없다면 어떤 문제가 생길까요? 개발자는 각 서버의 문서를 일일이 확인하고, 도구 정보를 코드에 직접 입력해야 합니다. 서버가 업데이트되어 새로운 도구가 추가되면? 클라이언트 코드도 함께 수정해야 합니다. 서버와 클라이언트가 **강하게 결합**되어 버리는 것입니다. MCP 프로토콜은 이 문제를 우아하게 해결합니다. 클라이언트가 서버에 연결하면 가장 먼저 **initialize** 요청을 보냅니다. 이 요청에서 클라이언트는 자신의 정보(이름, 버전)를 알리고, 서버는 자신이 지원하는 기능(capabilities)을 응답합니다. 그 다음 **tools/list** 요청으로 구체적인 도구 목록을 가져옵니다. 코드를 자세히 살펴보겠습니다. initialize 메서드에서는 클라이언트 이름과 버전을 포함한 요청을 보냅니다. 서버는 자신이 도구 호출을 지원하는지, 리소스를 제공하는지 등의 정보를 담아 응답합니다. listTools 메서드는 실제로 사용 가능한 도구의 상세 정보를 가져옵니다. 각 도구의 이름, 설명, 파라미터 스키마가 모두 포함됩니다. 실무에서는 이 정보를 어떻게 활용할까요? AI 에이전트 프레임워크에서는 디스커버리로 얻은 도구 정보를 **프롬프트에 자동으로 주입**합니다. AI 모델이 "사용 가능한 도구: 주문조회, 배송추적, 환불처리..."와 같은 정보를 보고 적절한 도구를 선택할 수 있게 되는 것입니다. 도구가 추가되거나 변경되어도 코드 수정 없이 자동으로 반영됩니다. 주의할 점이 있습니다. 디스커버리 결과를 **캐싱**하는 것이 좋습니다. 매번 도구 목록을 요청하면 불필요한 네트워크 비용이 발생합니다. 다만 서버가 동적으로 도구를 변경할 수 있다면, 주기적으로 갱신하거나 서버의 알림을 받는 구조를 고려해야 합니다. 김개발 씨는 감탄했습니다. "와, 이러면 서버가 업데이트되어도 클라이언트는 건드릴 필요가 없겠네요!" 서버 디스커버리를 활용하면 유연하고 확장 가능한 클라이언트를 구축할 수 있습니다. **실전 팁** 💡 - 디스커버리 결과는 캐싱하되, TTL을 설정하여 주기적으로 갱신하세요 - 서버의 capabilities를 먼저 확인하고, 지원하는 기능만 사용하세요 - 도구 스키마 정보를 활용하여 요청 파라미터의 유효성을 미리 검증하세요 --- ## 3. 도구 호출 인터페이스 서버가 어떤 도구를 제공하는지 알게 된 김개발 씨는 이제 실제로 도구를 호출해야 했습니다. "도구를 호출하는 건 그냥 API 호출이랑 비슷한 거 아닌가?" 그런데 막상 구현하려니 생각보다 고려할 게 많았습니다. 파라미터 검증, 타임아웃 처리, 에러 핸들링까지... 도구 호출 인터페이스는 MCP 서버의 도구를 실행하기 위한 표준화된 방법입니다. 마치 리모컨의 버튼을 누르면 TV가 원하는 동작을 하는 것처럼, 정해진 형식으로 요청을 보내면 서버가 해당 도구를 실행하고 결과를 반환합니다. 일관된 인터페이스 덕분에 어떤 서버의 어떤 도구든 같은 방식으로 호출할 수 있습니다. 다음 코드를 살펴봅시다. ```java // 도구 호출을 담당하는 서비스 클래스입니다 public class ToolInvoker { private final McpTransport transport; private final ToolRegistry registry; // 도구를 이름으로 호출합니다 public CompletableFuture invoke(String toolName, Map arguments) { // 도구 존재 여부 확인 Tool tool = registry.getTool(toolName) .orElseThrow(() -> new ToolNotFoundException(toolName)); // 요청 생성 및 전송 CallToolRequest request = new CallToolRequest(toolName, arguments); return transport.send("tools/call", request) .thenApply(response -> parseToolResult(response)) .exceptionally(ex -> ToolResult.error(ex.getMessage())); } } ``` 김개발 씨는 드디어 첫 번째 도구 호출을 시도했습니다. 주문 조회 도구에 주문 번호를 전달하면 주문 정보가 반환되어야 합니다. 그런데 처음 작성한 코드에서 에러가 발생했습니다. "Invalid tool name"이라니, 분명히 이름을 맞게 적은 것 같은데... 박시니어 씨가 코드를 보더니 말했습니다. "도구 호출 전에 레지스트리에서 확인하는 과정이 빠졌네요." 도구 호출 인터페이스란 무엇일까요? 쉽게 비유하자면, 도구 호출은 마치 **음식 배달 앱에서 주문하는 것**과 같습니다. 앱에서 메뉴를 선택하고(도구 이름), 옵션을 지정하고(파라미터), 주문 버튼을 누르면(호출), 잠시 후 음식이 도착합니다(결과). MCP도 마찬가지로 **tools/call**이라는 표준 메서드로 모든 도구를 호출합니다. 도구 호출에서 가장 중요한 것은 **일관성**입니다. MCP 프로토콜 덕분에 어떤 서버의 어떤 도구든 같은 방식으로 호출할 수 있습니다. 주문 조회 도구든, 이메일 발송 도구든, 날씨 조회 도구든 모두 동일한 형식의 요청을 사용합니다. 이것이 MCP의 핵심 가치입니다. 코드를 단계별로 살펴보겠습니다. invoke 메서드는 먼저 레지스트리에서 해당 도구가 존재하는지 확인합니다. 존재하지 않는 도구를 호출하려 하면 즉시 예외가 발생합니다. 도구가 확인되면 CallToolRequest 객체를 생성하여 서버에 전송합니다. 응답이 오면 결과를 파싱하고, 에러가 발생하면 에러 결과로 변환합니다. 실무에서 도구 호출 시 고려할 점은 무엇일까요? 첫째, **파라미터 검증**입니다. 디스커버리에서 얻은 스키마 정보를 활용하여 호출 전에 파라미터를 검증하면 불필요한 네트워크 요청을 줄일 수 있습니다. 둘째, **타임아웃 설정**입니다. 외부 서버 호출은 언제든 지연될 수 있으므로 적절한 타임아웃을 설정해야 합니다. 셋째, **재시도 로직**입니다. 일시적인 네트워크 문제로 실패한 경우 재시도하면 성공할 수 있습니다. AI 에이전트에서는 도구 호출이 어떻게 이루어질까요? AI 모델이 "주문 12345의 상태를 확인해 줘"라는 사용자 요청을 받으면, 모델은 적절한 도구(예: getOrderStatus)를 선택하고 파라미터(orderId: "12345")를 생성합니다. 에이전트 프레임워크는 이 정보를 MCP 클라이언트에 전달하고, 클라이언트는 도구 호출 인터페이스를 통해 서버에 요청합니다. 주의해야 할 점이 있습니다. 도구 호출은 **부작용(side effect)**을 일으킬 수 있습니다. 이메일 발송, 데이터 수정, 결제 처리 같은 도구는 한 번 실행되면 되돌리기 어렵습니다. 따라서 AI가 이런 도구를 호출하기 전에 사용자 확인을 받는 것이 좋습니다. 김개발 씨는 레지스트리 확인 로직을 추가한 후 다시 실행했습니다. 이번에는 성공적으로 주문 정보가 반환되었습니다. 도구 호출 인터페이스를 잘 설계하면, 안정적이고 예측 가능한 AI 에이전트를 구축할 수 있습니다. **실전 팁** 💡 - 호출 전 파라미터 스키마 검증으로 잘못된 요청을 사전에 차단하세요 - 타임아웃과 재시도 로직을 반드시 구현하세요 - 부작용이 있는 도구는 호출 전 사용자 확인 단계를 추가하세요 --- ## 4. 응답 처리 김개발 씨가 도구 호출을 성공적으로 구현하고 나니, 새로운 고민이 생겼습니다. 서버에서 돌아오는 응답의 형태가 도구마다 제각각이었습니다. 어떤 건 텍스트, 어떤 건 JSON, 어떤 건 이미지... 이걸 어떻게 일관되게 처리할 수 있을까요? MCP 응답 처리는 서버가 반환한 다양한 형태의 결과를 해석하고 활용하는 과정입니다. 마치 통역사가 여러 나라의 언어를 한국어로 번역해주는 것처럼, 응답 핸들러는 텍스트, 이미지, 임베딩 등 다양한 콘텐츠 타입을 일관된 방식으로 처리합니다. 이를 통해 AI 모델이 결과를 쉽게 이해하고 활용할 수 있습니다. 다음 코드를 살펴봅시다. ```java // 다양한 응답 타입을 처리하는 핸들러입니다 public class ResponseHandler { // 도구 실행 결과를 처리합니다 public ProcessedResult handle(ToolResult result) { List textContents = new ArrayList (); List imageContents = new ArrayList (); // 각 콘텐츠 타입별로 분류 처리 for (Content content : result.getContent()) { switch (content.getType()) { case "text" -> textContents.add(content.getText()); case "image" -> imageContents.add(decodeBase64(content.getData())); case "resource" -> textContents.add(fetchResource(content.getUri())); } } return new ProcessedResult(textContents, imageContents, result.isError()); } } ``` 김개발 씨는 날씨 조회 도구를 호출했는데, 예상과 다른 응답이 돌아왔습니다. 단순한 텍스트가 아니라 텍스트 설명과 날씨 아이콘 이미지가 함께 포함된 복합 응답이었습니다. "이걸 어떻게 처리하지?" 박시니어 씨가 설명했습니다. "MCP 응답은 여러 **콘텐츠 블록**으로 구성될 수 있어요. 각각을 적절히 처리해야 해요." MCP 응답의 구조는 어떻게 되어 있을까요? 쉽게 비유하자면, MCP 응답은 마치 **택배 상자 안의 여러 물건**과 같습니다. 하나의 상자(응답) 안에 책(텍스트), 사진(이미지), 영수증(메타데이터)이 함께 들어있을 수 있습니다. 상자를 열어서 각 물건을 종류별로 정리하는 것이 응답 처리입니다. MCP 프로토콜은 세 가지 주요 콘텐츠 타입을 정의합니다. 첫째, **text** 타입은 가장 일반적인 형태로, 도구 실행의 텍스트 결과를 담습니다. 둘째, **image** 타입은 Base64로 인코딩된 이미지 데이터입니다. 차트, 그래프, 스크린샷 등을 반환할 때 사용됩니다. 셋째, **resource** 타입은 외부 리소스에 대한 참조입니다. URI를 통해 별도로 내용을 가져와야 합니다. 코드를 살펴보겠습니다. handle 메서드는 ToolResult에 포함된 모든 콘텐츠를 순회합니다. 각 콘텐츠의 타입을 확인하고 적절한 컬렉션에 분류합니다. 텍스트는 그대로 저장하고, 이미지는 Base64 디코딩을 거쳐 바이트 배열로 변환합니다. 리소스 타입의 경우 URI를 통해 실제 내용을 가져옵니다. AI 에이전트에서 응답 처리는 왜 중요할까요? AI 모델은 처리된 결과를 바탕으로 다음 행동을 결정합니다. 만약 이미지 데이터가 제대로 처리되지 않으면 모델이 시각적 정보를 활용할 수 없습니다. 또한 에러 응답을 적절히 감지하지 못하면 모델이 잘못된 정보를 기반으로 답변할 수 있습니다. 실무에서 흔히 마주치는 상황이 있습니다. 데이터베이스 조회 도구는 보통 JSON 형태의 텍스트를 반환합니다. 이 경우 텍스트를 한 번 더 파싱하여 구조화된 데이터로 변환하면 활용하기 편합니다. 또한 도구가 에러를 반환했을 때 isError 플래그를 확인하여 적절히 처리해야 합니다. 주의할 점도 있습니다. 이미지 데이터는 크기가 클 수 있으므로 메모리 관리에 신경 써야 합니다. 불필요하게 큰 이미지를 메모리에 유지하면 OutOfMemoryError가 발생할 수 있습니다. 필요한 경우 이미지를 파일로 저장하고 경로만 유지하는 방식을 고려하세요. 김개발 씨는 응답 핸들러를 구현한 후 날씨 조회 결과를 깔끔하게 처리할 수 있게 되었습니다. 텍스트 설명은 AI 모델에게 전달하고, 이미지는 사용자에게 직접 보여주었습니다. 응답 처리를 체계적으로 구현하면, 다양한 도구의 결과를 유연하게 활용할 수 있습니다. **실전 팁** 💡 - 에러 응답(isError: true)을 반드시 확인하고 적절히 처리하세요 - 이미지 데이터는 메모리 사용량을 고려하여 필요시 파일로 저장하세요 - JSON 형태의 텍스트 응답은 추가 파싱하여 구조화하면 활용도가 높아집니다 --- ## 5. 연결 관리 김개발 씨의 MCP 클라이언트가 어느 정도 완성되어 갔습니다. 그런데 테스트 중 이상한 현상을 발견했습니다. 가끔 서버와의 연결이 끊어지면 클라이언트가 그대로 멈춰버리는 것이었습니다. "연결 관리를 제대로 하지 않으면 실서비스에서 큰 문제가 되겠군요." 연결 관리는 MCP 서버와의 연결 수명 주기를 관리하는 것입니다. 마치 전화 통화에서 연결 상태를 확인하고, 끊어지면 다시 거는 것처럼, MCP 클라이언트도 연결 상태를 모니터링하고 문제 발생 시 적절히 대응해야 합니다. 안정적인 연결 관리는 프로덕션 환경에서 필수적입니다. 다음 코드를 살펴봅시다. ```java // 연결 관리를 담당하는 매니저 클래스입니다 public class ConnectionManager { private final McpTransport transport; private final ScheduledExecutorService scheduler; private volatile ConnectionState state = ConnectionState.DISCONNECTED; // 연결 상태를 주기적으로 확인합니다 public void startHealthCheck(Duration interval) { scheduler.scheduleAtFixedRate(() -> { if (state == ConnectionState.CONNECTED) { transport.ping().orTimeout(5, TimeUnit.SECONDS) .exceptionally(ex -> { handleDisconnection(); return null; }); } }, 0, interval.toMillis(), TimeUnit.MILLISECONDS); } // 재연결 로직 - 지수 백오프 적용 private void reconnectWithBackoff(int attempt) { long delay = Math.min(1000 * (1L attemptReconnect(), delay, TimeUnit.MILLISECONDS); } } ``` 김개발 씨는 개발 환경에서는 문제가 없었는데, 스테이징 환경에서 테스트하니 간헐적으로 연결 오류가 발생했습니다. 네트워크가 불안정한 상황을 시뮬레이션하니 클라이언트가 무한 대기 상태에 빠지기도 했습니다. 박시니어 씨가 진지하게 말했습니다. "프로덕션에서는 네트워크 문제가 일상이에요. 연결 관리를 튼튼하게 해야 해요." 연결 관리란 정확히 무엇을 의미할까요? 쉽게 비유하자면, 연결 관리는 마치 **자동차의 계기판**과 같습니다. 연료가 부족하면 경고등이 켜지고, 엔진에 문제가 생기면 알려줍니다. MCP 클라이언트도 마찬가지로 서버와의 연결 상태를 지속적으로 모니터링하고, 문제가 생기면 적절히 대응해야 합니다. 연결 관리에는 세 가지 핵심 요소가 있습니다. 첫째, **헬스체크(Health Check)**입니다. 주기적으로 서버에 ping을 보내 연결이 살아있는지 확인합니다. 둘째, **연결 해제 감지**입니다. 헬스체크 실패나 통신 오류를 통해 연결이 끊어졌음을 인식합니다. 셋째, **재연결 로직**입니다. 연결이 끊어지면 자동으로 다시 연결을 시도합니다. 코드를 살펴보겠습니다. startHealthCheck 메서드는 설정된 간격으로 ping을 전송합니다. 5초 내에 응답이 없으면 타임아웃으로 처리하고 handleDisconnection을 호출합니다. reconnectWithBackoff 메서드는 **지수 백오프(Exponential Backoff)** 전략을 사용합니다. 첫 번째 재시도는 1초 후, 두 번째는 2초 후, 세 번째는 4초 후... 이런 식으로 간격을 늘려갑니다. 최대 30초까지만 늘어납니다. 왜 지수 백오프를 사용할까요? 서버가 과부하 상태일 때 모든 클라이언트가 동시에 재연결을 시도하면 상황이 더 악화됩니다. 지수 백오프를 사용하면 재연결 시도가 분산되어 서버가 회복할 시간을 벌 수 있습니다. 이는 분산 시스템에서 널리 사용되는 **안정성 패턴**입니다. 실무에서 추가로 고려할 점이 있습니다. 연결 상태 변화를 구독할 수 있는 **이벤트 메커니즘**을 제공하면 좋습니다. 예를 들어 연결이 끊어지면 UI에 "재연결 중..." 메시지를 표시하고, 연결이 복구되면 "연결됨"으로 바꿀 수 있습니다. 또한 최대 재시도 횟수를 설정하여 무한 재시도를 방지해야 합니다. 주의할 점도 있습니다. 재연결 시 이전에 진행 중이던 요청의 상태를 적절히 처리해야 합니다. 연결이 끊어진 시점에 대기 중이던 요청들에게 에러를 반환하거나, 연결 복구 후 자동으로 재시도할지 결정해야 합니다. 김개발 씨는 연결 관리 로직을 추가한 후 스테이징 환경에서 다시 테스트했습니다. 네트워크가 불안정해도 클라이언트가 자동으로 재연결하며 안정적으로 동작했습니다. 연결 관리를 탄탄하게 구현하면, 어떤 네트워크 환경에서도 안정적인 서비스를 제공할 수 있습니다. **실전 팁** 💡 - 헬스체크 간격은 너무 짧으면 오버헤드가 크고, 너무 길면 감지가 느립니다. 10-30초가 적당합니다 - 지수 백오프에 약간의 랜덤 지터(jitter)를 추가하면 동시 재연결을 더 효과적으로 분산시킬 수 있습니다 - 최대 재시도 횟수를 설정하고, 초과 시 관리자에게 알림을 보내세요 --- ## 6. 실전: 멀티 서버 클라이언트 김개발 씨의 프로젝트가 점점 커지면서 연동해야 할 MCP 서버가 늘어났습니다. 주문 서버, 재고 서버, 배송 서버, 고객 서버... 각각 별도의 클라이언트를 만들어야 할까요? 아니면 하나의 클라이언트로 모든 서버를 관리할 수 있을까요? 멀티 서버 클라이언트는 여러 MCP 서버와 동시에 연결하여 통합 관리하는 패턴입니다. 마치 리모컨 하나로 TV, 에어컨, 조명을 모두 조작하는 것처럼, 단일 인터페이스로 여러 서버의 도구를 호출할 수 있습니다. AI 에이전트가 다양한 외부 서비스를 활용해야 할 때 필수적인 구조입니다. 다음 코드를 살펴봅시다. ```java // 여러 MCP 서버를 통합 관리하는 클라이언트입니다 public class MultiServerMcpClient { private final Map clients = new ConcurrentHashMap (); private final Map toolToServerMap = new ConcurrentHashMap (); // 서버를 등록하고 연결합니다 public CompletableFuture addServer(String serverId, String uri) { McpClient client = new McpClient(createConfig(uri)); clients.put(serverId, client); return client.connect(uri) .thenCompose(v -> client.listTools()) .thenAccept(tools -> tools.forEach(tool -> toolToServerMap.put(tool.getName(), serverId))); } // 도구 이름으로 적절한 서버를 찾아 호출합니다 public CompletableFuture invokeTool(String toolName, Map args) { String serverId = toolToServerMap.get(toolName); if (serverId == null) throw new ToolNotFoundException(toolName); return clients.get(serverId).invoke(toolName, args); } } ``` 김개발 씨는 처음에 서버마다 별도의 클라이언트 인스턴스를 생성했습니다. 그런데 AI 모델에게 도구 목록을 전달할 때 문제가 생겼습니다. 어떤 도구가 어떤 서버에 있는지 일일이 관리해야 했고, 도구 호출 시에도 서버를 명시해야 했습니다. 박시니어 씨가 제안했습니다. "멀티 서버 클라이언트 패턴을 써보세요. AI 입장에서는 서버 구분 없이 도구 이름만으로 호출할 수 있어요." 멀티 서버 클라이언트의 핵심 아이디어는 무엇일까요? 쉽게 비유하자면, 멀티 서버 클라이언트는 마치 **대형 백화점의 안내 데스크**와 같습니다. 고객이 "운동화 사고 싶어요"라고 하면, 안내 데스크에서 스포츠 용품 매장 위치를 알려줍니다. "화장품 보러 왔어요"라고 하면 1층 화장품 매장으로 안내합니다. 고객은 어느 층 어느 매장인지 몰라도 됩니다. 멀티 서버 클라이언트도 마찬가지로 도구 이름만 알면 적절한 서버로 라우팅해줍니다. 이 패턴의 핵심 구성 요소는 두 가지입니다. 첫째, **서버 레지스트리**입니다. 서버 ID와 클라이언트 인스턴스를 매핑합니다. 둘째, **도구-서버 매핑**입니다. 각 도구가 어떤 서버에 속하는지 기록합니다. 서버를 추가할 때 자동으로 해당 서버의 도구 목록을 가져와 매핑을 구성합니다. 코드를 자세히 살펴보겠습니다. addServer 메서드는 새로운 서버를 등록합니다. 연결이 완료되면 해당 서버의 도구 목록을 가져와 toolToServerMap에 등록합니다. 이제 도구 이름만으로 어떤 서버에 있는지 알 수 있습니다. invokeTool 메서드는 도구 이름을 받아 적절한 서버의 클라이언트를 찾고 호출을 위임합니다. AI 에이전트에서 이 패턴이 왜 유용할까요? AI 모델에게는 "getOrderStatus, checkInventory, trackShipment, getCustomerInfo" 같은 도구 목록만 전달하면 됩니다. 모델이 "checkInventory" 도구를 선택하면, 멀티 서버 클라이언트가 자동으로 재고 서버에 요청을 보냅니다. **서버 구조의 복잡성이 AI 모델에게 노출되지 않습니다.** 실무에서 고려할 추가 사항이 있습니다. 첫째, **도구 이름 충돌** 문제입니다. 서로 다른 서버에 같은 이름의 도구가 있을 수 있습니다. 이 경우 네임스페이스를 도입하거나(예: "order.getStatus", "inventory.getStatus"), 먼저 등록된 것을 우선하는 정책을 정해야 합니다. 둘째, **서버 장애 처리**입니다. 특정 서버가 다운되면 해당 서버의 도구만 비활성화하고 나머지는 계속 서비스할 수 있어야 합니다. 주의할 점도 있습니다. 서버가 많아지면 초기 연결 시간이 길어질 수 있습니다. 병렬로 연결을 시도하거나, 지연 로딩(lazy loading)을 적용하여 필요할 때 연결하는 방식을 고려하세요. 또한 전체 도구 목록이 커지면 AI 모델의 도구 선택 정확도가 떨어질 수 있으므로, 상황에 따라 관련 도구만 노출하는 것도 방법입니다. 김개발 씨는 멀티 서버 클라이언트를 구현한 후 코드가 훨씬 깔끔해졌습니다. AI 모델 코드에서는 서버에 대한 언급이 사라지고, 순수하게 "어떤 도구를 호출할지"에만 집중할 수 있게 되었습니다. 박시니어 씨가 코드 리뷰를 마치며 말했습니다. "이제 새 서버가 추가되어도 addServer 한 줄이면 끝이네요. 잘 만들었어요!" 멀티 서버 클라이언트 패턴을 활용하면, 복잡한 서버 구조도 깔끔하게 추상화할 수 있습니다. **실전 팁** 💡 - 도구 이름 충돌을 방지하기 위해 서버별 네임스페이스 사용을 권장합니다 - 서버 연결은 병렬로 수행하여 초기화 시간을 단축하세요 - 서버 장애 시 해당 서버의 도구만 비활성화하고, 다른 서버는 정상 운영되도록 설계하세요 --- 이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

카테고리: Spring,AI,MCP

언어: Java

태그: MCP, Spring AI, Tool Calling, Protocol Client, Server Discovery, Spring,AI,MCP

작성자: AI Generated

프리미엄 콘텐츠 - 3개월 무료 체험 가능

CodeDeck

MCP 클라이언트 구현 완벽 가이드

목차

1. MCP 클라이언트 아키텍처

2. 서버 디스커버리

3. 도구 호출 인터페이스

4. 응답 처리

5. 연결 관리

6. 실전: 멀티 서버 클라이언트

이 카드뉴스가 포함된 코스

Spring AI 완전 정복 - 실전 AI 애플리케이션 개발

댓글 (0)

함께 보면 좋은 카드 뉴스

실전 MCP 통합 프로젝트 완벽 가이드

MCP 동적 도구 업데이트 완벽 가이드

MCP Sampling 완벽 가이드

MCP 어노테이션 기반 개발 완벽 가이드

MCP 서버 구현 STDIO 완벽 가이드