개발 및 IT운영

MCP 도구 상자 Java SDK v1.0 발표: 엔터프라이즈를 위한 에이전트형 데이터 액세스

2026년 10월 14일

https://storage.googleapis.com/gweb-cloudblog-publish/images/announcing-mcp-toolbox-java-sdk-v10-agenti.max-1300x1300.png

Abirami Sukumaran

Staff Developer Advocate, Google

공동 저자:
Stenal Jolly, Strategic Cloud Engineer, Google
Anubhav Dhawan, Software Engineer, Google

*이 콘텐츠는 AI 번역 도구를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역에는 오류나 누락이 포함될 수 있습니다. 정확한 정보는 영문 원본을 참고해 주시기 바랍니다.

MCP 도구 상자 v1.0의 획기적인 발표에 이어 MCP 도구 상자 Java SDK가 공식적으로 버전 1.0에 도달했음을 발표합니다.

이번 출시를 통해 세계에서 가장 널리 채택된 엔터프라이즈 생태계 중 하나에 최고 수준의 유형 안전성 에이전트 조정 기능이 도입되었습니다. Java의 성숙한 아키텍처는 엄격한 요구사항을 충족하도록 특별히 설계되어 프로덕션 환경에서 미션 크리티컬 AI 에이전트를 안전하게 확장하는 데 필요한 높은 동시 실행성, 엄격한 트랜잭션 무결성, 강력한 상태 관리 기능을 제공합니다.

이 글에서는 Java SDK v1.0의 새로운 기능을 소개하고, 실제 사례를 살펴보며, 자체 구현을 시작하는 데 도움을 드립니다.

MCP: 범용 인터페이스

오늘날 개발자들은 통합 병목 현상이라는 복합적인 문제에 직면해 있습니다. N개의 서로 다른 AI 모델과 M개의 엔터프라이즈 데이터 소스가 있다면 N × M개의 맞춤형 커스텀 연결을 빌드하고, 보안을 유지하고, 유지보수해야 합니다. 이러한 통합 레이어의 부재로 인해 엔지니어링팀은 단편화된 임시 파이프라인 웹에 의존할 수밖에 없습니다. 그 결과 에이전트형 아키텍처를 확장하는 것은 금세 지속 불가능해지며, 민감한 엔터프라이즈 데이터베이스가 심각한 보안 취약점, 단편화된 액세스 제어, 막대한 유지보수 오버헤드에 노출됩니다.

모델 컨텍스트 프로토콜(MCP)은 파편화된 커스텀 통합 웹을 제거하여 핵심 문제를 해결합니다. AI 조정을 위한 'USB 타입-C'와 같은 범용 인터페이스 역할을 하는 MCP는 모델을 데이터 소스로부터 분리합니다. 개발자는 새로운 모델이나 데이터베이스마다 커스텀 또는 관리형 API 통합 코드를 작성하는 대신, 표준화된 단일 프로토콜에 맞게 코드를 작성합니다. 이 접근 방식을 사용하면 모든 MCP 호환 에이전트가 모든 MCP 지원 시스템과 안전하고 즉각적으로 상호작용할 수 있습니다. MCP 연결을 사용하면 개발자가 새로운 모델마다 맞춤형 통합을 빌드하지 않고도 에이전트를 실제 시스템에 연결할 수 있습니다.

Java SDK v1.0의 새로운 기능: 프로덕션 워크로드를 위해 빌드

MCP 도구 상자 Java SDK의 공개 베타를 발표했을 때 Google의 목표는 엔터프라이즈 Java 환경에 최고 수준의 유형 안전성 에이전트 조정 기능을 제공하는 것이었습니다. 그 이후로 Google은 개발자 및 오픈소스 참여자와 협력하여 API를 강화해 왔습니다.

v1.0 출시는 엔터프라이즈 워크로드에 적합한 안정적이고 하위 호환성이 보장되는 기반을 마련했습니다. v0.2 출시 이후 새롭게 추가되고 강화된 기능은 다음과 같습니다.

