View a markdown version of this page

레지스트리 MCP 엔드포인트 사용 - Amazon Bedrock AgentCore

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

레지스트리 MCP 엔드포인트 사용

지금 마이그레이션 열기

AWS 에이전트 레지스트리가 새 agent-registry 네임스페이스에서 시작되었습니다. 퍼블릭 미리 보기 bedrock-agentcore 네임스페이스에 대한 지원은 2026년 9월 17일에 중단됩니다. 마이그레이션 지침은 포괄적인 레지스트리 마이그레이션 가이드를 참조하세요.

개요

각 레지스트리는 모델 컨텍스트 프로토콜 웹 사이트의 2025-11-25 사양에 따라 MCP 호환 엔드포인트를 노출합니다. 엔드포인트는 레지스트리 레코드 검색을 위한 도구 목록 및 도구 호출을 지원합니다.

예
AWS Agent Registry namespace
https://agent-registry.<region>.api.aws/registry/<registryId>/mcp
Amazon Bedrock AgentCore namespace (to be deprecated)
https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp

agent-registry 네임스페이스에서 MCP 엔드포인트는 세 가지 검색 데이터 영역 APIs

  • search_discoverable_registry_records - 승인된 레코드를 자연어로 검색합니다.

  • list_discoverable_registry_records - 승인된 레코드의 페이지 매김 목록입니다.

  • batch_get_discoverable_registry_record - 레코드 ID별로 전체 레코드 콘텐츠를 대량 검색합니다.

bedrock-agentcore 네임스페이스에는 search_registry_records 도구만 표시됩니다. 다음 표에는 도구 정의가 나와 있습니다.

예
AWS Agent Registry namespace
Tool name: search_discoverable_registry_records Description: Searches for approved 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, recordType, recordVersion). Example: {"recordType": {"$eq": "MCP"}} --- Tool name: list_discoverable_registry_records Description: Returns paginated summaries of approved records in the registry. Summaries include record metadata but not descriptor content. Use batch_get_discoverable_registry_record to fetch full descriptors after identifying the records you need. Parameters: - maxResults: integer - Maximum number of results per page (1-100, default 20) - nextToken: string - Pagination token from a previous response. Omit for the first page. - filters: array - Optional list of filter entries in the form {"name": "<field>", "values": ["<value>"]}. Supported filter names: recordType (valid values: AGENT, MCP, SKILL, CUSTOM) and descriptorType (valid values: a2aAgentCard, mcpServer, agentSkillsDefinition, custom). Duplicate filter names are rejected. If you specify multiple values for a single filter, the values are joined by OR. If you specify multiple filters, the filters are joined by AND. --- Tool name: batch_get_discoverable_registry_record Description: Retrieves the full descriptor content for up to 100 approved records in a single call. Common use case: after identifying records with list_discoverable_registry_records or search_discoverable_registry_records, fetch their full descriptors in one call rather than making one call per record. Parameters: - recordIds (required): array - List of 1-100 record ARNs or IDs to retrieve from the registry. The response returns HTTP 200 even on partial failure. Records that could not be retrieved appear in an errors list with an errorCode (RESOURCE_NOT_FOUND, ACCESS_DENIED, or INTERNAL_ERROR) rather than causing the whole call to fail.
Amazon Bedrock AgentCore namespace (to be deprecated)
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://agent-registry.<region>.api.aws/.well-known/oauth-protected-resource/registry/<registryId>/mcp (https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp 네bedrock-agentcore임스페이스에 아직 있는 레지스트리의 경우 )입니다.

클라이언트는 WWW-Authenticate 헤더에서도 메타데이터를 검색할 수 있습니다.

예
AWS Agent Registry namespace
www-authenticate: Bearer resource_metadata="https://agent-registry.<region>.api.aws/.well-known/oauth-protected-resource/registry/<registryId>/mcp"
Amazon Bedrock AgentCore namespace (to be deprecated)
www-authenticate: Bearer resource_metadata="https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp"

액세스 토큰을 얻은 후에는 다음을 검증할 수 있습니다.

