Day 18. MCP Server 구현 + A2A 프로토콜 소개 — "이번엔 우리가 서버다"

Day 17 에서 우리는 MCP 의 3축 (Host, Client, Server) 을 익혔어요. Host 가 사용자와 만나는 LLM 앱이고, Client 가 Host 안에서 외부 서버와 1:1 연결을 맺는 진입점이고, Server 가 실제 도구를 제공하는 프로세스였죠.

그때 우리 ai-friends 는 Host 겸 Client 위치에 있었어요. 외부 MCP Server (filesystem, fetch, github) 의 도구를 소비하는 쪽이었죠. 이번 Step 에서는 우리가 Server 위치로 이동해요.

MCP Server 란 무엇인가

MCP Server 는 자기가 가진 도구 카탈로그를 JSON-RPC 프로토콜로 외부에 노출하는 프로세스예요. Day 17 Step 1 에서 봤던 그 JSON-RPC 통신의 반대편이에요. 외부 클라이언트가 tools/list 를 보내면 우리가 "이런 도구들이 있어요" 를 돌려주고, tools/call 을 보내면 우리가 실행해서 결과를 돌려줘요.

Day 11 에서 우리가 만든 @Tool 메서드를 기억하시죠? 그때는 우리 앱 내부의 ChatClient 만 호출할 수 있었어요. MCP Server 를 띄우면 같은 @Tool 어노테이션으로 정의한 도구가 외부 LLM 앱에서도 호출 가능해져요. Spring AI 의 @Tool 이 내부용과 외부용 양쪽으로 쓰일 수 있는 거예요.

왜 우리가 Server 를 만들어야 하는가

"튜터님, 그냥 REST API 를 만들면 되지 않나요? 왜 MCP Server 를 별도로 띄우나요?"

좋은 질문이에요. REST API 도 물론 가능하고, 지금도 우리 ai-friends 에는 REST 컨트롤러가 잘 동작하고 있어요. 하지만 MCP Server 를 따로 노출하는 이유는 소비자가 LLM 앱이라는 점에서 달라져요.

REST API 는 프론트엔드 개발자가 문서를 읽고, 엔드포인트 경로를 외우고, 요청 body 를 직접 짜야 해요. 반면 MCP 도구는 LLM 이 도구 카탈로그에서 자동으로 발견해요.

Claude Desktop 사용자가 "ARIA 호감도 알려줘" 라고 자연어로 말하면, Claude 가 우리 MCP Server 의 getCharacterStatus 도구를 자동으로 골라서 호출하는 거예요. 사람이 API 문서를 읽을 필요가 없어요.

핵심은 REST 를 대체하는 게 아니라 병행한다는 점이에요. 우리 ai-friends 의 REST 컨트롤러는 프론트엔드가 계속 호출하고, MCP Server 는 LLM 앱이 호출해요. 같은 도메인 서비스를 두 가지 통로로 노출하는 구조예요.

Transport 선택 — STDIO vs Streamable-HTTP

Day 17 에서 transport 세 가지를 비교했어요. STDIO, Streamable-HTTP, SSE (legacy). MCP Server 쪽에서도 transport 선택이 필요한데, 기준은 누가 어디서 우리 서버에 접속하느냐예요.

SSE 는 Day 17 에서 말씀드린 대로 2026 년 중반 sunset 이 진행 중이라 다루지 않아요. 신규 프로젝트는 Streamable-HTTP 가 표준이에요.

💡 튜터의 결론

MCP Server 는 우리 도메인 도구를 LLM 앱에 노출하는 표준 통로예요. REST API 와 병행하며, transport 는 로컬이면 STDIO, 원격이면 Streamable-HTTP 를 선택해요.

이론은 충분해요. 이제 코드로 갈게요. 우리 ai-friends 를 MCP Server 로 만드는 데 필요한 세팅은 놀라울 정도로 적어요.

1. 의존성 추가

build.gradle 에 두 줄을 추가해요.

// Day 18 — MCP Server (STDIO transport).
//    Day 17 의 반대 방향: 우리 도구를 외부 LLM 앱(Claude Desktop · Cursor 등)에 노출한다.
//    STDIO transport 는 자식 프로세스로 기동되어 stdin/stdout 으로 JSON-RPC 통신.
implementation 'org.springframework.ai:spring-ai-starter-mcp-server'

// Day 18 Step 5 — MCP Server (Streamable-HTTP transport).
//    원격 클라이언트가 HTTP 로 MCP 도구를 호출할 수 있게 한다.
//    Spring MVC 기반이라 기존 REST API 와 같은 포트에서 공존 가능.
implementation 'org.springframework.ai:spring-ai-starter-mcp-server-webmvc'

이 부분에서 짚어야 할 점이 두 가지 있어요.

