01개요 - MCP Tool Forge란

이 절에서는 MCP Tool Forge가 어떤 도구이고 왜 만들어졌는지 소개합니다. 핵심은 하나입니다. AI가 쓰는 도구를 서버 없이 돌아가는 코드로 바꾸는 것입니다.

MCP Tool Forge는 MCP(Model Context Protocol, AI 에이전트가 외부 도구를 호출하게 해주는 표준 프로토콜) 서버의 도구(Tool)를 추출하는 Python CLI 도구입니다. 추출한 도구는 boto3, AWS CLI, OpenAPI 스키마(Schema), AgentCore Gateway, Claude Code / Kiro-CLI Skill 5가지 형식으로 변환됩니다. 바로 설치해 쓸 수 있는 9개 AWS Skills를 포함하며, Claude Code와 Kiro-CLI를 모두 지원합니다.

용어를 짧게 풀면 이렇습니다. boto3는 AWS를 코드로 다루는 Python 라이브러리이고, OpenAPI 스키마는 도구의 입력과 출력을 기술하는 표준 문서 형식입니다. AgentCore Gateway는 Amazon Bedrock의 도구 게이트웨이 서비스이고, Skill은 에이전트가 필요할 때만 읽어 들이는 마크다운 지침 파일입니다.

이 도구가 존재하는 이유는 MCP의 토큰 비용 구조에 있습니다. MCP 서버를 켜두는 것만으로 모든 도구 정의가 매 대화의 컨텍스트에 실립니다. 그래서 도구를 쓰지 않아도 비용이 발생합니다.

이 문서는 먼저 그 비용을 수치로 확인합니다(2~3장). 이어서 해법인 Skills의 설치와 구성을 다루고(4장), 변환 파이프라인의 동작 방식을 정리합니다(5~7장).

02핵심 문제 - MCP 토큰 비용

이 절에서는 MCP 서버를 켜두기만 해도 왜 비용이 생기는지 살펴봅니다. 비용의 단위는 토큰(LLM이 글을 읽고 쓰는 최소 단위이자 과금 기준)입니다.

2.1 MCP는 왜 토큰을 많이 소모하는가

MCP 프로토콜은 강력하지만, 모든 도구 정의(Tool Definition)와 요청/응답이 LLM 토큰으로 소모됩니다. MCP 서버가 로딩되면 모든 도구의 JSON Schema(도구의 입력과 출력을 기술한 명세)가 LLM 컨텍스트(모델이 대화마다 읽는 입력 전체)에 주입됩니다.

이 주입은 LLM이 어떤 도구를 쓸 수 있는지 "알기 위해" 필요한 과정입니다. 문제는 주입된 도구 대부분이 그 대화에서 사용되지 않는다는 점입니다.

그 비용은 어느 정도일까요? 도구 정의 하나가 약 2,000토큰이므로, IAM MCP 서버 하나를 로딩하면 도구 29개 × 약 2,000토큰 = 약 58,000토큰이 도구 정의만으로 소모됩니다. 여기에 도구를 호출할 때마다 JSON-RPC(원격 함수를 호출하는 메시지 규약) 요청/응답 왕복으로 호출당 약 500토큰이 추가됩니다.

2.2 실측 결과 (Kiro-CLI 기준)

이론이 아니라 실측에서는 얼마나 차이가 날까요? 같은 작업을 MCP 서버를 켠 상태와 끈 상태(Skills만 사용)로 각각 실행해 비교했습니다. 비용 단위는 credits(Kiro-CLI의 사용량 과금 단위)입니다.

이 표에서 볼 것은 같은 작업인데도 벌어지는 credits 차이입니다.

2.3 MCP Tool Forge의 해법

해법은 한 번 추출 → 네이티브 코드로 변환 → MCP 없이 직접 실행입니다. MCP 방식은 Agent ↔ MCP Server ↔ AWS API 경로를 매번 거치며 토큰을 소모합니다. Skill 방식은 Agent가 boto3 / CLI 코드를 직접 실행해 AWS API로 가므로, 추가 토큰도 왕복 지연도 없습니다.

이 표에서 볼 것은 토큰, 서버, 지연 시간 항목에서 두 방식이 어떻게 갈리는지입니다.

03토큰 경제학 - MCP vs Skills

이 절에서는 두 방식의 비용 차이를 토큰 수와 달러 금액으로 비교합니다. 앞 절의 문제가 실제로 얼마짜리인지 확인하는 단계입니다.

3.1 Skills는 어떻게 토큰을 절약하는가

Skills는 필요한 스킬만 선택적으로 로딩(Selective Loading)합니다. 예를 들어 "IAM 사용자 목록 보여줘"라는 요청에서, MCP 방식은 IAM 서버의 29개 도구 스키마 전체(58,000토큰)를 로딩한 뒤 그중 1개만 사용합니다. Skill 방식은 aws-iam의 SKILL.md 1개(약 3,000토큰)만 로딩하고 바로 실행합니다.

