Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Utilizzo dell'endpoint MCP del Registro
La migrazione è ora aperta
AWS Agent Registry è stato lanciato con il nuovo agent-registry namespace. Il supporto per il bedrock-agentcore namespace di anteprima pubblico verrà interrotto il 17 settembre 2026. Per le istruzioni sulla migrazione, consulta la Guida completa alla migrazione del registro.
Panoramica di
Ogni registro espone un MCP-compatible endpoint in base alla specifica 2025-11-25 sul sito Web Model Context Protocol. L'endpoint supporta l'elenco degli strumenti e l'invocazione degli strumenti per la ricerca nei record del registro.
Esempio
- 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
Nel agent-registry namespace, l'endpoint MCP espone tutte e tre le API di discovery data-plane come strumenti MCP:
-
search_discoverable_registry_records— Ricerca in linguaggio naturale per i record approvati.
-
list_discoverable_registry_records— Elenco impaginato dei record approvati.
-
batch_get_discoverable_registry_record— Recupero in blocco del contenuto completo del record in base all'ID del record.
Nel bedrock-agentcore namespace, viene esposto solo lo search_registry_records strumento. Le tabelle seguenti mostrano le definizioni degli strumenti:
Esempio
- 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"}}
È possibile connettersi al registro da un client MCP esistente, come Kiro, Claude, ecc.
Connettiti all'endpoint MCP OAuth-based del registro da un client MCP esistente
Permissions
L'endpoint MCP utilizzerà lo stesso per autorizzare le richieste CustomJWTAuthorizerConfiguration in arrivo.
Il .well-known/oauth-protected-resource percorso è: 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>/mcpper i registri ancora nel namespace). bedrock-agentcore
Il cliente può scoprire anche i metadati dall'intestazione: WWW-Authenticate
Esempio
- 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"
Una volta ottenuto il token di accesso, puoi convalidarlo:
Esempio
- 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"}}}'
A seconda del server di autorizzazione e dei requisiti di sicurezza dell'organizzazione, è possibile scegliere uno dei seguenti approcci per configurare il client MCP:
-
Token al portatore: utilizzate un processo separato per recuperare il token al portatore e configurarlo nell'intestazione del client MCP
-
Pre-registered client: crea un client nel tuo server di autorizzazione e inserisci il client nella configurazione del registro.
-
Registrazione dinamica del client: se il server di autorizzazione supporta la registrazione dinamica del client (DCR), puoi inserire il pubblico nella lista consentita nella configurazione del registro.
OAuth-based Configurazione del client MCP
Usa il token al portatore
Nella maggior parte degli IDE, puoi configurare l'header bearer token di autorizzazione in una configurazione mcp. Ad esempio, Kiro IDE supporta le variabili di ambiente utilizzando la sintassi. ${ENV_VAR} Per i dettagli, consulta Proteggere le connessioni MCP sul sito web di Kiro. Puoi usare il seguente esempio:
Esempio
- 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}"
}
}
}
}
Pre-registered cliente
È possibile creare un nuovo client in base alla concessione del codice di autorizzazione nel server di autorizzazione e utilizzare il client per accedere al registro. Ad esempio, crea un client nel pool di utenti di Cognito.
Una volta ottenuto l'ID cliente, assicurati di inserirlo nel registro:
Esempio
- 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>"]
}
}
}'
Quindi puoi configurare il tuo client MCP se supporta la specifica del clientID. Un esempio in codice Claude:
Esempio
- 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>"
}
}
}
}
Alcuni server di autorizzazione come Auth0 e Cognito non consentono di configurare un intervallo di porte come URI di reindirizzamento consentiti, quindi è necessario impostarne uno esplicitamente nell' redirect/callback URL consentito del client preregistrato e in mcp.json.
Registrazione dinamica del cliente
La maggior parte delle applicazioni client MCP supporta la registrazione dinamica dei client. In questo caso, NON è necessario specificare un allowedClients valore nel registro. Invece, puoi scegliere di impostareallowedAudience. Il valore può essere lo stesso del registro MCP. È necessario configurare il server di autorizzazione in modo che emetta a JWT un aud campo con lo stesso valore di in. allowedAudience
Esempio
- 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"]
}
}
}'
Quindi puoi configurare il tuo client MCP semplicemente usando un url:
Esempio
- 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"
}
}
}
Errori comuni durante la configurazione della registrazione dinamica del client:
-
È necessario assicurarsi che il server di autorizzazione supporti la registrazione dinamica dei client.
-
Il server di autorizzazione deve emettere il aud campo JWT, consentito nel registro. CustomJWTAuthorizerConfiguration
-
Attualmente il registro non restituisce l'ambito challenge nell'intestazione www-authenticate. Alcuni client MCP supportano la definizione oauthScopes esplicita della configurazione, come Kiro. https://kiro.dev/docs/cli/custom-agents/configuration-reference/#oauth-configuration
Connettiti all'endpoint MCP IAM-based del registro da un client MCP esistente
Permissions
Per l'inizializzazione MCP e l'elenco degli strumenti:
Esempio
- 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/*"
}
Per la ricerca tramite l'invocazione dello strumento MCP, è inoltre necessario:
Esempio
- 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/*"
}
Puoi verificare l'autorizzazione con il comando:
Esempio
- 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-based Configurazione del client MCP
È possibile utilizzare mcp-proxy-for-aws sul sito Web per connettersi a un registro. GitHub IAM-based Ad esempio, in Kiro mcp.json:
Esempio
- 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"
]
}
}
}
Sviluppa il tuo client MCP
Per ulteriori riferimenti al codice su come richiamare l'endpoint MCP del Registry, anche da IDE popolari come Kiro o Claude Code, fai riferimento agli esempi di riferimento al codice nell'archivio di codice pubblico.