첫째, spring-ai-starter-mcp-server 는 STDIO transport 를 지원하는 기본 starter 예요. 이것만으로도 Claude Desktop 이 우리 JAR 를 자식 프로세스로 띄워서 도구를 호출할 수 있어요.

둘째, spring-ai-starter-mcp-server-webmvc 는 Streamable-HTTP transport 를 추가하는 starter 예요. Spring MVC 기반이라 우리 기존 REST 컨트롤러와 같은 포트에서 공존해요. Step 5 에서 본격 활용하지만, 의존성은 미리 추가해 둬요.

2. Spring AI 의 MCP Server 자동 구성

의존성을 추가하면 Spring AI 의 자동 구성이 동작해요. @Tool 어노테이션이 달린 @Component 빈을 스캔해서, 그 메서드들을 MCP 도구 카탈로그에 자동 등록해요.

Day 11 에서 @Tool 을 처음 만났을 때 기억나시죠? 그때는 ChatClient 의 .tools(...) 에 직접 넘겨야 했어요.

MCP Server 에서는 한 단계 더 자동이에요 — @Component + @Tool 조합만으로 외부 카탈로그에 바로 등록돼요. Spring AI 가 부팅 시점에 도구 카탈로그를 조립하고, 외부 클라이언트가 tools/list 를 보내면 그 카탈로그를 JSON 으로 돌려줘요.

3. STDIO 기동 확인

STDIO transport 는 별도 설정 없이 동작해요. JAR 를 실행하면 Spring AI 가 자동으로 stdin/stdout JSON-RPC 리스너를 등록해요. 확인 방법은 Step 4 에서 Claude Desktop 연동을 시연할 때 함께 볼게요.

지금 단계에서 중요한 건 의존성 두 줄 + @Component + @Tool 만으로 MCP Server 가 완성된다는 사실이에요. REST 컨트롤러처럼 라우팅을 직접 짜지 않아도 돼요.

💡 튜터의 결론

spring-ai-starter-mcp-server 의존성 한 줄 + @Component + @Tool 조합이면 우리 Spring 앱이 MCP Server 가 돼요. REST 컨트롤러 없이도 외부 LLM 앱이 도구를 발견하고 호출할 수 있어요.

Step 2 에서 MCP Server 의 뼈대가 완성됐어요. 이제 우리 ai-friends 도메인에서 외부에 노출할 도구 3종을 만들어요. Day 11 의 내부 도구와 왜 분리하는지, 각 도구가 어떤 범위까지 노출하는지를 함께 짚어요.

내부 도구 vs 외부 도구 — 왜 분리하는가

Day 11 에서 만든 AffinityTool, GameStateTool 같은 내부 도구는 우리 ChatClient 전용이에요. 우리 앱 안에서 LLM 이 호출하니까, 트랜잭션 컨텍스트도 공유하고 접근 권한도 전권이에요.

반면 MCP 로 외부에 노출하는 도구는 외부 LLM 앱이 호출해요. Claude Desktop, Cursor, 또 다른 회사의 Spring AI 앱 등 누가 호출할지 모르는 상황이에요. 그래서 세 가지 원칙으로 분리해요.

1. 노출 범위 제한 — 내부 엔티티 (Soulmate) 를 그대로 돌려주지 않고, 외부 소비자에게 필요한 필드만 담은 전용 record 로 변환해요.
2. 쓰기 범위 제한 — 이벤트 트리거 도구는 미리 정의된 이벤트 목록만 허용하고, 임의 데이터 수정은 차단해요.
3. 패키지 분리 — kr.spartaclub.aifriends.mcp.server 패키지에 모아서, 내부 도구 (kr.spartaclub.aifriends.tool) 와 물리적으로 구분해요.

도구 1 — McpCharacterStatusTool (읽기 전용)

외부 LLM 앱이 캐릭터의 현재 상태를 조회하는 도구예요.

// kr.spartaclub.aifriends.mcp.server.McpCharacterStatusTool
// (전체 코드: lecture-source-code/ai-friends/.../mcp/server/McpCharacterStatusTool.java)

@Component
public class McpCharacterStatusTool {

    private static final Logger log = LoggerFactory.getLogger(McpCharacterStatusTool.class);

    private final SoulmateRepository soulmateRepository;

    public McpCharacterStatusTool(SoulmateRepository soulmateRepository) {
        this.soulmateRepository = soulmateRepository;
    }

    @Tool(description = "Get the current status of an AI character by ID. "
            + "Returns the character's name, personality, hobbies, affection score, and level. "
            + "Use this to check a character's state before interacting with them.")
    public McpCharacterStatus getCharacterStatus(
            @ToolParam(description = "The unique ID of the character to look up")
            Long characterId
    ) {
        log.info("[MCP Server] getCharacterStatus invoked — characterId={}", characterId);
        return soulmateRepository.findById(characterId)
                .map(this::toStatus)
                .orElseGet(() -> McpCharacterStatus.notFound(characterId));
    }