이 표에서 볼 것은 초기 로딩 토큰과 호출당 토큰, 그리고 서버 개수의 차이입니다.

3.2 비용 환산 (Claude Opus 4.6 기준)

돈으로 환산하면 얼마나 차이가 날까요? 입력 토큰 단가 $15/1M 토큰을 적용해 대화당 비용으로 바꿔 보았습니다. 이 표에서 볼 것은 MCP 서버 개수에 따라 커지는 대화당 비용과 Skill의 비용입니다.

한 문장으로 요약하면, Skill 방식은 MCP 대비 토큰 비용을 95% 이상 절감합니다.

04Skills 설치와 9개 AWS Skills

이 절에서는 함께 제공되는 9개 AWS Skills를 설치하고 쓰는 방법을 다룹니다. 설치는 복사 몇 줄이면 끝나고, 이후에는 평소처럼 말로 요청하면 됩니다.

4.1 설치 - 3줄이면 끝

저장소를 클론하고 스킬 디렉터리로 복사하면 설치가 끝납니다. Claude Code는 .claude/skills, Kiro-CLI는 .kiro/skills를 씁니다.

# Claude Code
git clone https://github.com/whchoi98/mcp-tool-forge.git
mkdir -p .claude/skills
cp -r mcp-tool-forge/.claude/skills/aws-* .claude/skills/

# Kiro-CLI
mkdir -p .kiro/skills
cp -r mcp-tool-forge/.claude/skills/aws-* .kiro/skills/

# Claude Code
mkdir -p ~/.claude/skills
cp -r mcp-tool-forge/.claude/skills/aws-* ~/.claude/skills/

# Kiro-CLI
mkdir -p ~/.kiro/skills
cp -r mcp-tool-forge/.claude/skills/aws-* ~/.kiro/skills/

전체가 필요 없으면 특정 스킬 디렉터리만 골라 복사해도 됩니다 (예: aws-iam, aws-cost, aws-network만 설치). 설치 후에는 자연어(평소 쓰는 일상 언어)로 요청하면 스킬이 자동 활성화됩니다.

이 표에서 볼 것은 어떤 요청이 어떤 스킬을 깨우는지의 대응 관계입니다.

4.2 9개 스킬 구성

9개 스킬은 각각 하나의 AWS 관리 영역을 맡습니다. 이 표에서 볼 것은 스킬별 담당 영역과 대표 작업입니다.

4.3 커버리지(Coverage)

9개 스킬로 기존 MCP 서버를 얼마나 대체할 수 있을까요? 9개 수동 스킬은 67개 MCP 서버 중 52개(78%)를 커버합니다. 나머지 15개는 특정 AWS 서비스가 아니거나 전문 영역이라 수동 스킬 대상에서 제외되었습니다.

이 표에서 볼 것은 제외된 15개 서버가 어느 카테고리이고 왜 빠졌는지입니다.

4.4 테스트 결과(Test Results)

실제 계정에서도 제대로 동작할까요? 실제 AWS 계정(서울 리전, IAM 역할 인증)에서 9개 스킬을 17개 항목으로 테스트해 17/17 통과했습니다. 모든 스킬이 표준 AWS 자격 증명만으로 동작합니다.

이 표에서 볼 것은 스킬별 테스트 항목과 각 항목의 통과 여부입니다.

05아키텍처 - 3단계 변환 파이프라인

이 절에서는 도구가 실제로 어떤 과정을 거쳐 코드로 바뀌는지 살펴봅니다. 변환은 스키마 추출, 정적 매핑, LLM 추론(모델에게 매핑을 추측하게 하는 단계)의 3단계로 진행됩니다. 마지막에 Jinja2(템플릿으로 코드를 찍어내는 Python 라이브러리) 생성기(Generator)가 5가지 형식의 코드를 만들어냅니다.

