MCP 클라이언트

Model Context Protocol 클라이언트

MCP 클라이언트는 Model Context Protocol(MCP) 아키텍처의 핵심 구성 요소로, MCP 서버와의 연결을 수립하고 관리합니다. 즉, 프로토콜의 클라이언트 측을 구현하며 다음을 처리합니다:

서버 호환성을 위한 프로토콜 버전 협상
사용 가능한 기능을 결정하는 capability 협상
메시지 전송(transport) 및 JSON-RPC 통신
도구(tools) 탐색 및 실행
리소스(resources) 접근 및 관리
프롬프트(prompts) 시스템 상호작용
루트(roots) 관리, 샘플링(sampling) 지원 같은 선택 기능

클라이언트는 다양한 애플리케이션 컨텍스트에 맞게 동기/비동기 API를 모두 제공합니다.

// Create a sync client with custom configuration
McpSyncClient client = McpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // Enable roots capability
        .sampling()       // Enable sampling capability
        .build())
    .sampling(request -> new CreateMessageResult(response))
    .build();

// Initialize connection
client.initialize();

// List available tools
ListToolsResult tools = client.listTools();

// Call a tool
CallToolResult result = client.callTool(
    new CallToolRequest("calculator", 
        Map.of("operation", "add", "a", 2, "b", 3))
);

// Create an async client with custom configuration
McpAsyncClient client = McpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // Enable roots capability
        .sampling()       // Enable sampling capability
        .build())
    .sampling(request -> Mono.just(new CreateMessageResult(response)))
    .build();

Client Transport

전송(transport) 레이어는 MCP 클라이언트와 서버 간 통신을 담당하며, 다양한 유스케이스를 위한 여러 구현을 제공합니다. 클라이언트 전송은 메시지 직렬화/역직렬화, 연결 수립, 프로토콜 특화 통신 패턴을 관리합니다.

프로세스 기반 통신을 위한 전송 생성

ServerParameters params = ServerParameters.builder("npx")
    .args("-y", "@modelcontextprotocol/server-everything", "dir")
    .build();
McpTransport transport = new StdioClientTransport(params);

프레임워크에 의존하지 않는(pure Java API) SSE 클라이언트 전송을 생성합니다. 코어 mcp 모듈에 포함되어 있습니다.

McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");

WebFlux 기반 SSE 클라이언트 전송을 생성합니다. mcp-webflux-sse-transport 의존성이 필요합니다.

WebClient.Builder webClientBuilder = WebClient.builder()
    .baseUrl("http://your-mcp-server");
McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);

Client Capabilities

클라이언트는 다양한 capability로 구성할 수 있습니다:

var capabilities = ClientCapabilities.builder()
    .roots(true)      // Enable filesystem roots support with list changes notifications
    .sampling()       // Enable LLM sampling support
    .build();

Roots Support

Roots는 서버가 파일 시스템에서 작업할 수 있는 범위를 정의합니다:

// Add a root dynamically
client.addRoot(new Root("file:///path", "description"));

// Remove a root
client.removeRoot("file:///path");

// Notify server of roots changes
client.rootsListChangedNotification();

roots capability를 통해 서버는 다음을 수행할 수 있습니다:

접근 가능한 파일 시스템 루트 목록 요청
루트 목록이 바뀔 때 알림 수신
접근 가능한 디렉터리/파일 범위 이해

Sampling Support

샘플링(sampling)은 서버가 클라이언트를 통해 LLM 상호작용(“completions” 또는 “generations”)을 요청할 수 있게 합니다:

// Configure sampling handler
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
    // Sampling implementation that interfaces with LLM
    return new CreateMessageResult(response);
};

// Create client with sampling support
var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .sampling()
        .build())
    .sampling(samplingHandler)
    .build();

이 capability는 다음을 가능하게 합니다:

서버가 API 키 없이도 AI 기능을 활용
클라이언트가 모델 접근 및 권한을 통제
텍스트/이미지 기반 상호작용 모두 지원
프롬프트에 MCP 서버 컨텍스트를 선택적으로 포함

Using MCP Clients

Tool Execution

도구(tools)는 클라이언트가 탐색하고 실행할 수 있는 서버 측 함수입니다. MCP 클라이언트는 사용 가능한 도구 목록을 조회하고, 특정 파라미터로 실행하는 메서드를 제공합니다. 각 도구는 고유한 이름을 가지며 파라미터는 맵(map) 형태로 전달합니다.

```java // List available tools and their names var tools = client.listTools(); tools.forEach(tool -> System.out.println(tool.getName()));

// Execute a tool with parameters var result = client.callTool(“calculator”, Map.of( “operation”, “add”, “a”, 1, “b”, 2 ));

  </Tab>

  <Tab title="비동기 API">
```java
// List available tools asynchronously
client.listTools()
    .doOnNext(tools -> tools.forEach(tool -> 
        System.out.println(tool.getName())))
    .subscribe();

// Execute a tool asynchronously
client.callTool("calculator", Map.of(
        "operation", "add",
        "a", 1,
        "b", 2
    ))
    .subscribe();

Resource Access

리소스(resources)는 클라이언트가 URI 템플릿을 통해 접근할 수 있는 서버 측 데이터 소스를 의미합니다. MCP 클라이언트는 표준화된 인터페이스로 리소스를 탐색하고 콘텐츠를 가져오는 메서드를 제공합니다.

```java // List available resources and their names var resources = client.listResources(); resources.forEach(resource -> System.out.println(resource.getName()));

// Retrieve resource content using a URI template var content = client.getResource(“file”, Map.of( “path”, “/path/to/file.txt” ));

  </Tab>

  <Tab title="비동기 API">
```java
// List available resources asynchronously
client.listResources()
    .doOnNext(resources -> resources.forEach(resource -> 
        System.out.println(resource.getName())))
    .subscribe();

// Retrieve resource content asynchronously
client.getResource("file", Map.of(
        "path", "/path/to/file.txt"
    ))
    .subscribe();

Prompt System

프롬프트(prompts) 시스템은 서버 측 프롬프트 템플릿과 상호작용할 수 있게 합니다. 템플릿은 탐색할 수 있으며, 커스텀 파라미터로 실행할 수 있어 사전 정의된 패턴을 기반으로 동적 텍스트 생성을 수행할 수 있습니다.

```java // List available prompt templates var prompts = client.listPrompts(); prompts.forEach(prompt -> System.out.println(prompt.getName()));

// Execute a prompt template with parameters var response = client.executePrompt(“echo”, Map.of( “text”, “Hello, World!” ));

  </Tab>

  <Tab title="비동기 API">
```java
// List available prompt templates asynchronously
client.listPrompts()
    .doOnNext(prompts -> prompts.forEach(prompt -> 
        System.out.println(prompt.getName())))
    .subscribe();

// Execute a prompt template asynchronously
client.executePrompt("echo", Map.of(
        "text", "Hello, World!"
    ))
    .subscribe();

MCP 서버