# 레지스트리 MCP 엔드포인트 사용
**예정된 네임스페이스 마이그레이션**
AWS 에이전트 레지스트리는 현재 bedrock-agentcore 네임스페이스에서 공개 미리 보기 중입니다. 2026년 8월 6일부터 서비스는 에이전트 레지스트리 네임스페이스로 이동합니다. AWS 에이전트 레지스트리를 사용하는 경우 엔드포인트, IAM 정책, SDK 클라이언트, CLI 스크립트 및 레지스트리 데이터를 업데이트해야 합니다. 공개 미리 보기에서 마이그레이션하는 방법에 대한 자세한 내용은 [포괄적인 레지스트리 마이그레이션 가이드를](registry-faq.md) 참조하세요.
## 개요
각 레지스트리는 [2025-11-25 사양](https://modelcontextprotocol.io/specification/2025-11-25)에 따라 MCP 호환 엔드포인트를 노출합니다. 엔드포인트는 레지스트리 레코드 검색을 위한 도구 목록 및 도구 호출을 지원합니다.
```
https://bedrock-agentcore..amazonaws.com/registry//mcp
```
MCP에는 "search\_registry\_records"라는 도구 하나가 포함되어 있습니다.
```
Tool name: search_registry_records
Description:
Searches for registry records using natural language queries. Returns metadata for matching records.
Parameters:
- searchQuery (required): string - Natural language search query
- maxResults: integer - Maximum number of results to return (1-20, default 10)
- filter: object - Optional metadata filter using structured JSON operators. Supports field-level operators ($eq, $ne,
$in) and logical operators ($and, $or) on filterable fields (name, descriptorType, version). Example:
{"descriptorType": {"$eq": "MCP"}}
```
Kiro, Claude 등과 같은 기존 MCP 클라이언트에서 레지스트리에 연결할 수 있습니다.
## 기존 MCP 클라이언트에서 OAuth 기반 레지스트리 MCP 엔드포인트에 연결
### 권한
MCP 엔드포인트는 동일한 **CustomJWTAuthorizerConfiguration**을 사용하여 수신 요청을 승인합니다.
`.well-known/oauth-protected-resource` 경로는 입니다`https://bedrock-agentcore..amazonaws.com/.well-known/oauth-protected-resource/registry//mcp`.
클라이언트는 `WWW-Authenticate` 헤더에서도 메타데이터를 검색할 수 있습니다.
```
www-authenticate: Bearer resource_metadata="https://bedrock-agentcore..amazonaws.com/.well-known/oauth-protected-resource/registry//mcp"
```
액세스 토큰을 얻은 후에는 다음을 검증할 수 있습니다.
```
curl -s -X POST "https://bedrock-agentcore..amazonaws.com/registry//mcp" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_registry_records","arguments":{"searchQuery":"weather"}}}'
```
권한 부여 서버 및 조직의 보안 요구 사항에 따라 다음 방법 중 하나를 선택하여 MCP 클라이언트를 구성할 수 있습니다.
1. 베어러 토큰: 별도의 프로세스를 사용하여 베어러 토큰을 가져오고 MCP 클라이언트 헤더에서 구성합니다.
1. 사전 등록된 클라이언트: 권한 부여 서버에서 클라이언트를 생성하고 레지스트리 구성에서 클라이언트를 허용 목록에 추가합니다.
1. 동적 클라이언트 등록: 권한 부여 서버가 동적 클라이언트 등록(DCR)을 지원하는 경우 레지스트리 구성에서 대상을 허용 목록에 추가할 수 있습니다.
### OAuth 기반 MCP 클라이언트 설정
#### 보유자 토큰 사용
대부분의 IDEs에서는 mcp 구성에서 권한 부여 헤더 보유자 토큰을 구성할 수 있습니다. 예를 들어 [Kiro는 구문을 사용하여 환경 변수를 지원합니다](https://kiro.dev/blog/introducing-remote-mcp/#securing-mcp-connections). `${ENV_VAR}` 다음 예제를 사용할 수 있습니다.
```
{
"mcpServers": {
"my-registry": {
"type": "http",
"url": "https://bedrock-agentcore..amazonaws.com/registry//mcp",
"headers": {
"Authorization": "Bearer ${ACCESS_TOKEN}"
}
}
}
}
```
#### 사전 등록된 클라이언트
권한 부여 서버의 권한 부여 코드 부여를 기반으로 새 클라이언트를 생성하고 클라이언트를 사용하여 레지스트리에 액세스할 수 있습니다. 예를 들어 [Cognito 사용자 풀에서 클라이언트를 생성합니다](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-idp-cognito.html).
클라이언트 ID가 있으면 레지스트리에 허용 목록에 등록해야 합니다.
```
aws bedrock-agentcore-control update-registry \
--registry-id \
--authorizer-configuration '{
"optionalValue": {
"customJWTAuthorizer": {
"discoveryUrl": "https:///.well-known/openid-configuration",
"allowedClients": [""]
}
}
}'
```
그런 다음 clientId 지정을 지원하는 경우 MCP 클라이언트를 구성할 수 있습니다. Claude 코드의 예:
```
{
"mcpServers": {
"pre-registered-registry": {
"type": "http",
"url": "https://bedrock-agentcore..amazonaws.com/registry//mcp",
"oauth": {
"clientId": "",
"callbackPort": ""
}
}
}
}
```
**참고**
Auth0 및 Cognito와 같은 일부 권한 부여 서버는 포트 범위를 허용된 리디렉션 URIs로 구성하도록 허용하지 않으므로 사전 등록된 클라이언트의 허용된 리디렉션/콜백 URL과 mcp.json에서 명시적으로 설정해야 합니다.
#### 동적 클라이언트 등록
대부분의 MCP 클라이언트 애플리케이션은 동적 클라이언트 등록을 지원합니다. 이 경우 레지스트리에 `allowedClients` 값을 지정해서는 안 됩니다. 대신 `allowedAudience`를 설정하도록 선택할 수 있습니다. 값은 MCP 레지스트리와 동일할 수 있습니다. 에서와 동일한 값을 가진 `aud` 필드가 있는 JWT를 발급하도록 권한 부여 서버를 구성해야 합니다`allowedAudience`.
```
aws bedrock-agentcore-control update-registry \
--registry-id \
--authorizer-configuration '{
"optionalValue": {
"customJWTAuthorizer": {
"discoveryUrl": "https:///.well-known/openid-configuration",
"allowedAudience": ["https://bedrock-agentcore..amazonaws.com/registry//mcp"]
}
}
}'
```
그런 다음 url을 사용하여 MCP 클라이언트를 구성할 수 있습니다.
```
{
"mcpServers": {
"dcr-registry": {
"type": "http",
"url": "https://bedrock-agentcore..amazonaws.com/registry//mcp"
}
}
}
```
동적 클라이언트 등록을 설정할 때 발생하는 일반적인 오류:
+ 권한 부여 서버가 동적 클라이언트 등록을 지원하는지 확인해야 합니다.
+ 권한 부여 서버는 레지스트리의 CustomJWTAuthorizerConfiguration에서 허용되는 `aud` 필드를 사용하여 JWT를 발급해야 합니다. CustomJWTAuthorizerConfiguration
+ 현재 레지스트리는 www-authenticate 헤더에 범위 챌린지를 반환하지 않습니다. 일부 MCP 클라이언트는 [Kiro](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#oauth-configuration)와 같은 구성`oauthScopes`에서 명시적으로 정의를 지원합니다.
## 기존 MCP 클라이언트에서 IAM 기반 레지스트리 MCP 엔드포인트에 연결
### 권한
MCP 초기화 및 도구 목록의 경우:
```
{
"Effect": "Allow",
"Action": "bedrock-agentcore:InvokeRegistryMcp",
"Resource": "arn:aws:bedrock-agentcore:*::registry/*"
}
```
MCP 도구 호출을 통해 검색하려면 다음 사항도 필요합니다.
```
{
"Effect": "Allow",
"Action":
[
"bedrock-agentcore:InvokeRegistryMcp",
"bedrock-agentcore:SearchRegistryRecords"
],
"Resource": "arn:aws:bedrock-agentcore:*::registry/*"
}
```
명령을 사용하여 권한을 확인할 수 있습니다.
```
curl -s -X POST "https://bedrock-agentcore..amazonaws.com/registry//mcp" \
-H "Content-Type: application/json" \
-H "X-Amz-Security-Token: ${AWS_SESSION_TOKEN}" \
--aws-sigv4 "aws:amz::bedrock-agentcore" \
--user "${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_registry_records","arguments":{"searchQuery":"weather"}}}'
```
### IAM 기반 MCP 클라이언트 설정
[mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws)를 사용하여 IAM 기반 레지스트리에 연결할 수 있습니다. 예를 들어 Kiro mcp.json에서는 다음과 같습니다.
```
{
"mcpServers": {
"iam-based-registry": {
"disabled": false,
"type": "stdio",
"command": "uvx",
"args": [
"mcp-proxy-for-aws@latest",
"https://bedrock-agentcore..amazonaws.com/registry//mcp",
"--service",
"bedrock-agentcore",
"--region",
"",
"--profile",
"my-profile"
]
}
}
}
```
## 자체 MCP 클라이언트 개발
Kiro 또는 Claude Code와 같은 인기 있는 IDEs를 포함하여 레지스트리 MCP 엔드포인트를 호출하는 방법에 대한 자세한 코드 참조는 퍼블릭 코드 리포지토리의 샘플 코드 참조를 참조하세요.