    private McpCharacterStatus toStatus(Soulmate soulmate) {
        return new McpCharacterStatus(
                true,
                soulmate.getId(),
                soulmate.getName(),
                soulmate.getPersonalityKeywords(),
                soulmate.getHobbies(),
                soulmate.getAffectionScore(),
                soulmate.getLevel()
        );
    }
}

몇 가지를 짚어 볼게요.

@Tool 의 description 이 영문인 이유 — MCP 도구의 description 은 외부 LLM 이 읽어요. Claude Desktop 에 연결하면 Claude 모델이 이 description 을 보고 "이 도구를 호출해야겠다" 를 판단해요. 영문이 대부분의 LLM 에서 인식률이 높아요.

McpCharacterStatus record 로 변환하는 이유 — Soulmate 엔티티를 직접 돌려주면 JPA 프록시 + 지연 로딩 + 내부 필드 (패스워드 해시 등 민감 정보가 있을 수 있는 부분) 가 그대로 외부에 노출돼요. 외부 전용 record 로 변환해서 노출 범위를 통제해요.

응답 record 는 깔끔해요.

// kr.spartaclub.aifriends.mcp.server.dto.McpCharacterStatus

public record McpCharacterStatus(
        boolean found,
        Long characterId,
        String name,
        String personality,
        String hobbies,
        int affectionScore,
        int level
) {
    public static McpCharacterStatus notFound(Long characterId) {
        return new McpCharacterStatus(false, characterId, null, null, null, 0, 0);
    }
}

notFound 정적 팩토리가 있어서, 존재하지 않는 캐릭터 ID 로 호출해도 예외 대신 구조화된 응답을 돌려줘요. 외부 LLM 앱이 예외를 받으면 대화 흐름이 끊기거든요. "찾을 수 없다" 는 정보도 정상 응답으로 전달하는 게 MCP 도구 설계의 좋은 패턴이에요.

도구 2 — McpEventTriggerTool (쓰기)

외부 LLM 앱이 캐릭터에게 이벤트를 발생시키는 도구예요. 읽기 전용인 1번 도구와 달리 호감도를 변경하는 쓰기 작업이 포함돼요.

// kr.spartaclub.aifriends.mcp.server.McpEventTriggerTool
// (전체 코드: lecture-source-code/ai-friends/.../mcp/server/McpEventTriggerTool.java)

@Component
public class McpEventTriggerTool {

    static final Map<String, EventEffect> EVENT_EFFECTS = Map.of(
            "gift", new EventEffect(5, "선물을 받아서 기분이 좋아졌어!"),
            "compliment", new EventEffect(3, "칭찬 고마워, 기분 좋다!"),
            "date", new EventEffect(8, "같이 놀아서 정말 즐거웠어!"),
            "insult", new EventEffect(-5, "그런 말 하면 속상해..."),
            "ignore", new EventEffect(-3, "왜 무시하는 거야...")
    );

    private final SoulmateRepository soulmateRepository;

    @Tool(description = "Trigger a named event for an AI character. "
            + "Supported events: gift (+5), compliment (+3), date (+8), "
            + "insult (-5), ignore (-3). "
            + "Returns the affection change and the character's reaction message.")
    public McpEventResult triggerEvent(
            @ToolParam(description = "The unique ID of the target character")
            Long characterId,
            @ToolParam(description = "Event name: gift, compliment, date, insult, or ignore")
            String eventName
    ) {
        String normalizedEvent = eventName.toLowerCase().trim();
        EventEffect effect = EVENT_EFFECTS.get(normalizedEvent);
        if (effect == null) {
            return McpEventResult.failure(characterId, eventName,
                    "Unknown event. Supported: " + EVENT_EFFECTS.keySet());
        }

        return soulmateRepository.findById(characterId)
                .map(soulmate -> applyEvent(soulmate, normalizedEvent, effect))
                .orElseGet(() -> McpEventResult.failure(characterId, eventName,
                        "Character not found"));
    }

    private McpEventResult applyEvent(Soulmate soulmate, String eventName,
                                      EventEffect effect) {
        soulmate.addAffection(effect.delta());
        soulmateRepository.save(soulmate);
        return new McpEventResult(true, soulmate.getId(), eventName,
                effect.delta(), soulmate.getAffectionScore(), effect.reaction());
    }

    record EventEffect(int delta, String reaction) {}
}

이 도구에서 주목할 설계 결정이 두 가지예요.

허용 이벤트를 Map.of(...) 로 제한한 이유 — 외부 LLM 앱이 임의 이벤트 이름을 보낼 수 있어요. "deleteAll" 이나 "resetDatabase" 같은 이름을 보내도 EVENT_EFFECTS map 에 없으면 failure 응답으로 거절돼요. 화이트리스트 기반의 입력 검증이 MCP 쓰기 도구의 기본이에요.

