MCP

관리자가 조직 차원에서 Kiro의 MCP 서버 사용을 통제하는 엔터프라이즈 거버넌스 기능을 설명합니다.

기본적으로 사용자는 Kiro 클라이언트에서 임의의 MCP 서버를 사용할 수 있습니다. 관리자는 사용자의 MCP 서버 사용을 전면 비활성화하거나, 사용자가 사용할 수 있도록 검증된 MCP 서버 목록만 허용하도록 지정할 수 있습니다.

이러한 제한은 Kiro 프로필의 일부인 MCP 온/오프 토글과 MCP 레지스트리 속성으로 제어합니다. 프로필은 조직 수준 또는 계정 수준에서 정의할 수 있으며, 계정 수준 프로필이 조직 수준 프로필보다 우선합니다. 조직의 기본 MCP 정책을 지정한 뒤 특정 계정에 대해 이를 재정의할 수 있습니다. 예를 들어 조직 전체에서는 MCP를 비활성화하되 특정 팀(계정)에는 허용 목록과 함께 활성화할 수 있습니다.

MCP 거버넌스는 IAM Identity Center 또는 API 키로 인증하는 사용자에게 적용됩니다. Builder ID 및 소셜 인증 사용자는 조직 수준 MCP 통제의 대상이 아닙니다.

조직에서 MCP 비활성화

계정 또는 조직에서 MCP를 비활성화하려면 다음을 수행합니다.

1. Kiro 콘솔을 엽니다.
2. Settings를 선택합니다.
3. Shared settings에서 Model Context Protocol (MCP)를 Off로 전환합니다.

MCP가 꺼져 있으면 클라이언트는 사용자 구성, 레거시, 레지스트리, 세션 주입을 포함한 모든 MCP 서버를 억제하며, 에이전트가 사용할 수 있는 MCP 도구는 없습니다. /mcp 패널에는 MCP has been disabled by your administrator가 표시됩니다.

또한 클라이언트가 거버넌스 API에 연결할 수 없는 경우 MCP는 안전하게 차단(fail closed)됩니다. 즉 MCP가 비활성화되고 /mcp에는 Failed to retrieve MCP settings — MCP disabled가 표시됩니다. 이러한 fail-closed 이벤트는 대개 일시적이며, 클라이언트가 거버넌스 API에 다시 연결되면 해소됩니다.

조직에 대한 MCP 허용 목록 지정

사용자가 접근할 수 있는 MCP 서버를 통제하려면, 허용할 서버를 담은 JSON 파일을 만들어 HTTPS로 제공한 다음 그 URL을 Kiro 프로필에 추가합니다. 이 프로필을 사용하는 Kiro 클라이언트에서는 허용 목록에 있는 MCP 서버에만 접근이 허용됩니다.

MCP 레지스트리 URL 지정

1. Kiro 콘솔을 엽니다.
2. Settings를 선택합니다.
3. Shared settings에서 Model Context Protocol (MCP)가 On인지 확인합니다.
4. MCP Registry URL 필드에서 Edit를 선택합니다.
5. 허용 목록에 포함된 MCP 서버가 담긴 MCP 레지스트리 JSON 파일의 URL을 입력합니다.
6. Save를 선택합니다.

MCP 레지스트리 URL은 데이터 암호화 정책에 따라 전송 중과 저장 시 모두 암호화됩니다.

MCP 레지스트리 파일 형식

레지스트리 JSON 파일의 형식은 MCP 레지스트리 표준 v0.1의 서버 스키마 JSON의 하위 집합입니다. Kiro가 지원하는 하위 집합의 JSON 스키마 정의는 이 문서 끝의 레지스트리 스키마 섹션에서 확인할 수 있습니다.

다음 예시는 원격(HTTP) MCP 서버와 로컬(stdio) MCP 서버 정의를 모두 포함한 MCP 레지스트리 파일을 보여줍니다.

{
  "servers": [
    {
      "server": {
        "name": "my-remote-server",
        "title": "My server",
        "description": "My server description",
        "version": "1.0.0",
        "remotes": [
          {
            "type": "streamable-http",
            "url": "https://acme.com/my-server",
            "headers": [
              {
                "name": "X-My-Header",
                "value": "SomeValue"
              }
            ]
          }
        ]
      }
    },
    {
      "server": {
        "name": "my-local-server",
        "title": "My server",
        "description": "My server description",
        "version": "1.0.0",
        "packages": [
          {
            "registryType": "npm",
            "registryBaseUrl": "https://npm.acme.com",
            "identifier": "@acme/my-server",
            "transport": {
              "type": "stdio"
            },
            "runtimeArguments": [
              {
                "type": "positional",
                "value": "-q"
              }
            ],
            "packageArguments": [
              {
                "type": "positional",
                "value": "start"
              }
            ],
            "environmentVariables": [
              {
                "name": "ENV_VAR",
                "value": "ENV_VAR_VALUE"
              }
            ]
          }
        ]
      }
    }
  ]
}

