AWS MCP Server가 일반 공개되었습니다.

이번에는 Ruby를 사용하여 MCP 클라이언트를 직접 제작하고, AWS MCP Server와 직접 통신함으로써 MCP의 내부 동작을 확인해 보겠습니다.

AWS MCP Server는 Model Context Protocol (MCP)을 통해 AI 에이전트 등에 AWS 서비스에 대한 안전한 접근을 제공하는 완전 관리형(full-managed) 원격 MCP 서버입니다. AWS API 실행, AWS 문서 참조, IAM 기반 인증(authorization), CloudTrail 감사 등을 통합적으로 제공합니다.

보통은 Claude Code, Kiro, Cursor 등의 MCP 지원 클라이언트나 MCP용 SDK를 통해 사용하는 경우가 많을 것입니다.

하지만 이번에는 일부러 Ruby로 MCP 클라이언트를 직접 제작하여 AWS MCP Server와 직접 주고받아 보겠습니다.

제작할 도구의 이미지

하고 싶은 것은 매우 간단합니다.

• 입력: 인간이 자연어로 하고 싶은 것을 전달
• 제안: AWS MCP Server가 적절한 AWS CLI 명령어 후보를 제안
• 판단: 인간이 그 후보를 확인 및 선택
• 실행: 선택된 명령어만 실행하고, 결과를 표시

실제 동작 예시

$ ./main.rb
👉 무엇을 하고 싶으신가요? (exit로 종료): S3의 버킷 목록이 보고 싶어요
🔍 제안 생성 중...
...

참고로, 명령어 실행 전에 인간이 선택하는 대화 형식으로 되어 있지만, 이는 MCP의 필수 사양은 아닙니다.

이번 구현은,

• 제안은 AI가 담당하고,
• 실행 판단은 인간이 담당한다는 설계 사상을 가지고 있습니다.

AWS MCP Server란?

다시 한번, 애초에 MCP가 어떤 기능인지 정리해 보겠습니다.

MCP는 툴이나 리소스, 프롬프트 등의 컨텍스트 정보를 JSON-RPC 기반으로 주고받기 위한 표준 프로토콜입니다.

AWS MCP Server는 AWS가 제공하는 공식 MCP 서버이며, AI 에이전트가 MCP를 통해 AWS의 API나 문서에 접근할 수 있도록 하는 인터페이스를 제공합니다. 주로 다음과 같은 기능들이 제공됩니다.

• 문서 참조
• AWS API 제안
• AWS API 실행

굳이 직접 제작하는 이유

MCP에는 공식 언어별 SDK도 준비되어 있습니다.

공식 SDK는 JSON-RPC 2.0의 메시지 처리, initialize나 capability negotiation, tools/list, tools/call, stdio/Streamable HTTP 등을 다루기 쉽게 추상화해주기 때문에 일반적인 애플리케이션 개발에서는 SDK를 사용하는 것이 자연스럽습니다.

SDK를 사용하면 편리한 반면, 이러한 처리 과정들은 라이브러리 내부에 숨겨집니다.

• JSON-RPC의 원시 데이터: 텍스트 기반으로 어떤 요청/응답이 흐르고 있는지
• 세션 초기화: 클라이언트와 서버가 어떻게 연결을 확립하는지
• Tool Calling의 실체: AI가 툴을 '호출'하는 순간의 구체적인 데이터 구조
• Human-in-the-loop의 설계: 실행 전에 인간의 확인을 거치는 안전한 워크플로우 구축 방법

MCP를 자체 AI 에이전트나 사내 시스템에 통합하는 것을 고려하고 있다면, 한 번은 이 저수준(low-level) 메커니즘을 만져볼 가치가 있을 것입니다.

통신 플로우와 구성

이번 구현에서는 Ruby에서 AWS에 직접 연결하는 것이 아니라, AWS가 제공하는 프록시 mcp-proxy-for-aws를 중개자로 사용합니다.

등장인물

• Ruby CLI (Client): 사용자 입력을 받아 JSON-RPC 요청을 생성
• mcp-proxy-for-aws: 로컬 인증 정보를 사용하여 원격 서버와의 통신을 중계
• AWS MCP Server: 실제 툴 실행이나 API 조작 담당