예
AWS Agent Registry namespace
curl -s -X POST "https://agent-registry.<region>.api.aws/registry/<registryId>/mcp" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_discoverable_registry_records","arguments":{"searchQuery":"weather"}}}'
Amazon Bedrock AgentCore namespace (to be deprecated)
curl -s -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/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 클라이언트 헤더에서 구성합니다.

  2. 사전 등록된 클라이언트: 권한 부여 서버에서 클라이언트를 생성하고 레지스트리 구성에서 클라이언트를 허용 목록에 추가합니다.

  3. 동적 클라이언트 등록: 권한 부여 서버가 동적 클라이언트 등록(DCR)을 지원하는 경우 레지스트리 구성에서 대상을 허용 목록에 추가할 수 있습니다.

OAuth 기반 MCP 클라이언트 설정

보유자 토큰 사용

대부분의 IDEs에서는 mcp 구성에서 권한 부여 헤더 보유자 토큰을 구성할 수 있습니다. 예를 들어 Kiro IDE는 ${ENV_VAR} 구문을 사용하여 환경 변수를 지원합니다. 자세한 내용은 Kiro 웹 사이트의 MCP 연결 보안을 참조하세요. 다음 예제를 사용할 수 있습니다.

예
AWS Agent Registry namespace
{ "mcpServers": { "my-registry": { "type": "http", "url": "https://agent-registry.<region>.api.aws/registry/<registryId>/mcp", "headers": { "Authorization": "Bearer ${ACCESS_TOKEN}" } } } }
Amazon Bedrock AgentCore namespace (to be deprecated)
{ "mcpServers": { "my-registry": { "type": "http", "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp", "headers": { "Authorization": "Bearer ${ACCESS_TOKEN}" } } } }

사전 등록된 클라이언트

권한 부여 서버의 권한 부여 코드 부여를 기반으로 새 클라이언트를 생성하고 클라이언트를 사용하여 레지스트리에 액세스할 수 있습니다. 예를 들어 Cognito 사용자 풀에서 클라이언트를 생성합니다.

클라이언트 ID가 있으면 레지스트리에 허용 목록에 등록해야 합니다.

예
AWS Agent Registry namespace
aws agent-registry-control update-registry \ --registry-id <registryId> \ --discovery-configuration '{ "authorizerConfiguration": { "optionalValue": { "customJWTAuthorizer": { "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration", "allowedClients": ["<client-id>"] } } } }'
Amazon Bedrock AgentCore namespace (to be deprecated)
aws bedrock-agentcore-control update-registry \ --registry-id <registryId> \ --authorizer-configuration '{ "optionalValue": { "customJWTAuthorizer": { "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration", "allowedClients": ["<client-id>"] } } }'

그런 다음 clientId 지정을 지원하는 경우 MCP 클라이언트를 구성할 수 있습니다. Claude 코드의 예:

예
AWS Agent Registry namespace
{ "mcpServers": { "pre-registered-registry": { "type": "http", "url": "https://agent-registry.<region>.api.aws/registry/<registryId>/mcp", "oauth": { "clientId": "<client-id>", "callbackPort": "<port-number>" } } } }
Amazon Bedrock AgentCore namespace (to be deprecated)
{ "mcpServers": { "pre-registered-registry": { "type": "http", "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp", "oauth": { "clientId": "<client-id>", "callbackPort": "<port-number>" } } } }
참고

Auth0 및 Cognito와 같은 일부 권한 부여 서버는 포트 범위를 허용된 리디렉션 URIs로 구성하도록 허용하지 않으므로 사전 등록된 클라이언트의 허용된 리디렉션/콜백 URL과 mcp.json에서 명시적으로 설정해야 합니다.

동적 클라이언트 등록

대부분의 MCP 클라이언트 애플리케이션은 동적 클라이언트 등록을 지원합니다. 이 경우 레지스트리에 allowedClients 값을 지정해서는 안 됩니다. 대신를 설정하도록 선택할 수 있습니다allowedAudience. 값은 MCP 레지스트리와 동일할 수 있습니다. 에서와 동일한 값을 가진 aud 필드가 있는 JWT를 발급하도록 권한 부여 서버를 구성해야 합니다allowedAudience.

예
AWS Agent Registry namespace
aws agent-registry-control update-registry \ --registry-id <registryId> \ --discovery-configuration '{ "authorizerConfiguration": { "optionalValue": { "customJWTAuthorizer": { "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration", "allowedAudience": ["https://agent-registry.<region>.api.aws/registry/<registryId>/mcp"] } } } }'
Amazon Bedrock AgentCore namespace (to be deprecated)
aws bedrock-agentcore-control update-registry \ --registry-id <registryId> \ --authorizer-configuration '{ "optionalValue": { "customJWTAuthorizer": { "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration", "allowedAudience": ["https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp"] } } }'

