View a markdown version of this page

Usando o endpoint MCP do Registry - Base da Amazônia AgentCore
Visão geral doConecte-se ao endpoint MCP de OAuth-based registro a partir de um cliente MCP existenteConecte-se ao endpoint MCP de IAM-based registro a partir de um cliente MCP existenteDesenvolva seu próprio cliente MCP

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Usando o endpoint MCP do Registry

A migração já está aberta

AWS O Agent Registry foi lançado com o novo agent-registry namespace. O suporte para o bedrock-agentcore namespace de visualização pública será descontinuado em 17 de setembro de 2026. Para obter instruções de migração, consulte Guia abrangente de migração de registro.

Visão geral do

Cada registro expõe um MCP-compatible endpoint seguindo a especificação 2025-11-25 no site do Model Context Protocol. O endpoint oferece suporte à listagem de ferramentas e à invocação de ferramentas para pesquisar registros de registro.

exemplo
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

No agent-registry namespace, o endpoint MCP expõe todas as três APIs do plano de dados de descoberta como ferramentas MCP:

  • search_discoverable_registry_records— Pesquisa em linguagem natural para registros aprovados.

  • list_discoverable_registry_records— Lista paginada de registros aprovados.

  • batch_get_discoverable_registry_record— Recuperação em massa do conteúdo completo do registro por ID do registro.

No bedrock-agentcore namespace, somente a search_registry_records ferramenta é exposta. As tabelas a seguir mostram as definições da ferramenta:

exemplo
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"}}

Você pode se conectar ao registro a partir de um cliente MCP existente, como Kiro, Claude, etc.

Conecte-se ao endpoint MCP de OAuth-based registro a partir de um cliente MCP existente

Permissões

O endpoint MCP usará o mesmo CustomJWTAuthorizerConfiguration para autorizar as solicitações recebidas.

O .well-known/oauth-protected-resource caminho é: 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>/mcppara registros ainda no bedrock-agentcore namespace).

O cliente também pode descobrir os metadados do WWW-Authenticate cabeçalho:

exemplo
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"

Depois de obter o token de acesso, você pode validá-lo:

exemplo
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"}}}'

Dependendo do servidor de autorização e dos requisitos de segurança da organização, você pode escolher uma das seguintes abordagens para configurar seu cliente MCP:

  1. Token portador: use um processo separado para buscar o token portador e configurá-lo no cabeçalho do cliente MCP

  2. Pre-registered cliente: crie um cliente em seu servidor de autorização e coloque o cliente na lista de permissões na configuração do registro.

  3. Registro dinâmico de clientes: se seu servidor de autorização oferecer suporte ao registro dinâmico de clientes (DCR), você poderá listar o público na configuração do registro.

OAuth-based Configuração do cliente MCP

Use o token do portador

Na maioria dos IDEs, você pode configurar o token portador do cabeçalho de autorização em uma configuração mcp. Por exemplo, o Kiro IDE suporta variáveis de ambiente usando a ${ENV_VAR} sintaxe. Para obter detalhes, consulte Protegendo conexões MCP no site da Kiro. Você pode usar o seguinte exemplo:

exemplo
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

Você pode criar um novo cliente com base na concessão do código de autorização em seu servidor de autorização e usar o cliente para acessar o registro. Por exemplo, crie um cliente no grupo de usuários do Cognito.

Depois de ter o ID do cliente, certifique-se de incluí-lo na lista de permissões no registro:

exemplo
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>"]
      }
    }
  }'

Em seguida, você pode configurar seu cliente MCP se ele suportar a especificação de ClientID. Um exemplo no código Claude:

exemplo
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>"
      }
    }
  }
}
nota

Alguns servidores de autorização, como Auth0 e Cognito, não permitem que você configure um intervalo de portas como URIs de redirecionamento permitidos, então você precisa definir explicitamente um no redirect/callback URL permitido do cliente pré-registrado, bem como no mcp.json.

Registro dinâmico de clientes

A maioria dos aplicativos cliente MCP oferece suporte ao registro dinâmico de clientes. Nesse caso, você NÃO deve especificar o allowedClients valor no registro. Em vez disso, você pode optar por definirallowedAudience. O valor pode ser o mesmo do seu registro MCP. Você deve configurar seu servidor de autorização para emitir JWT com aud campo com o mesmo valor de emallowedAudience.

exemplo
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"]
      }
    }
  }'

Em seguida, você pode configurar seu cliente MCP simplesmente usando um URL:

exemplo
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"
    }
  }
}

Erros comuns ao configurar o registro dinâmico de clientes:

  • Você deve garantir que o servidor de autorização ofereça suporte ao registro dinâmico de clientes.

  • O servidor de autorização deve emitir JWT com o aud campo, o que é permitido no seu registro. CustomJWTAuthorizerConfiguration

  • Atualmente, o registro não retorna o desafio de escopo no cabeçalho www-authenticate. Alguns clientes MCP suportam a definição explícita oauthScopes na configuração, como o Kiro.

Conecte-se ao endpoint MCP de IAM-based registro a partir de um cliente MCP existente

Permissões

Para inicialização do MCP e listagem de ferramentas:

exemplo
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/*"
}

Para pesquisar por meio da invocação da ferramenta MCP, você também precisa:

exemplo
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/*"
}

Você pode verificar a permissão com o comando:

exemplo
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 Configuração do cliente MCP

Você pode usar mcp-proxy-for-aws no site para se conectar a GitHub um registro. IAM-based Por exemplo, no Kiro mcp.json:

exemplo
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"
      ]
    }
  }
}

Desenvolva seu próprio cliente MCP

Para obter mais referências de código sobre como invocar o endpoint MCP do Registry, inclusive de IDEs populares como Kiro ou Claude Code, consulte exemplos de referências de código no repositório de código público.