MCP Configuration

Kiro에서 MCP 서버를 연결하기 위해 작성하는 JSON 설정 파일의 위치, 구조, 그리고 안전하게 운영하기 위한 요령을 정리합니다.

설정 파일은 어떻게 생겼나

MCP 서버 설정은 JSON 한 덩어리로 표현됩니다. 최상위 키는 항상 mcpServers이며, 그 아래에 각 서버를 식별할 이름을 넣고 옵션을 지정합니다. 로컬 프로세스로 실행되는 서버와 원격 엔드포인트에 접속하는 서버 두 가지 형태를 모두 한 파일에 섞어 둘 수 있습니다.

{
  "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"]
    }
  }
}

속성 개요

원격(remote) 서버의 주요 속성:

• url (필수, String): 접속할 HTTPS 엔드포인트. localhost인 경우에 한해 HTTP도 허용됩니다.
• headers (선택, Object): 연결 시 함께 전송할 헤더.
• disabled (선택, Boolean): 기본값은 false.
• autoApprove (선택, Array): 사용자 확인 없이 호출을 허가할 도구 이름 목록. "*"를 넣으면 모든 도구가 자동 승인됩니다.
• disabledTools (선택, Array): Agent에 노출하지 않을 도구 이름 목록.

로컬(local) 서버는 위 옵션 중 url·headers 대신 command(필수)와 args(필수)를 사용합니다. env, disabled, autoApprove, disabledTools는 양쪽 모두 동일하게 지원됩니다.

설정 파일은 어디에 두어야 할까

Kiro는 두 단계의 설정을 인식합니다.

1. 워크스페이스 단위: .kiro/settings/mcp.json — 현재 프로젝트에서만 적용됩니다. 특정 저장소에 종속된 서버를 둘 때 적합합니다.
2. 사용자 단위: ~/.kiro/settings/mcp.json — 모든 워크스페이스에 공통 적용됩니다. 자주 쓰는 서버를 여기에 두면 편리합니다.

두 파일이 모두 존재하면 내용을 병합하며, 같은 키가 중복될 경우 워크스페이스 설정이 우선합니다.

설정 파일 만들기

Command Palette에서 바로 열기

1. Command Palette를 엽니다. macOS는 Cmd + Shift + P, Windows/Linux는 Ctrl + Shift + P.
2. MCP로 검색해서 다음 중 하나를 선택합니다.
   • Kiro: Open workspace MCP config (JSON)
   • Kiro: Open user MCP config (JSON)

Kiro 패널에서 열기

1. Kiro 패널을 엽니다.
2. Open MCP Config 아이콘을 누릅니다.

다음은 Brave Search 서버를 로컬 프로세스로 실행하도록 구성한 예시입니다.

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

환경 변수 활용

API 키나 토큰처럼 환경마다 달라지는 값은 ${VAR_NAME} 문법으로 참조합니다. 셸에서 export된 값이 그대로 치환되어 서버 프로세스에 전달됩니다.

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

서버를 임시로 끄고 싶다면

설정 자체를 지우지 않고 잠시만 비활성화하려면 disabled 값을 true로 두면 됩니다. 다시 켤 때는 false로 바꾸기만 하면 됩니다.

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

보안에 관한 고려 사항

• 비밀값은 가능한 한 ${API_TOKEN} 같은 환경 변수 참조로 처리합니다.
• 자격 증명이 들어 있는 설정 파일을 버전 관리에 포함시키지 않습니다.
• 원격 서버는 신뢰할 수 있는 출처에만 연결합니다.
• autoApprove에 어떤 도구를 넣을지 신중히 검토합니다. 한번 승인된 도구는 사용자 확인 없이 호출됩니다.

더 자세한 내용은 MCP Security Best Practices 문서를 참고하세요.

설정 문제 해결

1. JSON 문법 검사 — 콤마, 따옴표, 괄호가 빠진 곳이 없는지 다시 확인합니다.
2. command 경로 확인 — 명령이 PATH에 있는지, 터미널에서 직접 실행했을 때 동작하는지 점검합니다.
3. 환경 변수 확인 — 참조한 변수가 모두 정의되어 있는지, 이름에 오타가 없는지 살핍니다.
4. 저장 후 자동 반영 — Cmd+S(또는 Ctrl+S)로 저장하면 Kiro가 변경 사항을 감지해 서버를 다시 연결합니다.