호감도 변동 폭을 서버 측에서 고정한 이유 — @ToolParam 으로 delta 값을 외부에서 받지 않아요. 이벤트 이름만 받고, 변동 폭은 서버 측 map 에서 결정해요. 외부가 "호감도를 +10000 올려줘" 같은 요청을 보내도 서버 측 정책으로 통제되는 구조예요.

도구 3 — McpSaveSlotTool (읽기 전용)

외부 LLM 앱이 ai-friends 의 세이브 슬롯 목록을 조회하는 도구예요.

// kr.spartaclub.aifriends.mcp.server.McpSaveSlotTool
// (전체 코드: lecture-source-code/ai-friends/.../mcp/server/McpSaveSlotTool.java)

@Component
public class McpSaveSlotTool {

    private static final int MAX_SLOTS = 50;
    private final GameStateEntryRepository gameStateEntryRepository;

    @Tool(description = "List all save slots in the ai-friends game. "
            + "Returns slot ID, player ID, turn count, and save timestamp. "
            + "Results are ordered by most recent first, limited to 50 entries.")
    public List<McpSaveSlotSummary> listSaveSlots() {
        return gameStateEntryRepository.findAll().stream()
                .sorted((a, b) -> b.getCreatedAt().compareTo(a.getCreatedAt()))
                .limit(MAX_SLOTS)
                .map(entry -> new McpSaveSlotSummary(
                        entry.getId(),
                        entry.getPlayerId(),
                        entry.getTurnCount(),
                        entry.getCreatedAt()
                ))
                .toList();
    }
}

MAX_SLOTS = 50 제한의 의미 — findAll() 전체를 가져오지만 50건으로 잘라요. MCP 응답이 너무 크면 LLM 의 컨텍스트 윈도우를 잡아먹어요.

Day 17 Step 4 에서 FetchMcpResponseLimiter 가 64KB 로 잘랐던 것과 같은 원리예요. 방향만 반대 — Day 17 은 우리가 받는 외부 응답을 잘랐고, 여기서는 우리가 보내는 응답을 잘라요.

대화 내용은 노출하지 않는 이유 — McpSaveSlotSummary record 에는 ID, 플레이어 번호, 턴 수, 저장 시각만 포함돼요. 대화 원문은 빠져 있어요. 외부 LLM 앱이 다른 플레이어의 대화 내용을 엿보는 사고를 구조적으로 차단하는 거예요.

도구 3종의 패키지 구조 정리

kr.spartaclub.aifriends
├── tool/                        # Day 11 — 내부 ChatClient 전용
│   ├── AffinityTool.java
│   └── GameStateTool.java
└── mcp/
    └── server/                  # Day 18 — 외부 MCP 전용
        ├── McpCharacterStatusTool.java
        ├── McpEventTriggerTool.java
        ├── McpSaveSlotTool.java
        ├── dto/
        │   ├── McpCharacterStatus.java
        │   ├── McpEventResult.java
        │   └── McpSaveSlotSummary.java
        └── security/
            ├── McpServerApiKeyFilter.java
            └── McpServerAuditInterceptor.java

내부 도구와 외부 도구가 같은 Repository 를 참조하지만, 반환 타입과 접근 범위가 다른 구조예요. 하나의 도메인 서비스를 두 관문으로 노출하되, 관문마다 통과하는 정보량이 다른 거예요.

💡 튜터의 결론

MCP 전용 도구는 내부 도구와 분리해서 노출 범위, 쓰기 범위, 응답 크기를 통제해요. 같은 도메인 데이터를 쓰되 외부 소비자에게는 record 로 변환한 안전한 뷰만 내보내요.

도구 3종이 준비됐어요. 이제 외부 LLM 앱에서 실제로 연동해 봐요. STDIO transport 기반이라 같은 머신에서 동작하는 Claude Desktop 과 Cursor 를 대상으로 시연해요.

Claude Desktop 연동

Claude Desktop 은 claude_desktop_config.json 파일로 MCP Server 를 등록해요. 파일 위치는 운영체제마다 달라요.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

설정 파일에 우리 ai-friends 서버를 추가해요.

{
  "mcpServers": {
    "ai-friends": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/ai-friends/build/libs/ai-friends-0.0.1-SNAPSHOT.jar",
        "--spring.profiles.active=mcp-stdio"
      ],
      "env": {
        "SPRING_DATASOURCE_URL": "jdbc:mysql://localhost:3306/ai_friends",
        "SPRING_DATASOURCE_USERNAME": "root",
        "SPRING_DATASOURCE_PASSWORD": "your-password"
      }
    }
  }
}

세 가지 포인트를 짚어요.

command + args 가 JAR 실행 명령인 이유 — STDIO transport 에서 Claude Desktop 은 우리 앱을 자식 프로세스로 직접 기동해요.

