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"
      },
      "oauth": {
        "clientId": "your-app-client-id"
      },
      "oauthScopes": ["scope1", "scope2"],
      "disabled": false,
      "autoApprove": ["tool_name1", "tool_name2"],
      "disabledTools": ["tool_name3"]
    }
  }
}

속성 개요

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

로컬(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
    }
  }
}

OAuth 인증

OAuth가 필요한 원격 서버에 연결하면 Kiro가 브라우저 기반 OAuth 플로우를 자동으로 처리합니다. 대부분의 서버는 Dynamic Client Registration(DCR)을 사용하므로 별도 설정이 필요 없습니다. 연결만 하면 Kiro가 인가 페이지를 열어 줍니다.

서버가 DCR을 지원하지 않는다면 직접 클라이언트 ID를 지정해야 합니다. MCP 설정에 oauth.clientId와 필요한 스코프를 함께 추가합니다.

{
  "mcpServers": {
    "github": {
      "url": "https://api.github.com/mcp",
      "oauth": {
        "clientId": "your-github-app-client-id"
      },
      "oauthScopes": ["repo", "user"]
    }
  }
}

OAuth 동작을 제어하는 속성은 다음과 같습니다(위의 속성 개요도 함께 참고하세요).

oauth.clientId는 언제 쓰나

일부 서비스는 Dynamic Client Registration(DCR)을 지원하지 않아, 개발자 포털에서 OAuth 앱을 직접 등록해야 합니다. 등록한 앱의 클라이언트 ID를 oauth.clientId에 넣으면 Kiro가 별도의 프록시 없이 인증을 수행할 수 있습니다.

이 방식은 Cognito, Auth0, Okta 같은 인증 서버에서 동작합니다. 단, 앱이 PKCE를 사용하는 public client(client secret 없음)로 구성되어 있어야 합니다.

주의: public OAuth 클라이언트(client secret 없이 PKCE 사용)만 지원됩니다. secret으로 구성된 Slack 앱이나 confidential client 유형의 Cognito 앱처럼 client_secret이 필요한 서비스는 이 설정으로 동작하지 않습니다.

예시: AWS Cognito (public client)

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3100/mcp",
      "oauth": {
        "clientId": "your-cognito-app-client-id",
        "redirectUri": "127.0.0.1:8080"
      },
      "oauthScopes": ["openid", "email", "profile"]
    }
  }
}

MCP 서버는 자격 증명 공급자의 엔드포인트를 가리키는 /.well-known/oauth-authorization-server 메타데이터 문서를 제공해야 하며, 공급자의 JWKS로 Bearer 토큰을 검증해야 합니다.

그 밖의 서비스

JSON 형태는 모든 서비스에서 동일하며, url·clientId·oauthScopes만 달라집니다.

서비스URL예시 스코프
GitHubhttps://api.github.com/mcp["repo", "user"]
Figmahttps://mcp.figma.com/mcp["files:read"]

토큰 만료와 재인증

세션 도중 OAuth 액세스 토큰이 만료되고 사용할 수 있는 refresh 토큰이 없으면, Kiro가 만료를 감지해 브라우저 기반 인증 플로우를 자동으로 다시 시작합니다. 토큰이 만료되면 MCP 패널에 경고 표시와 Re-authenticate 버튼이 나타납니다.

OAuth 스코프 문제 해결

OAuth 스코프 관련 오류가 발생한다면, 빈 배열을 지정해 스코프 요구를 우회할 수 있습니다.

{
  "mcpServers": {
    "github": {
      "url": "https://api.github.com/mcp",
      "oauthScopes": []
    }
  }
}

보안에 관한 고려 사항

자격 증명을 평문으로 두지 마세요. 토큰을 직접 적어두면 실수로 커밋되거나 다른 사람에게 노출될 위험이 큽니다.

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

설정 문제 해결

  1. JSON 문법 검사 — 콤마, 따옴표, 괄호가 빠진 곳이 없는지 다시 확인합니다.
  2. command 경로 확인 — 명령이 PATH에 있는지, 터미널에서 직접 실행했을 때 동작하는지 점검합니다.
  3. 환경 변수 확인 — 참조한 변수가 모두 정의되어 있는지, 이름에 오타가 없는지 살핍니다.
  4. 저장 후 자동 반영 — Cmd+S(또는 Ctrl+S)로 저장하면 Kiro가 변경 사항을 감지해 서버를 다시 연결합니다.
워크스페이스 설정과 사용자 설정 사이에서 어떤 값이 적용되는지 헷갈린다면, 잠시 한쪽을 disabled: true로 두고 동작 차이를 비교해 보면 빠르게 원인을 좁힐 수 있습니다.