구성¶

이 가이드는 구성 파일 구조, 서버 설정 및 모범 사례를 포함하여 Kiro와 함께 Model Context Protocol(MCP) 서버를 구성하는 방법에 대한 자세한 정보를 제공합니다.

구성 파일 구조¶

MCP 구성 파일은 다음 구조의 JSON 형식을 사용합니다:

json

{ "mcpServers": { "local-server-name": { "command": "command-to-run-server", "args": ["arg1", "arg2"], "env": { "ENV_VAR1": "hard-coded-variable", "ENV_VAR2": "${EXPANDED_VARIABLE}" }, "disabled": false, "autoApprove": ["tool_name1", "tool_name2"], "disabledTools": ["tool_name3"] }, "remote-server-name": { "url": "https://endpoint.to.connect.to", "headers": { "HEADER1": "value1", "HEADER2": "value2" }, "disabled": false, "autoApprove": ["tool_name1", "tool_name2"], "disabledTools": ["tool_name3"] } } }

구성 속성¶

원격 서버¶

속성	타입	필수	설명
`url`	String	Yes	원격 MCP 서버의 HTTPS 엔드포인트 (또는 localhost의 HTTP 엔드포인트)
`headers`	Object	No	연결 중에 MCP 서버에 전달할 헤더
`env`	Object	No	서버 프로세스의 환경 변수
`disabled`	Boolean	No	서버가 비활성화되었는지 여부 (기본값: false)
`autoApprove`	Array	No	프롬프트 없이 자동 승인할 도구 이름 (모든 도구를 자동 승인하려면 "*" 사용)
`disabledTools`	Array	No	에이전트를 호출할 때 생략할 도구 이름

로컬 서버¶

속성	타입	필수	설명
`command`	String	Yes	MCP 서버를 실행할 명령
`args`	Array	Yes	명령에 전달할 인수
`env`	Object	No	서버 프로세스의 환경 변수
`disabled`	Boolean	No	서버가 비활성화되었는지 여부 (기본값: false)
`autoApprove`	Array	No	프롬프트 없이 자동 승인할 도구 이름 (모든 도구를 자동 승인하려면 "*" 사용)
`disabledTools`	Array	No	에이전트를 호출할 때 생략할 도구 이름

구성 위치¶

MCP 서버는 두 가지 수준에서 구성할 수 있습니다:

워크스페이스 수준: .kiro/settings/mcp.json
- 현재 워크스페이스에만 적용
- 프로젝트별 MCP 서버에 이상적
- 사용자 수준: ~/.kiro/settings/mcp.json
- 모든 워크스페이스에 전역적으로 적용
- 자주 사용하는 MCP 서버에 최적

두 파일이 모두 존재하는 경우 워크스페이스 설정이 우선 적용되어 구성이 병합됩니다.

구성 파일 생성¶

명령 팔레트 사용¶

명령 팔레트 열기:
- Mac: Cmd + Shift + P
- Windows/Linux: Ctrl + Shift + P
- "MCP"를 검색하고 다음 옵션 중 하나 선택:
- Kiro: Open workspace MCP config (JSON) - 워크스페이스 수준 구성
- Kiro: Open user MCP config (JSON) - 사용자 수준 구성

Kiro 패널 사용¶

Kiro 패널 열기
Open MCP Config 아이콘 선택

json

{ "mcpServers": { "web-search": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-bravesearch" ], "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" } } } }

환경 변수¶

많은 MCP 서버는 인증 또는 구성을 위해 환경 변수가 필요합니다:

json

{ "mcpServers": { "server-name": { "env": { "API_KEY": "${YOUR_API_KEY}", "DEBUG": "true", "TIMEOUT": "30000" } } } }

서버 임시 비활성화¶

구성을 제거하지 않고 MCP 서버를 임시로 비활성화하려면:

json

{ "mcpServers": { "server-name": { "disabled": true } } }

보안 고려 사항¶

MCP 서버를 구성할 때 자격 증명과 시스템을 보호하기 위해 보안 모범 사례를 따르세요:

민감한 값을 하드코딩하는 대신 환경 변수 참조 (예: ${API_TOKEN}) 사용
자격 증명이 포함된 구성 파일을 버전 관리에 커밋하지 않음
신뢰할 수 있는 원격 서버에만 연결
autoApprove에 추가하기 전에 도구 권한 검토

포괄적인 보안 가이드는 MCP 보안 모범 사례 페이지를 참조하세요.

구성 문제 해결¶

MCP 구성이 작동하지 않는 경우:

JSON 구문 검증:
- 구문 오류 없이 JSON이 유효한지 확인
- 누락된 쉼표, 따옴표 또는 괄호 확인
- 명령 경로 확인:
- 지정된 명령이 PATH에 존재하는지 확인
- 터미널에서 직접 명령을 실행해 보기
- 환경 변수 확인:
- 필요한 모든 환경 변수가 설정되어 있는지 확인
- 환경 변수 이름의 오타 확인
- 구성 변경 사항 저장:
- 파일을 저장하면 MCP 구성 변경 사항이 자동으로 적용됨
- 구성 파일을 저장(Cmd+S)하기만 하면 서버가 다시 연결됨