Day 17 에서 우리가 npx @modelcontextprotocol/server-filesystem 으로 외부 서버를 자식 프로세스로 띄웠던 것과 같은 원리예요. 이번엔 우리 JAR 가 자식 프로세스가 되는 거예요.

--spring.profiles.active=mcp-stdio — MCP STDIO 모드 전용 프로파일이에요. 웹 서버를 띄우지 않고 stdin/stdout 만 리슨하는 설정이에요. 기존 ./run.sh 로 띄우는 웹 서버 모드와 분리해요.

환경변수로 DB 접속 정보를 넘기는 이유 — STDIO 자식 프로세스는 부모 프로세스 (Claude Desktop) 의 환경을 상속받아요. .env 파일을 직접 읽지 못하니까, env 블록으로 필요한 변수를 명시적으로 전달해요.

시연 시나리오

Claude Desktop 에서 자연어로 대화해 봐요.

사용자: "ai-friends 의 1번 캐릭터 상태를 알려줘" Claude: (getCharacterStatus 호출) "1번 캐릭터 ARIA 의 현재 상태예요. 호감도 42점, 레벨 3이에요. 성격 키워드는 '상냥함, 호기심' 이고..."

사용자: "ARIA 에게 선물을 줘" Claude: (triggerEvent 호출) "ARIA 에게 선물 이벤트를 발동했어요. 호감도가 +5 올랐고 현재 47점이에요. ARIA 의 반응: '선물을 받아서 기분이 좋아졌어!'"

사용자: "세이브 슬롯 목록 보여줘" Claude: (listSaveSlots 호출) "현재 3개의 세이브 슬롯이 있어요. 가장 최근 저장은 2026-05-23 14:30..."

Claude 가 우리 도구의 description 을 읽고 자동으로 적절한 도구를 골라서 호출해요. 사용자는 API 엔드포인트를 알 필요가 없어요.

Cursor 연동

Cursor 도 MCP Server 를 지원해요. .cursor/mcp.json 파일에 같은 구조로 등록하면 돼요.

{
  "mcpServers": {
    "ai-friends": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/ai-friends/build/libs/ai-friends-0.0.1-SNAPSHOT.jar",
        "--spring.profiles.active=mcp-stdio"
      ]
    }
  }
}

Cursor 에서는 코딩 중에 "이 캐릭터의 현재 호감도를 확인하고 싶어" 라고 Chat 에 물어보면, Cursor 의 LLM 이 우리 MCP 도구를 호출해서 답해줘요.

STDIO 연동의 한계

STDIO 가 간편하지만 한계가 명확해요.

1. 같은 머신에서만 동작 — Claude Desktop / Cursor 가 JAR 를 직접 기동하니까 네트워크 너머에서는 접근 불가.
2. 프로세스 기동 비용 — 매번 JAR 를 새로 띄워요. Spring Boot 앱이라 cold start 가 수 초 걸릴 수 있어요.
3. 단일 클라이언트 — 한 번에 하나의 클라이언트만 stdin/stdout 을 점유해요.

이 한계를 넘어서 원격 접근이 필요하면? Step 5 의 Streamable-HTTP 가 답이에요.

💡 튜터의 결론

Claude Desktop / Cursor 의 설정 JSON 에 우리 JAR 경로를 한 줄 넣으면 연동 끝이에요. 외부 LLM 이 도구 description 을 읽고 자동으로 호출해요. 단, STDIO 는 로컬 전용이라 원격 접근은 Streamable-HTTP 로 전환해야 해요.

STDIO 의 한계 세 가지 (로컬 전용, 프로세스 기동 비용, 단일 클라이언트) 를 넘어서 원격에서도 우리 MCP Server 에 접근하려면 Streamable-HTTP transport 를 활성화해야 해요.

Streamable-HTTP 란

Day 17 Step 1 에서 transport 표를 봤었죠. Streamable-HTTP 는 일반 HTTP POST 로 MCP JSON-RPC 요청을 보내고, streaming 응답을 받는 통로예요.

우리 기존 REST API 와 같은 포트 (8080) 에서 공존할 수 있어요. spring-ai-starter-mcp-server-webmvc 가 Spring MVC 기반으로 엔드포인트를 자동 등록해 주거든요.

활성화 설정

application.yml 에 MCP Server 설정을 추가해요.

spring:
  ai:
    mcp:
      server:
        enabled: true
        name: ai-friends-mcp-server
        version: 1.0.0
        type: SYNC
        stdio: true                      # STDIO transport 유지
        streamable-http:
          enabled: true                  # Streamable-HTTP 추가 활성화
          endpoint: /mcp                 # HTTP 진입점

이 설정으로 두 transport 가 동시에 활성화돼요. STDIO 는 Claude Desktop 로컬 연동용, Streamable-HTTP 는 원격 연동용으로 공존해요.

endpoint: /mcp — 우리 앱의 http://localhost:8080/mcp 경로로 MCP JSON-RPC 요청을 받아요. 기존 REST API (/api/...) 와 경로가 겹치지 않아요.