아래가 이번 구현에서의 통신 시퀀스입니다.

통신 시퀀스

그림 1. Ruby 제작 MCP 클라이언트에서 AWS MCP Server까지의 통신 시퀀스

aws_mcp_client.rb<br>
(저수준 통신)<br>
Open3을 사용하여 프록시와 표준입출력(파이프)으로 JSON-RPC를 주고받는 핵심부입니다. -<br>aws_mcp_agent.rb

（대화·안전 제어）

사용자 입력 수신, AI 제안 파싱, 파괴적인 명령 실행 방지 로직을 담당합니다. -
main.rb

（기동용）

전체 초기화와 메인 루프를 수행하는 엔트리 포인트(Entry point)입니다.

구현의 핵심: 왜 이런 설계인가

1. 왜 Ruby의 Open3를 사용하는가

이번 클라이언트 구현의 핵심은 Open3.popen3를 통한 서브 프로세스(Subprocess) 제어입니다.

왜 단순한 라이브러리 호출이 아니라 이 방식을 채택했는지 설명하겠습니다.

양방향 스트림(Stream) 확보

MCP는 표준 입력(stdin)으로 요청을 보내고, 표준 출력(stdout)으로 응답을 받는 '대화형' 프로토콜입니다.

Open3를 사용함으로써, 이러한 독립된 파이프(Pipe)를 Ruby에서 직접 비동기적으로 제어할 수 있습니다.

프록시를 통한 '인증 위임'

본래 AWS API를 조작하려면 복잡한 SigV4 서명이 필요하지만, 이를 Ruby로 처음부터 구현하는 것은 매우 고된 작업입니다.

mcp-proxy-for-aws를 Open3로 실행하여 배후에 숨김으로써, Ruby 측은 인증의 번거로움에서 벗어나 순수 로직에 집중할 수 있습니다.

견고한 에러 핸들링(Error Handling)

표준 에러 출력(stderr)을 별도의 스레드(Thread)에서 모니터링함으로써, 프록시 측에서 발생한 인증 에러나 네트워크 트러블을 Ruby 측에서 즉시 감지하고 표시할 수 있습니다.

2. MCP 통신의 실체: JSON-RPC 송수신

통신의 실체는 매우 심플한 JSON-RPC 2.0입니다.

요청(Request) 구조

Ruby 측에서는 실행하고 싶은 도구(Tool) 이름과 인자(Argument)를 JSON 형식으로 한 줄 쓰기만 하면 됩니다.