1. 추출(Extract) - MCP SDK stdio_client(표준 입출력으로 서버 프로세스와 통신하는 클라이언트)로 서버에 연결하고 tools/list로 스키마를 추출합니다. 결과는 ~/.mcp-tool-forge/cache/에 캐시(Cache)됩니다.
2. 정적 매핑(Static Map) - mappings/*.yaml에서 알려진 매핑을 조회합니다 (IAM 29 + DynamoDB 6 = 35개).
3. LLM 매핑(LLM Map) - 미매핑(Unmapped) 도구를 Bedrock Claude Opus 4.6에 보내 boto3 매핑을 추론합니다. --llm-assist 플래그(Flag)로 켭니다.

5.1 멀티 AWS 프로필 지원(Multi-Profile Support)

--aws-profile 옵션으로 생성되는 boto3 코드에 AWS 프로필을 설정할 수 있습니다. AWS Organizations + SSO 환경에서 여러 계정을 오가는 경우 유용합니다. 호출 시점에 프로필을 오버라이드(기본값 대신 다른 값을 지정)할 수도 있습니다.

# --aws-profile 없이 생성 (기본)
def list_users(profile_name: str | None = None, **kwargs) -> dict:
    session = boto3.Session(profile_name=profile_name)
    client = session.client('iam')
    ...

# --aws-profile prod-account 으로 생성
def list_users(profile_name: str | None = "prod-account", **kwargs) -> dict:
    session = boto3.Session(profile_name=profile_name)
    client = session.client('iam')
    ...

# 호출 시 프로필 오버라이드 가능
list_users()                                  # 기본 프로필 사용
list_users(profile_name="staging-account")    # 다른 계정으로 전환

5.2 추출 결과(Extraction Results)

이 파이프라인을 전체 서버에 돌리면 어느 정도 규모가 나올까요? 이 표에서 볼 것은 연결 성공률, 추출된 도구 수, 생성 코드의 구문 통과율입니다.

06출력 형식과 지원 서버

이 절에서는 변환 결과물이 어떤 파일로 나오는지, 그리고 어떤 서버를 변환할 수 있는지 정리합니다. 변환 결과는 5가지 형식으로 나오며, 같은 도구라도 실행 환경에 따라 쓰는 형식이 다릅니다.

이 표에서 볼 것은 형식별 출력 파일 위치와 그 형식이 쓰이는 자리입니다.

변환 대상으로 등록된 MCP 서버는 총 67개입니다. 이 표에서 볼 것은 67개 서버가 어떤 카테고리에 몇 개씩 분포하는지입니다.

07빠른 시작 - CLI 도구

이 절에서는 MCP 서버를 직접 변환하고 싶은 사람을 위해 CLI 사용법을 정리합니다. 설치, 변환, 스킬 등록까지의 명령을 순서대로 담았습니다.

# 설치(Install)
pip install -e ".[dev]"

# 서버 목록 조회(List Servers)
mcp-tool-forge list-servers
mcp-tool-forge list-servers --category "Data & Analytics"

# 도구 확인(List Tools) - 실제 MCP 서버에 연결
mcp-tool-forge list-tools --server aws-iam-mcp-server

# 모든 형식으로 변환(Convert)
mcp-tool-forge convert --server aws-iam-mcp-server --output all

# LLM 매핑(LLM Assist)
mcp-tool-forge convert --server amazon-cloudwatch-mcp-server --output all --llm-assist

# 멀티 AWS 프로필(Multi-Profile) 지원
mcp-tool-forge convert --server aws-iam-mcp-server --output boto3 --aws-profile prod-account

# Claude Code에 스킬 등록(Register)
mcp-tool-forge register --server aws-iam-mcp-server -d output

# Kiro-CLI에 스킬 등록
mcp-tool-forge register --server aws-iam-mcp-server -d output --target kiro

7.1 프로젝트 구조(Project Structure)

mcp-tool-forge/
├── .claude/skills/             # 9개 AWS Skills (이식 가능)
│   ├── aws-iam/                # IAM 사용자, 역할, 정책
│   ├── aws-cloudwatch/         # 로그, 메트릭, 알람, CloudTrail
│   ├── aws-cost/               # 비용 탐색기, 청구, 가격
│   ├── aws-infra/              # CloudFormation, EKS, ECS, Lambda
│   ├── aws-messaging/          # SNS, SQS, MQ, Step Functions
│   ├── aws-network/            # VPC, Transit Gateway, Cloud WAN, VPN
│   ├── aws-ai/                 # Bedrock, SageMaker, Kendra, Q Business
│   ├── aws-data/               # DynamoDB, Aurora, Redshift, Neptune
│   └── aws-security/           # 계정 정보, 보안 감사
├── src/mcp_to_cli/
│   ├── cli.py                  # Click CLI 진입점(Entry Point)
│   ├── pipeline.py             # 3단계 오케스트레이터(Orchestrator)
│   ├── connector.py            # MCP SDK stdio_client 연결
│   ├── registry.yaml           # 67개 서버 설정(Configuration)
│   ├── llm_mapper.py           # Bedrock Claude Opus 4.6 매핑
│   ├── validator.py            # 생성 코드 검증/자동 수정
│   ├── generators/             # 5가지 출력 생성기(Generator)
│   ├── mappings/               # 정적 YAML 매핑 (IAM, DynamoDB)
│   └── templates/              # 6개 Jinja2 템플릿(Template)
├── tests/                      # 38개 pytest 테스트
└── docs/                       # 아키텍처 및 설계 문서

7.2 요구사항(Requirements)

Skills만 쓰는 경로와 CLI 도구 전체를 쓰는 경로의 요구사항이 다릅니다. Skills 경로는 AWS 자격 증명 외에 아무것도 요구하지 않습니다. 이 표에서 볼 것은 두 경로에서 각 항목이 필요한지 여부입니다.