그런 다음 url을 사용하여 MCP 클라이언트를 구성할 수 있습니다.

예
AWS Agent Registry namespace
{ "mcpServers": { "dcr-registry": { "type": "http", "url": "https://agent-registry.<region>.api.aws/registry/<registryId>/mcp" } } }
Amazon Bedrock AgentCore namespace (to be deprecated)
{ "mcpServers": { "dcr-registry": { "type": "http", "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp" } } }

동적 클라이언트 등록을 설정할 때 발생하는 일반적인 오류:

  • 권한 부여 서버가 동적 클라이언트 등록을 지원하는지 확인해야 합니다.

  • 권한 부여 서버는 레지스트리의 CustomJWTAuthorizerConfiguration에서 허용되는 aud 필드를 사용하여 JWT를 발급해야 합니다. CustomJWTAuthorizerConfiguration

  • 현재 레지스트리는 www-authenticate 헤더에 범위 챌린지를 반환하지 않습니다. 일부 MCP 클라이언트는 Kiro와 같은 구성oauthScopes에서 명시적으로 정의를 지원합니다.

기존 MCP 클라이언트에서 IAM 기반 레지스트리 MCP 엔드포인트에 연결

권한

MCP 초기화 및 도구 목록의 경우:

예
AWS Agent Registry namespace
{ "Effect": "Allow", "Action": "agent-registry:InvokeRegistryMcp", "Resource": "arn:aws:agent-registry:*:<account>:registry/*" }
Amazon Bedrock AgentCore namespace (to be deprecated)
{ "Effect": "Allow", "Action": "bedrock-agentcore:InvokeRegistryMcp", "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*" }

MCP 도구 호출을 통해 검색하려면 다음 사항도 필요합니다.

예
AWS Agent Registry namespace
{ "Effect": "Allow", "Action": [ "agent-registry:InvokeRegistryMcp", "agent-registry:SearchDiscoverableRegistryRecords" ], "Resource": "arn:aws:agent-registry:*:<account>:registry/*" }
Amazon Bedrock AgentCore namespace (to be deprecated)
{ "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeRegistryMcp", "bedrock-agentcore:SearchRegistryRecords" ], "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*" }

명령을 사용하여 권한을 확인할 수 있습니다.

예
AWS Agent Registry namespace
curl -s -X POST "https://agent-registry.<region>.api.aws/registry/<registryId>/mcp" \ -H "Content-Type: application/json" \ -H "X-Amz-Security-Token: ${AWS_SESSION_TOKEN}" \ --aws-sigv4 "aws:amz:<region>:agent-registry" \ --user "${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_discoverable_registry_records","arguments":{"searchQuery":"weather"}}}'
Amazon Bedrock AgentCore namespace (to be deprecated)
curl -s -X POST "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp" \ -H "Content-Type: application/json" \ -H "X-Amz-Security-Token: ${AWS_SESSION_TOKEN}" \ --aws-sigv4 "aws:amz:<region>: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 클라이언트 설정

GitHub 웹 사이트에서 mcp-proxy-for-aws를 사용하여 IAM 기반 레지스트리에 연결할 수 있습니다. 예를 들어 Kiro mcp.json에서는 다음과 같습니다.

예
AWS Agent Registry namespace
{ "mcpServers": { "iam-based-registry": { "disabled": false, "type": "stdio", "command": "uvx", "args": [ "mcp-proxy-for-aws@latest", "https://agent-registry.<region>.api.aws/registry/<registryId>/mcp", "--service", "agent-registry", "--region", "<region>", "--profile", "my-profile" ] } } }
Amazon Bedrock AgentCore namespace (to be deprecated)
{ "mcpServers": { "iam-based-registry": { "disabled": false, "type": "stdio", "command": "uvx", "args": [ "mcp-proxy-for-aws@latest", "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp", "--service", "bedrock-agentcore", "--region", "<region>", "--profile", "my-profile" ] } } }

자체 MCP 클라이언트 개발

Kiro 또는 Claude Code와 같은 인기 있는 IDEs를 포함하여 레지스트리 MCP 엔드포인트를 호출하는 방법에 대한 자세한 코드 참조는 퍼블릭 코드 리포지토리의 샘플 코드 참조를 참조하세요.