Kiro 핸드북

테마

MCP (Model Context Protocol) ​

목표 ​

MCP의 개념과 설정 방법을 이해합니다. 외부 도구·API·데이터 소스를 Kiro에 연결하여 에이전트의 기능을 확장하는 프로토콜입니다.

MCP란? ​

MCP(Model Context Protocol)는 AI 모델이 외부 도구와 데이터 소스에 안전하게 연결할 수 있게 해주는 개방형 표준 프로토콜입니다.

연결하기 전에 확인할 것 ​

MCP 서버는 외부 서비스·로컬 파일·명령에 접근할 수 있습니다. 먼저 서버의 출처와 실행 명령을 확인하고, 필요한 서버만 연결하세요. 파일 시스템 접근은 대상 디렉터리를 좁게 지정합니다. 토큰·API 키가 필요한 서버는 해당 서버의 공식 인증 방식을 따르고, 실제 비밀값이 든 workspace 설정을 저장소에 커밋하지 마세요. 가능하면 사용자 수준 설정이나 운영체제·조직의 비밀 관리 수단을 사용합니다.

autoApprove는 읽기 전용이며 범위가 명확한 도구에만 최소로 적용합니다. 파일 쓰기·삭제, 이슈 생성·병합, 메시지 전송처럼 부작용이 있는 도구는 수동 승인을 유지하세요.

활용 예시 ​

  • 웹 검색으로 최신 정보 참조
  • AWS 문서 검색
  • GitHub 이슈·PR 연동
  • 데이터베이스 조회
  • API 테스트

설정 위치 (두 레벨) ​

레벨경로적용 범위
Workspace.kiro/settings/mcp.json현재 프로젝트만
User글로벌 설정모든 프로젝트

Workspace 설정이 우선. 두 설정은 병합됩니다.

사전 준비 ​

  • Kiro IDE 로그인 완료
  • uvx 설치 (MCP 서버 실행에 필요)

uvx 설치 ​

bash
# macOS (Homebrew)
brew install uv

# 설치 확인
uvx --version

해볼 것 ​

1단계: MCP 설정 파일 생성 ​

Kiro 패널 → MCP Servers 섹션 → 설정 파일 생성 버튼 클릭.

또는 채팅에서:

웹 콘텐츠에 접근할 수 있는 Fetch MCP 서버를 설정해주세요.
설정 요구사항:
- 서버명: fetch
- 웹 페이지 내용 가져오기 기능
- 자동 승인 설정
설정 파일 위치: .kiro/settings/mcp.json

2단계: 생성된 설정 확인 ​

json
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "disabled": false,
      "autoApprove": ["fetch"]
    }
  }
}

3단계: MCP 활용 테스트 ​

Fetch MCP 서버를 사용해서 다음 정보를 가져와주세요:
https://developer.mozilla.org/en-US/docs/Web/API/localStorage
로컬 스토리지 사용법에 대한 최신 정보를 요약해주세요.

다른 유용한 MCP 서버 ​

AWS 문서 서버:

json
{
  "aws-docs": {
    "command": "uvx",
    "args": ["awslabs.aws-documentation-mcp-server@latest"],
    "disabled": false,
    "autoApprove": ["search_documentation"]
  }
}

GitHub MCP (이슈·PR 조회):

json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token>" },
    "disabled": false,
    "autoApprove": []
  }
}

autoApprove를 빈 배열로 두면 모든 도구 호출에 수동 승인이 필요합니다. 이슈 생성·PR 머지 등 민감한 작업을 실수로 자동 실행하지 않도록 빈 배열을 권장합니다.

Filesystem MCP (로컬 폴더 읽기):

json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed-dir"],
    "disabled": false,
    "autoApprove": ["read_file", "list_directory"]
  }
}

args에 지정한 경로만 접근 가능합니다. 허용할 디렉터리를 최소 범위로 제한하세요.

여러 서버를 함께 설정하기 ​

하나의 mcpServers 객체 안에 여러 서버 키를 나란히 두면 됩니다:

json
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "disabled": false,
      "autoApprove": ["fetch"]
    },
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "disabled": false,
      "autoApprove": ["search_documentation"]
    }
  }
}