다음 표는 레지스트리 JSON 파일의 속성을 나열합니다. 별도 명시가 없는 한 모든 속성은 필수입니다. 전체 JSON 스키마는 레지스트리 스키마 섹션을 참고하세요.

중첩된 속성은 상위 속성에서 들여쓰기하여 표시합니다. 예를 들어 headers는 remotes의 하위 속성이며, name과 value는 headers의 하위 속성입니다.

MCP 레지스트리 파일 제공

MCP 레지스트리 JSON 파일은 Amazon S3, Apache, nginx 등 임의의 웹 서버를 사용해 HTTPS로 제공합니다. 이 URL은 사용자 컴퓨터의 Kiro 클라이언트에서 접근할 수 있어야 하지만, 회사 네트워크 내부에 비공개로 둘 수 있습니다.

HTTPS 엔드포인트는 신뢰할 수 있는 인증 기관(CA)이 서명한 유효한 SSL 인증서를 갖추어야 합니다. 자체 서명 인증서는 지원되지 않습니다.

Kiro는 시작 시점과 24시간마다 MCP 레지스트리를 가져옵니다. 주기적 동기화 중에 로컬에 설치된 MCP 서버가 더 이상 레지스트리에 없으면, Kiro는 해당 서버를 종료하고 사용자가 다시 추가하지 못하도록 합니다. 로컬에 설치된 서버의 버전이 레지스트리의 서버와 다르면, Kiro는 레지스트리에 정의된 버전으로 서버를 다시 실행합니다.

매개변수 재정의

레지스트리 MCP 서버 매개변수(URL, 패키지 식별자, runtimeArguments 등)는 읽기 전용입니다. 다만 사용자는 다음을 수행할 수 있습니다.

1. 로컬 MCP 서버에 대해 추가 환경 변수를 지정할 수 있습니다.
2. 원격 MCP 서버에 대해 추가 HTTP 헤더를 지정할 수 있습니다.
3. 요청 시간 제한(timeout)을 변경할 수 있습니다.
4. MCP 서버 범위(Global, Workspace 또는 특정 Agent Configuration)를 설정할 수 있습니다.
5. MCP 도구 신뢰 권한을 설정할 수 있습니다.

사용자가 지정한 환경 변수나 HTTP 헤더는 레지스트리 정의를 재정의합니다. 이를 통해 사용자는 인증 키나 로컬 폴더 경로처럼 자신의 환경에 특화된 속성을 지정할 수 있습니다.

MCP 레지스트리 JSON 스키마