전송 계층 추상화 및 HttpMcpTransport: HttpMcpTransport와 함께 깔끔한 전송 계층 추상화를 도입했습니다. 이 기능은 핵심 프로토콜 로직을 기본 HTTP 클라이언트에서 분리하여 네트워크 구현을 쉽게 교체하거나 연결 풀링을 맞춤설정할 수 있도록 합니다.
분리된 클라이언트 인증: 기업 보안 규정 준수를 간소화하기 위해 이제 CredentialsProvider 및 AuthMethods 클래스를 사용하여 클라이언트 인증이 분리됩니다. 사용자 인증 정보는 모든 요청에서 비동기식으로 해결되므로 팀에서 토큰을 동적으로 새로고침하거나 자체 토큰 소스를 연결할 수 있습니다(ADC를 통한 Google OIDC는 기본 제공되며, 그 외의 모든 것은 단일 메서드 인터페이스로 구현됨).
기본 파라미터 지원: 도구 파라미터의 기본값을 네이티브로 지원하여 프롬프트 페이로드 크기를 줄이고 에이전트 안정성을 향상합니다.
바인딩된 파라미터 가지치기: 서버 측에 바인딩된 민감한 파라미터(예: tenant_id)가 이제 노출된 도구 정의에서 자동으로 제거되므로 LLM이 이를 조작할 수 없습니다.
버전 선택 및 세션 추적: 표준화된 MCP 버전 선택과 강력한 세션 추적을 통해 일관된 프로토콜 협상과 대화 상태 수명 주기를 보장합니다.
HTTP 사용자 인증 정보 노출 경고: 사용자 인증 정보가 일반 텍스트 HTTP 연결을 통해 전송되려고 할 때 런타임에 경고하는 기본 제공 감지 기능이 추가되었습니다.
일반 클라이언트 헤더 맵: 커스텀 기업 프록시 헤더, 트랜잭션 추적 ID 또는 상관관계 메타데이터를 모든 발신 요청에 쉽게 연결할 수 있습니다.

Java SDK v1.0 시작하기

MCP 도구 상자 Java SDK는 엔터프라이즈 팀이 원활하게 사용할 수 있도록 설계했습니다. pom.xml에 다음 종속 항목을 추가하기만 하면 됩니다.

로드 중...

실제 사례: 자율 교통 컨시어지

AlloyDB와 결합된 Java SDK의 강력한 기능을 알아보기 위해 엔터프라이즈 사용 사례를 살펴보겠습니다.

가상의 시외버스 네트워크인 Cymbal Transit을 소개합니다. 고객은 여행 계획을 세우기 위해 중첩된 드롭다운 메뉴를 하나하나 클릭하고 싶어 하지 않습니다. 고객은 다음과 같이 질문합니다.

"내일 아침에 뉴욕에서 보스턴으로 가야 해. 내 골든 리트리버를 데려갈 수 있을까? 그렇다면 가장 빠른 항공편을 예약해 줘."

이 질문에 답하려면 AI 에이전트가 비정형 데이터(반려동물 정책)와 정형 데이터(시간표 및 좌석 현황)를 상호 참조하고 트랜잭션(예약)을 실행해야 하며, 이 모든 과정에서 대화의 컨텍스트를 유지해야 합니다.

기반: 네이티브 임베딩이 포함된 AlloyDB 스키마

이 구현에는 AlloyDB를 사용했습니다. AlloyDB는 관계형 데이터와 고차원 벡터를 네이티브로 처리하기 때문입니다. 다음 문을 사용하여 데이터베이스 테이블을 설정하세요.

lang-sql

로드 중...

-- Enable necessary extensions for semantic search and embeddings
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS google_ml_integration;

-- Table 1: Transit Policies (Unstructured Data for RAG)
CREATE TABLE transit_policies (
    policy_id SERIAL PRIMARY KEY,
    category VARCHAR(50),
    policy_text TEXT,
    policy_embedding vector(768)
);