서버 키 이름은 자유이지만, 역할을 알 수 있는 짧은 이름을 권장합니다.

npx vs uvx ​

실행기대상설치 방법
uvxPython 기반 MCP 서버brew install uv (macOS)
npxNode 기반 MCP 서버Node.js 설치 시 포함

서버 공식 문서가 지정하는 실행기를 사용하세요. 잘못된 실행기를 지정하면 서버가 시작되지 않습니다.

설정 속성 ​

속성타입설명
commandString (필수)서버 실행 명령
argsArray (필수)명령 인자
envObject (선택)환경 변수
disabledBoolean (선택)비활성화 여부
autoApproveArray (선택)자동 승인할 도구 목록

MCP 심화: Playwright로 실행 앱 E2E 테스트 ​

Playwright MCP를 연결하면 Kiro가 실제 브라우저를 구동해 실행 중인 앱을 자율 테스트할 수 있습니다. 등록 → 글 작성 → 결과 확인 같은 사용자 흐름을 브라우저에서 직접 수행합니다.

json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
  • 첫 실행은 브라우저 바이너리 다운로드로 30–60초가 걸릴 수 있습니다(한 번만).
  • MCP Servers 패널에서 playwright 서버가 green 상태인지 확인합니다.
  • Kiro는 navigate → click → fill → screenshot 도구 호출을 순차 실행하며, 스크린샷을 보고 다음 행동을 추론해 예상 밖 화면에도 적응합니다.

테스트 접근 비교 ​

관점수동MCP 기반전통 E2E 스크립트
속도2–5분/시나리오1–2분/시나리오초 단위(셋업 후)
셋업없음1회 MCP 설정스크립트 작성·유지
적응성높음(사람)높음(AI 추론)낮음(취약 셀렉터)
적합주관적 평가개발 중 검증CI/CD 회귀

💡 적용 원칙

MCP 기반 테스트는 개발 시점 검증에 적합합니다. 프로덕션 CI/CD에는 Playwright 테스트 파일을 유지하고, Kiro에게 탐색 결과를 바탕으로 테스트 파일 생성을 요청할 수 있습니다.

실행 중인 To-Do 앱을 Playwright MCP로 자율 E2E 테스트하는 전체 핸즈온은 실습 Scene E에서 단계별로 진행합니다.

기대 결과 ​

  • .kiro/settings/mcp.json 파일에 MCP 서버 설정 완료
  • 외부 웹 정보를 Kiro가 가져와 응답에 활용
  • AI 에이전트의 기능이 외부 도구로 확장됨

🔒 autoApprove 보안 원칙

autoApprove에는 읽기 전용 도구만 등록하세요. 파일 쓰기·삭제, 이슈 생성·머지, 메시지 전송 등 부작용이 있는 도구는 수동 승인을 유지하는 것이 안전합니다.

✅ 핵심 요약

  • MCP = AI가 외부 도구·API와 연결되는 개방형 표준
  • .kiro/settings/mcp.json으로 설정
  • Fetch(웹), AWS Docs, GitHub 등 다양한 서버 연결 가능
  • 실습 Scene E에서 실전 실습 진행

통합 관점

MCP와 같은 공식 Features 형제 항목 및 선택 기준은 Context Engineering에서 확인하세요.

🚨 문제 해결

  • MCP 연결 안 됨: 인터넷 확인 / uvx --version으로 설치 확인 / Kiro 재시작.
  • JSON 문법 오류: 쉼표·따옴표·괄호 확인. 마지막 항목 뒤에 쉼표 금지.
  • "command not found": uvx(또는 npx) 명령이 PATH에 있는지 확인.
  • 보안: API 키가 포함된 설정 파일은 .gitignore에 추가하세요.
  • env 값이 반영 안 됨: 설정 파일 저장 후 MCP 서버를 재시작해야 합니다. Kiro 재시작 또는 명령 팔레트에서 MCP 서버 재시작 명령을 검색하세요.

© 2026 Kiro 핸드북 · 비공식 자료이며 AWS와 무관합니다.