원격 클라이언트에서 연결

Streamable-HTTP 가 활성화되면 원격 MCP Client 가 HTTP 로 접속할 수 있어요. 예를 들어 다른 팀의 Spring AI 앱이 우리 ai-friends 도구를 사용하고 싶다면, application.yml 에 이렇게 연결해요.

# 다른 팀의 Spring AI 앱 — 우리 ai-friends MCP Server 에 연결
spring:
  ai:
    mcp:
      client:
        streamable-http:
          connections:
            ai-friends:
              url: http://ai-friends-server:8080
              endpoint: /mcp

Day 17 에서 우리가 외부 MCP 서버에 연결했던 yml 구조와 정확히 같아요. 이번엔 다른 앱이 우리에게 같은 구조로 연결하는 거예요. 거울이죠.

STDIO vs Streamable-HTTP 트레이드오프 정리

프로덕션에서는 Streamable-HTTP + 인증이 표준이에요. STDIO 는 개인 데스크탑 도구나 로컬 테스트용이에요.

💡 튜터의 결론

streamable-http.enabled: true + endpoint: /mcp 한 줄로 원격 MCP 접근이 열려요. 기존 REST API 와 같은 포트에서 공존하고, 인증은 다음 Step 6 에서 추가해요.

Streamable-HTTP 로 원격 접근을 열었어요. 그런데 인증 없이 열어 두면 누구나 우리 도구를 호출할 수 있어요. Day 17 에서 우리가 5 가드 빈으로 외부 MCP 서버의 응답을 검증했듯이, 이번엔 들어오는 요청을 검증하는 거울 방향의 보안이 필요해요.

Day 17 의 보안이 "나가는 방향" (우리가 외부 응답을 필터링) 이었다면, Day 18 의 보안은 "들어오는 방향" (외부가 우리에게 보내는 요청을 필터링) 이에요.

보안 5축 개요

축 1 — API Key 인증 (McpServerApiKeyFilter)

Streamable-HTTP 로 들어오는 요청에 API Key 를 요구해요.

// kr.spartaclub.aifriends.mcp.server.security.McpServerApiKeyFilter
// (전체 코드: lecture-source-code/ai-friends/.../security/McpServerApiKeyFilter.java)

@Component
@ConditionalOnProperty(name = "aifriends.mcp.server.api-key")
public class McpServerApiKeyFilter {

    static final String API_KEY_HEADER = "X-MCP-API-Key";
    private final String expectedApiKey;

    public boolean authenticate(String apiKeyHeader) {
        if (apiKeyHeader == null || apiKeyHeader.isBlank()) return false;
        return expectedApiKey.equals(apiKeyHeader.trim());
    }
}

핵심 설계 결정 두 가지를 짚어요.

@ConditionalOnProperty 가 하는 일 — aifriends.mcp.server.api-key 프로퍼티가 설정돼 있을 때만 이 빈이 등록돼요.

설정이 없으면 빈 자체가 생성되지 않아요. STDIO 전용 환경 (로컬 Claude Desktop) 에서는 API Key 가 필요 없으니까 이 프로퍼티를 빼면 필터가 자동으로 비활성화돼요.

헤더 이름 X-MCP-API-Key — MCP 스펙 자체는 인증 헤더를 강제하지 않아요. 우리 앱 정책으로 정한 커스텀 헤더예요. 프로덕션에서는 OAuth 2.1 Bearer 토큰으로 교체하는 것이 표준이에요.

축 2 — 감사 로그 (McpServerAuditInterceptor)

외부 클라이언트가 어떤 도구를 언제 호출했는지 기록해요.

// kr.spartaclub.aifriends.mcp.server.security.McpServerAuditInterceptor

@Component
public class McpServerAuditInterceptor {

    private final Map<String, AtomicLong> invocationCounts = new ConcurrentHashMap<>();

    public void logInvocation(String toolName, String clientId) {
        invocationCounts.computeIfAbsent(toolName, k -> new AtomicLong(0))
                .incrementAndGet();
        log.info("[MCP Server Audit] tool={}, client={}, timestamp={}, totalCalls={}",
                toolName, clientId, Instant.now(),
                invocationCounts.get(toolName).get());
    }

    public long getInvocationCount(String toolName) {
        AtomicLong count = invocationCounts.get(toolName);
        return count != null ? count.get() : 0;
    }
}

ConcurrentHashMap + AtomicLong 조합인 이유 — Streamable-HTTP 는 다중 클라이언트가 동시에 접속할 수 있어요. 동시성 안전한 자료구조로 카운터를 관리해야 해요.

학습 단계에서 인메모리로 충분한 이유 — 앱이 재시작되면 카운터가 초기화돼요. 프로덕션에서는 이 로그가 Micrometer 메트릭 + 구조화 로깅으로 확장돼요 (Day 21 Observability 에서 다룰 예정이에요).

