Usando o endpoint MCP do Registry

Visão geral do

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

https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp

O MCP contém uma ferramenta chamada “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"}}

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 CustomJWTAuthorizerConfigurationpara autorizar as solicitações recebidas.

O .well-known/oauth-protected-resource caminho é:https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp.

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

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:

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:

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 suporta variáveis de ambiente usando a ${ENV_VAR} sintaxe. Você pode usar o seguinte exemplo:

{
  "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 colocá-lo na lista de permissões no registro:

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:

{
  "mcpServers": {
    "pre-registered-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
      "oauth": {
        "clientId": "<client-id>",
        "callbackPort": "<port-number>"
      }
    }
  }
}

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 escolher definirallowedAudience. O valor pode ser o mesmo do seu registro MCP. Você deve configurar seu servidor de autorização para emitir ao JWT um aud campo com o mesmo valor de emallowedAudience.

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:

{
  "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:

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:

{
    "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:

{
    "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:

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 para se conectar a um registro. IAM-based Por exemplo, em Kiro mcp.json:

{
  "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 público de código.