{
"jsonrpc": "2.0",
"id": 1,
...

ID를 통한 매핑

id를 부여하여 요청을 보내고, 동일한 id를 가진 응답을 기다림으로써, 상태가 없는(Stateless) 표준 입출력 환경에서도 '요청과 응답'의 정합성을 유지합니다.

gRPC와의 차이점

엄격한 타입 정의(.proto)가 필요한 gRPC와 달리, MCP는 실행 시점에 서버가 '어떠한 도구(기능)를 가지고 있는지'를 동적으로 제시합니다.

이러한 유연성은 매일 진화하는 방대한 AWS API를 AI로 다루는 데 있어 강력한 무기가 됩니다.

3. '제안'과 '실행'을 분리하는 안전 설계

자연어로 AWS를 조작하는 이상, AI의 오작동은 반드시 방지해야 합니다.

본 클라이언트에서는 의도적으로 제안과 실행을 물리적으로 분리했습니다.

제안(suggest)

aws___suggest_aws_commands를 호출하여 AI가 '최적의 명령'을 생각하게 하고 사용자에게 제시합니다.

인간에 의한 확인

사용자가 번호를 선택해야만 다음 단계로 진행됩니다.

실행(execute)

aws___call_aws를 사용하여 인간이 승인한 명령만 실행합니다.

aws___suggest_aws_commands나 aws___call_aws와 같은 도구 이름은 MCP 서버 측이 tools/list를 통해 공개하는 도구 이름에 대응합니다.

본 샘플에서는 설명을 간결하게 하기 위해, 작성 시점에 확인된 도구 이름을 상수로 정의했습니다.

실제 코드 부분을 발췌하겠습니다.

먼저, 사용할 도구 이름을 TOOLS에 모아두었습니다.

TOOLS = {
suggest: "aws___suggest_aws_commands",
execute: "aws___call_aws"
...

여기서는 MCP 서버 측에 정의된 도구 이름(aws___suggest_aws_commands 등)을 애플리케이션 측에서 다루기 쉬운 심볼(Symbol)로 매핑하고 있습니다.

다음은 명령 후보를 가져오는 함수입니다.

def suggest_commands(query)
request("tools/call", {
name: TOOLS[:suggest],
...

이는 MCP의 tools/call을 사용하여 aws___suggest_aws_commands 도구를 호출합니다.

사용자의 입력(query)을 전달함으로써 실행 가능한 AWS CLI 명령 후보를 가져옵니다.

마지막으로, 실제로 AWS 조작을 실행하는 함수입니다.

def execute_aws(cli_command)
request("tools/call", {
name: TOOLS[:execute],
...

이것 역시 마찬가지로 tools/call을 사용하여 aws___call_aws 도구를 호출하고 있습니다.

suggest_commands에서 얻은 명령을 cli_command로 전달함으로써, 실제 AWS API 실행으로 이어집니다.

요약

이번에 AWS MCP Server를 대상으로 Ruby를 사용하여 MCP 클라이언트를 직접 제작해 봄으로써, MCP의 초기화 시퀀스(Initialization Sequence)나 JSON-RPC 기반의 Tool Calling이 어떻게 동작하는지 실제로 확인할 수 있었습니다.

실제 애플리케이션 개발에서는 유지보수성이나 사양 준수 관점에서 공식 SDK를 이용하는 것이 자연스러울 것입니다. 반면, MCP를 독자적인 시스템에 통합하거나, MCP 서버 또는 에이전트 자체를 개발하는 경우에는 이러한 저수준(Low-level) 메커니즘을 이해해 두는 것이 유용합니다.

앞으로는 AWS에 국한되지 않고 다양한 MCP 서버를 조합함으로써, AI 에이전트가 여러 시스템을 횡단적으로 조작하는 아키텍처가 더욱 일반화될 것이라고 느낍니다.

부록: 구현 코드 전체

본 기사에서 사용한, AWS MCP Server의 tools/call을 이해하기 위한 최소 구성의 MCP 클라이언트를 공유합니다.

"AWS MCP Server에 대해 initialize를 실행하고, 도구를 호출하며, 결과를 받는다"라는 핵심 흐름에 대해서는, SDK가 내부적으로 수행하는 처리를 상당히 소박한 형태로 재현하고 있습니다.

공식 Ruby SDK와 같이 prompts / resources, pagination, progress, sampling, elicitation, Streamable HTTP, SSE 등 MCP 전체를 포괄하는 것은 아닙니다.

실운용에서는 에러 핸들링(Error Handling), 재시도 제어(Retry Control), 인증 관리, MCP 사양 준수 등의 관점에서 공식 SDK 사용을 권장합니다.

ruby_version/lib/aws_mcp_client.rb

require "json"
require "open3"
require "timeout"
...

ruby_version/lib/aws_mcp_agent.rb

class AwsMcpAgent
def initialize(client)
@client = client
...
```json|```/, "").strip
parsed = JSON.parse(json_text)
# GA 버전의 응답 구조에 맞춰 파싱
# suggestions: [{ command, confidence_score, description, required_parameters }]
...

ruby_version/bin/main.rb

$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
require "aws_mcp_client"
require "aws_mcp_agent"
...

관련 서비스

소프트뱅크는 AWS 어드밴스드 티어 서비스 파트너 (AWS Advanced Tier Services Partner) 입니다.

"첫 AWS 도입"부터 대규모 서비스 기반 및 기간 시스템 구축까지, 고객의 요구사항에 맞춰 최적의 AWS 환경 도입을 지원합니다.

MSP (Managed Service Provider) 서비스는 고객의 퍼블릭 클라우드 도입부터 운용까지를 토탈로 제공하는 매니지드 서비스입니다.

Discussion