다음 JSON 스키마는 Kiro가 지원하는 MCP 레지스트리 파일 형식을 정의합니다. 이 스키마를 사용해 직접 만든 레지스트리 파일을 검증할 수 있습니다.

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "properties": {
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "server": {
            "$ref": "#/definitions/ServerDetail"
          }
        },
        "required": [
          "server"
        ]
      }
    }
  },
  "definitions": {
    "ServerDetail": {
      "properties": {
        "name": {
          "description": "Server name. Must be unique within a given registry file.",
          "example": "weather-mcp",
          "maxLength": 200,
          "minLength": 3,
          "pattern": "^[a-zA-Z0-9._-]+$",
          "type": "string"
        },
        "title": {
          "description": "Optional human-readable title or display name for the MCP server. MCP subregistries or clients MAY choose to use this for display purposes.",
          "example": "Weather API",
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "description": {
          "description": "Clear human-readable explanation of server functionality. Should focus on capabilities, not implementation details.",
          "example": "MCP server providing weather data and forecasts via OpenWeatherMap API",
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Version string for this server. SHOULD follow semantic versioning (e.g., '1.0.2', '2.1.0-alpha'). Equivalent of Implementation.version in MCP specification. Non-semantic versions are allowed but may not sort predictably. Version ranges are rejected (e.g., '^1.2.3', '~1.2.3', '>=1.2.3', '1.x', '1.*').",
          "example": "1.0.2",
          "maxLength": 255,
          "type": "string"
        },
        "packages": {
          "items": {
            "$ref": "#/definitions/Package"
          },
          "type": "array",
          "minItems": 0,
          "maxItems": 1
        },
        "remotes": {
          "items": {
            "anyOf": [
              {
                "$ref": "#/definitions/StreamableHttpTransport"
              },
              {
                "$ref": "#/definitions/SseTransport"
              }
            ]
          },
          "type": "array",
          "minItems": 0,
          "maxItems": 1
        }
      },
      "required": [
        "name",
        "description",
        "version"
      ],
      "type": "object"
    },
    "Package": {
      "properties": {
        "registryType": {
          "description": "Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'oci')",
          "enum": [
            "npm",
            "pypi",
            "oci"
          ],
          "type": "string"
        },
        "registryBaseUrl": {
          "description": "Base URL of the package registry",
          "examples": [
            "https://registry.npmjs.org",
            "https://pypi.org",
            "https://docker.io"
          ],
          "format": "uri",
          "type": "string"
        },
        "identifier": {
          "description": "Package identifier - either a package name (for registries) or URL (for direct downloads)",
          "examples": [
            "@modelcontextprotocol/server-brave-search",
            "https://github.com/example/releases/download/v1.0.0/package.mcpb"
          ],
          "type": "string"
        },
        "transport": {
          "anyOf": [
            {
              "$ref": "#/definitions/StdioTransport"
            },
            {
              "$ref": "#/definitions/StreamableHttpTransport"
            },
            {
              "$ref": "#/definitions/SseTransport"
            }
          ],
          "description": "Transport protocol configuration for the package"
        },

        "runtimeArguments": {
          "description": "A list of arguments to be passed to the package's runtime command (such as docker or npx).",
          "items": {
            "$ref": "#/definitions/PositionalArgument"
          },
          "type": "array"
        },
        "packageArguments": {
          "description": "A list of arguments to be passed to the package's binary.",
          "items": {
            "$ref": "#/definitions/PositionalArgument"
          },
          "type": "array"
        },
        "environmentVariables": {
          "description": "A mapping of environment variables to be set when running the package.",
          "items": {
            "$ref": "#/definitions/KeyValueInput"
          },
          "type": "array"
        }
      },
      "required": [
        "registryType",
        "identifier",
        "transport"
      ],
      "type": "object"
    },
    "StdioTransport": {
      "properties": {
        "type": {
          "description": "Transport type",
          "enum": [
            "stdio"
          ],
          "example": "stdio",
          "type": "string"
        }
      },
      "required": [
        "type"
      ],
      "type": "object"
    },
    "StreamableHttpTransport": {
      "properties": {
        "type": {
          "description": "Transport type",
          "enum": [
            "streamable-http"
          ],
          "example": "streamable-http",
          "type": "string"
        },
        "url": {
          "description": "URL template for the streamable-http transport. Variables in {curly_braces} reference argument valueHints, argument names, or environment variable names. After variable substitution, this should produce a valid URI.",
          "example": "https://api.example.com/mcp",
          "type": "string"
        },
        "headers": {
          "description": "HTTP headers to include",
          "items": {
            "$ref": "#/definitions/KeyValueInput"
          },
          "type": "array"
        }
      },
      "required": [
        "type",
        "url"
      ],
      "type": "object"
    },
    "SseTransport": {
      "properties": {
        "type": {
          "description": "Transport type",
          "enum": [
            "sse"
          ],
          "example": "sse",
          "type": "string"
        },
        "url": {
          "description": "Server-Sent Events endpoint URL",
          "example": "https://mcp-fs.example.com/sse",
          "format": "uri",
          "type": "string"
        },
        "headers": {
          "description": "HTTP headers to include",
          "items": {
            "$ref": "#/definitions/KeyValueInput"
          },
          "type": "array"
        }
      },
      "required": [
        "type",
        "url"
      ],
      "type": "object"
    },
    "PositionalArgument": {
      "properties": {
        "type": {
          "enum": [
            "positional"
          ],
          "example": "positional",
          "type": "string"
        },
        "value": {
          "description": "The value for the input.",
          "type": "string"
        }
      },
      "required": [
        "type",
        "value"
      ],
      "type": "object"
    },
    "KeyValueInput": {
      "properties": {
        "name": {
          "description": "Name of the header or environment variable.",
          "example": "SOME_VARIABLE",
          "type": "string"
        },
        "value": {
          "description": "The value for the input.",
          "type": "string"
        }
      },
      "required": [
        "name"
      ],
      "type": "object"
    }
  },
  "required": [
    "servers"
  ],
  "type": "object"
}