축 3~5 요약

Day 17 에서 5 가드 빈을 만들면서 배운 원칙이 그대로 적용돼요 — 외부와 만나는 모든 지점에 의식적인 결정을 넣는다. 방향만 반대예요.

💡 튜터의 결론

MCP Server 보안은 Day 17 Client 가드의 거울이에요. 방향만 반대 (나가는 → 들어오는) 이고, 원칙은 동일 — 외부와 만나는 지점마다 인증, 감사, 스코프, 검증, 네트워크 노출을 의식적으로 결정해요.

MCP Server 까지 완성했어요. 우리 ai-friends 의 도구를 외부 LLM 앱이 표준 프로토콜로 호출할 수 있게 됐죠. 그런데 한 가지 질문이 남아요.

"도구를 호출하는 건 알겠는데, 에이전트끼리 협업하려면 어떻게 하죠?"

MCP 는 도구 호출의 표준이에요. LLM 앱이 "이 함수를 실행해 줘" 라고 요청하면 서버가 실행해서 결과를 돌려주는 구조죠. 그런데 에이전트가 다른 에이전트에게 "이 작업을 처리해 줘" 라고 작업 자체를 위임하는 건 MCP 의 범위 밖이에요.

그래서 등장한 게 A2A (Agent-to-Agent) 프로토콜이에요.

A2A 란 무엇인가

A2A 는 Google 이 2025 년에 제안하고, 이후 Linux Foundation 에 거버넌스가 이관된 오픈 프로토콜이에요. 2026 년 5월 현재 150개 이상 조직이 프로덕션에서 사용 중이에요.

MCP 와 A2A 의 관계를 실생활 비유로 풀어 볼게요.

MCP 는 연장통이에요. 목수 (LLM) 가 "이 망치를 써야겠다" 고 판단하면 연장통에서 망치를 꺼내서 못을 때려요. 도구를 골라서 실행하는 거예요.

A2A 는 하청 계약이에요. 건축 현장의 총 책임자 (에이전트 A) 가 "배관 작업은 배관 전문업체 (에이전트 B) 에 맡기자" 고 판단하면, 작업 요청서를 보내고 진행 상황을 추적하다가 완료 보고를 받아요. 도구를 직접 쓰는 게 아니라 다른 전문가에게 작업을 위임하는 거예요.

A2A 의 핵심 3 개념

Agent Card

A2A 에서 에이전트는 Agent Card 라는 JSON 문서로 자기 능력을 공개해요. MCP 의 tools/list 에 대응하는 개념이에요.

{
  "name": "ai-friends-agent",
  "description": "AI 캐릭터 관리 에이전트 — 캐릭터 상태 조회, 이벤트 처리, 세이브 관리",
  "url": "https://ai-friends.example.com/a2a",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "character-management",
      "name": "캐릭터 관리",
      "description": "AI 캐릭터의 상태 조회, 이벤트 발동, 호감도 관리"
    }
  ]
}

Agent Card 가 /.well-known/agent.json 경로에 공개되면, 다른 에이전트가 이걸 읽고 "이 에이전트에게 캐릭터 관리 작업을 맡길 수 있겠다" 를 판단해요.

Task

A2A 에서 작업 단위는 Task 예요. MCP 의 tools/call 이 1회성 함수 호출이라면, A2A 의 Task 는 상태를 가진 비동기 작업이에요.

submitted → working → done (또는 failed)

요청하는 에이전트가 Task 를 생성하면, 받는 에이전트가 작업을 처리하면서 상태를 업데이트해요. 요청자는 상태를 폴링하거나 push notification 으로 완료를 기다릴 수 있어요.

Message

Task 안에서 에이전트 간에 주고받는 메시지예요. 텍스트, 이미지, 파일 등 다양한 형태의 Part 를 담을 수 있어요.

MCP + A2A 가 보완하는 구조

둘은 경쟁이 아니라 보완 관계예요.

하나의 에이전트가 A2A 로 작업을 위임받고, 그 작업을 처리하는 과정에서 MCP 도구를 호출하는 구조가 자연스러워요.

예를 들어:

1. 총괄 에이전트가 "ai-friends 캐릭터 ARIA 의 호감도를 높여 줘" 라는 A2A Task 를 ai-friends 에이전트에 위임
2. ai-friends 에이전트가 Task 를 받아서, MCP 도구 getCharacterStatus 로 현재 상태를 확인
3. MCP 도구 triggerEvent 로 선물 이벤트를 발동
4. A2A Task 상태를 done 으로 업데이트하고 결과를 반환

MCP 가 손 (도구를 직접 쓰는 행위) 이라면, A2A 는 전화 (다른 전문가에게 일을 맡기는 행위) 예요. 같은 일을 해도 접근 방식이 달라요.

💡 튜터의 결론