-- Table 2: Intercity Bus Schedules (Structured Data)
CREATE TABLE bus_schedules (
    trip_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    origin_city VARCHAR(100),
    destination_city VARCHAR(100),
    departure_time TIMESTAMP,
    arrival_time TIMESTAMP,
    available_seats INT DEFAULT 50,
    ticket_price DECIMAL(6,2)
);

-- Table 3: Booking Ledger (Transactional Action Data)
CREATE TABLE bookings (
    booking_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    trip_id UUID REFERENCES bus_schedules(trip_id),
    passenger_id VARCHAR(100),
    status VARCHAR(20) DEFAULT 'CONFIRMED',
    booking_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

인텐트를 SQL에 매핑: `tools.yaml`

MCP 도구 상자를 사용하면 커스텀 도구를 안전하게 정의할 수 있습니다. LLM에 직접적인 데이터베이스 액세스 권한을 부여하는 대신 tools.yaml 구성을 통해 자연어 인텐트를 파라미터화된 안전한 쿼리에 직접 매핑합니다.

로드 중...

전체 YAML 파일은 mcp-toolbox-sdk-java 저장소의 tools.yaml 파일을 참고하세요.

Spring Boot의 스테이트풀(Stateful) 에이전트 아키텍처

엔터프라이즈 애플리케이션에서 대화형 AI를 빌드할 때 가장 어려운 부분은 상태 관리입니다. 사용자가 "몇 시에 예약할 수 있나요?"라고 물은 다음 "오전 8시로 예약해 주세요"라고 말하면 에이전트는 대화가 진행되는 동안 이전 컨텍스트를 기억해야 합니다.

Spring Boot 및 LangChain4j와 함께 Java MCP 도구 상자 SDK를 사용하면 HTTP 세션에서 대화 메모리를 깔끔하게 유지하고 에이전트를 두 개의 선언적 구성요소로 깔끔하게 분리할 수 있습니다.

HTTP 세션을 통해 프롬프트, 도구, 대화 메모리를 관리하는 선언적 에이전트 인터페이스입니다.
에이전트 요청을 MCP 도구 상자 서버로 직접 라우팅하는 도구 실행 서비스입니다.

로드 중...

@MemoryId 주석이 세션 추적을 어떻게 추상화하는지 확인하세요. Spring Boot는 대화 컨텍스트를 사용자의 HTTP 세션에 자동으로 연결합니다. 한편 LangChain4j와 MCP 도구 상자는 백그라운드에서 스키마 변환과 도구 라우팅을 처리하므로 수동으로 if/else 인텐트 파싱을 작성할 필요가 없습니다.

MCP 도구 상자 Java SDK를 LangChain4j와 결합하면 관심사를 명확하게 분리하고 상태를 손쉽게 관리할 수 있습니다.

상용구 없는 세션 관리: @MemoryId String sessionId 파라미터는 대화 기록을 사용자의 HTTP 세션에 직접 바인딩합니다.
선언적 에이전트 계약: TransitAgent 인터페이스는 복잡한 프롬프트 템플릿 없이 모델의 페르소나와 시스템 요청 사항을 정의합니다.
유형 안전성 도구 실행: TransitAgentTools Spring 서비스는 원격 MCP 데이터베이스 도구를 네이티브 Java 메서드로 래핑합니다.

이 아키텍처는 에이전트의 모듈성을 유지합니다. 인터페이스에서 프롬프트 가이드를 미세 조정하고, 사용자 세션을 자동으로 관리하며, 긴밀한 결합 없이 MCP 도구 상자를 통해 안전한 데이터베이스 쿼리를 실행할 수 있습니다.

전체적 그림 보기: Java v1.0에서 도구 나열, 호출, 실행

이제 TransitAgentTools 인터페이스를 자세히 살펴보겠습니다. Spring @Service의 LangChain4j @Tool 메서드 내에서 MCP 도구 상자 Java SDK는 Java 서비스 메서드를 tools.yaml 파일에 정의된 MCP 도구에 연결하는 까다로운 작업을 처리합니다. 몇 줄의 유형 안전성 코드로 새로운 v1.0 분리된 인증 및 헤더 추상화를 사용하여 클라이언트를 초기 설정할 수 있습니다.

로드 중...

// 1. Initialize the Client with Decoupled Auth and Custom Headers (v1.0)
String serviceUrl = "https://toolbox-my-project-uc.a.run.app/mcp";
McpToolboxClient mcpClient = McpToolboxClient.builder()
    .baseUrl(serviceUrl)
    .credentialsProvider(new GoogleCredentialsProvider(serviceUrl)) // Decoupled OIDC credentials
    .headers(Map.of( // Generic client headers
        "X-Correlation-ID", "enterprise-session-abc123",
        "X-Client-Platform", "Spring-Boot"
    ))
    .build();

// 2. Listing Discoverable Tools
mcpClient.listTools().thenAccept(tools -> {
    System.out.println("Successfully discovered " + tools.size() + " tools.");
});

// 3. Invoking a Tool (Read-Only Data with Default Parameter Support)
// "limit" is omitted: the SDK fills it from the default in the tool definition
String schedules = mcpClient.loadTool("query-schedules")
    .thenCompose(tool -> tool.execute(Map.of(
        "origin", "New York",
        "destination", "Boston")))
    .join().text();

// 4. Executing a Transactional Tool (Using Bound Parameters)
AuthTokenGetter toolAuthGetter = () -> CompletableFuture.completedFuture(myIdToken);

String bookingConfirmation = mcpClient.loadTool("book-ticket", Map.of("google_auth", toolAuthGetter))
    // Bind the authenticated user context securely. bindParam returns a new immutable
    // Tool, and the bound parameter is pruned from the definition exposed to the LLM!
    .thenCompose(tool -> tool.bindParam("passenger_name", "Jane Doe")
        // Execute the mutable transaction
        .execute(Map.of("trip_id", "123e4567-e89b-12d3-a456-426614174000")))
    .join().text();

보안을 우선으로 하는 기본 설정: 인증 및 배포

AI 에이전트를 프로덕션으로 이전하려면 견고한 사용자 인증 정보 처리와 수요에 따라 확장가능한 인프라가 필요합니다. 다양한 환경에서 사용자 인증 정보 보안을 적용하고 Cloud Run에 독립적으로 배포하는 방법을 살펴보겠습니다.

애플리케이션 기본 사용자 인증 정보(ADC) 및 안전

GoogleCredentialsProvider 서비스를 사용하면 Java 앱이 애플리케이션 기본 사용자 인증 정보(ADC)를 통해 실행 환경(로컬 또는 Google Cloud)에서 보안 ID를 상속합니다. 하드 코딩된 키가 필요 없으며, OIDC 토큰이 잠재고객별로 생성되고 캐시됩니다. 또한 v1.0은 사용자 인증 정보가 일반 텍스트 HTTP 연결을 통해 전송되려고 할 때 이를 자동으로 감지하고 HTTPS로 전환하라는 런타임 경고를 내보내는 HTTP 사용자 인증 정보 노출 경고를 제공합니다.

Cloud Run에 Fleet 배포

MCP 도구 상자와 Spring Boot 에이전트는 완전히 분리되어 있으므로 Google Cloud Run에서 독립적으로 확장되어 높은 동시 실행성 및 스테이트풀(Stateful) 대화 요구사항을 충족합니다.

Cloud Run에서 도구 상자를 설정하고 구성하려면 오픈소스 데이터베이스용 MCP 도구 상자를 다운로드한 다음 배포 가이드를 따르세요.

지금 시작하기

MCP 도구 상자 Java SDK v1.0을 사용하면 엔터프라이즈 Java팀이 Spring Boot 및 LangChain4j 에이전트를 도구 상자 서버에 연결하고, 이를 통해 AlloyDB 및 지원되는 다른 모든 데이터 소스에 연결할 수 있습니다. 도구 상자를 사용하면 인수가 JVM을 벗어나기 전에 도구 정의에 따라 검증되고, 인증이 분리되며, 모든 발신 요청에 커스텀 헤더가 연결됩니다. 다음 구현 단계를 참고하여 시작하세요.