MCP 는 도구 호출의 표준, A2A 는 에이전트 간 작업 위임의 표준이에요. 둘은 경쟁이 아니라 보완 관계 — 하나의 에이전트가 A2A 로 작업을 받아서, MCP 도구로 처리하는 구조가 자연스러워요.

마지막 Step 이에요. 코드를 만지지 않는 정리 시간이에요. A2A 의 현재 생태계를 한 줄로 짚고, 오늘 8 Step 의 트레이드오프를 테이블로 정리하고, Day 19 복선을 심어요.

A2A 생태계 현황 (2026-05 기준)

• 거버넌스: Google 제안 → Linux Foundation 이관 완료
• 참여 규모: 150+ 조직 프로덕션 사용
• SDK: Google ADK (Agent Development Kit) 1.0 GA
• Spring AI 통합: 블로그 포스트 (2026-01-29) 에서 Spring AI 의 A2A 통합 패턴이 공개됐어요. spring-ai-starter-a2a 같은 first-class starter 는 아직 없지만, RestClient + A2A JSON 스펙으로 통합하는 패턴이 문서화돼 있어요.

A2A 는 아직 MCP 만큼 성숙하지 않아요. 하지만 에이전트 간 협업이 필요한 시점이 오면 자연스럽게 도입하게 되는 프로토콜이에요.

트레이드오프 정리 — 오늘의 5가지 결정

Day 19 으로 잇는 다리

다음 시간은 Agent 를 프로덕션에 올리기 위한 harness 엔지니어링이에요. Day 14 에서 손으로 구현한 4 가드 (반복 횟수, 타임아웃, 토큰 예산, 툴 호출 횟수) 가 Spring AI Agent Client 에서는 선언적으로 처리되는 모습을 볼 거예요.

복선 키워드 4종을 한 줄씩 남겨 둘게요.

• Agent Client — Day 14 의 수동 가드가 선언적 설정으로 전환되는 지점
• Spring AI Bench — 에이전트 품질을 정량 측정하는 벤치마크 도구
• Rate Limit — 클라이언트별 호출 횟수 제한 (오늘 Step 6 감사 로그의 확장)
• harness 엔지니어링 — "에이전트를 프로덕션에 올리려면 harness 가 필요하다"

🎯 오늘 한 줄 회수

"Day 17 Client 의 거울 — 우리 도메인 도구를 MCP Server 로 노출하고, 보안 5축으로 들어오는 요청을 검증하고, A2A 로 에이전트 협업의 다음 축을 인식했어요."

💡 튜터의 결론

MCP 가 도구의 표준이라면 A2A 는 에이전트 협업의 표준이에요. 두 프로토콜이 보완하는 구조를 인식하는 것만으로도 오늘의 가장 큰 수확이에요. 다음 시간 Day 19 에서는 이 에이전트를 프로덕션 수준으로 끌어올리는 harness 엔지니어링을 다뤄요.

Day 17 에서 우리는 외부 MCP Server 의 도구를 받아들이는 Client 였어요. 오늘은 정반대 — 우리 ai-friends 의 도메인 도구를 외부 LLM 앱에 내어주는 Server 가 됐어요. 같은 MCP 프로토콜인데 화살표 방향만 뒤집힌 거예요.

오늘의 8 Step 을 한 표에 담아 회수해요.

Day 17 에서 배운 메타 원칙을 다시 한 번 확인했어요 — 외부와 만나는 모든 지점에 의식적인 결정을 넣는다. Day 17 은 나가는 방향 (외부 응답 검증), Day 18 은 들어오는 방향 (외부 요청 검증) 으로 같은 원칙이 양쪽에서 일관되게 적용됐어요.

다음 시간 (Day 19) 으로 잇는 다리

Day 19 는 에이전트를 프로덕션에 올리기 위한 harness 엔지니어링이에요. Day 14 에서 반복 횟수, 타임아웃, 토큰 예산, 툴 호출 횟수를 손으로 구현했던 4 가드가, Spring AI Agent Client 에서는 선언적 설정으로 전환돼요.

그리고 본 시간 Step 6 에서 인메모리로 카운트만 했던 감사 로그가 Rate Limit 정책으로 확장되는 대목도 함께 다뤄요.

오늘 우리는 MCP Server 3종 도구 + 보안 5축 + A2A 개념을 8 Step 으로 익혔어요. 진짜로 감각이 잡히는 건 본인이 직접 도구를 확장하고 보안을 강화해 보는 경험에서 시작돼요.

오늘 우리는 MCP Server + A2A 의 8 Step 골격을 추가했어요. 그런데 진짜 운영 의 면은 본 강의가 추가한 디폴트 위에서 한 단계 더 깊게 확장돼요. 세 독립적인 주제를 던져 둡니다. 각 주제는 답이 하나가 아니에요 — 본인의 시나리오와 운영 가치 위에서 본인의 답 을 찾아오는 거예요.