View a markdown version of this page

Utilizzo dell'endpoint MCP del Registry - Amazon Bedrock AgentCore
Panoramica diConnect all'endpoint MCP OAuth-based del registro da un client MCP esistenteConnect all'endpoint MCP IAM-based del registro da un client MCP esistenteSviluppa il tuo client MCP

Utilizzo dell'endpoint MCP del Registry

Prossima migrazione del namespace

AWS Agent Registry è attualmente disponibile in anteprima pubblica nel namespace bedrock-agentcore. A partire dal 6 agosto 2026, il servizio passerà allo spazio dei nomi agent-registry. Se utilizzi AWS Agent Registry, devi aggiornare gli endpoint, le policy IAM, i client SDK, gli script CLI e i dati del registro. Per ulteriori informazioni sulla migrazione dall'anteprima pubblica, consulta la Guida completa alla migrazione del registro.

Panoramica di

Ogni registro espone un MCP-compatible endpoint conforme alle specifiche 2025-11-25. L'endpoint supporta l'elenco degli strumenti e la chiamata degli strumenti per la ricerca nei record di registro.

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

L'MCP contiene uno strumento denominato «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"}}

È possibile connettersi al registro da un client MCP esistente, come Kiro, Claude, ecc.

Connect all'endpoint MCP OAuth-based del registro da un client MCP esistente

Permissions

L'endpoint MCP utilizzerà lo stesso per CustomJWTAuthorizerConfigurationautorizzare le richieste in arrivo.

Il .well-known/oauth-protected-resource percorso è:. https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp

Il client può scoprire i metadati anche dall'WWW-Authenticateintestazione:

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:

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:

  1. Token Bearer: utilizzate un processo separato per recuperare il token bearer e configurarlo nell'intestazione del client MCP

  2. Pre-registered client: crea un client nel tuo server di autorizzazione e consenti il client nella configurazione del registro.

  3. Registrazione dinamica dei client: se il server di autorizzazione supporta la registrazione dinamica dei client (DCR), è possibile inserire l'audience nella configurazione del registro.

OAuth-based Configurazione del client MCP

Usa il token bearer

Nella maggior parte degli IDE, è possibile configurare il token di intestazione dell'intestazione di autorizzazione in una configurazione mcp. Ad esempio, Kiro supporta le variabili di ambiente utilizzando la sintassi. ${ENV_VAR} Puoi usare il seguente esempio:

{
  "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 nell'elenco dei permessi nel 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>"]
      }
    }
  }'

Quindi puoi configurare il tuo client MCP se supporta la specifica ClientID. Un esempio nel codice di Claude:

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

Alcuni server di autorizzazione come Auth0 e Cognito non consentono di configurare un intervallo di porte come URI di reindirizzamento consentiti, quindi è necessario impostarne una in modo esplicito nell'URL redirect/callback consentito del client preregistrato, oltre che in mcp.json.

Registrazione dinamica del client

La maggior parte delle applicazioni client MCP supporta la registrazione dinamica dei client. In questo caso, NON è necessario specificare allowedClients il valore nel registro. Invece, puoi scegliere di impostareallowedAudience. Il valore può essere lo stesso del registro MCP. È necessario configurare il server di autorizzazione per emettere a JWT un aud campo con lo stesso valore di. allowedAudience

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:

{
  "mcpServers": {
    "dcr-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp"
    }
  }
}

Errori comuni durante l'impostazione della registrazione dinamica del client:

Connect all'endpoint MCP IAM-based del registro da un client MCP esistente

Permissions

Per l'inizializzazione MCP e l'elenco degli strumenti:

{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:InvokeRegistryMcp",
    "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*"
}

Per la ricerca tramite l'invocazione dello strumento MCP, è inoltre necessario:

{
    "Effect": "Allow",
    "Action":
    [
        "bedrock-agentcore:InvokeRegistryMcp",
        "bedrock-agentcore:SearchRegistryRecords"
    ],
    "Resource": "arn:aws:bedrock-agentcore:*:<account>:registry/*"
}

È possibile verificare l'autorizzazione con il 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 Configurazione del client MCP

È possibile utilizzare mcp-proxy-for-aws per connettersi a un registro. IAM-based Ad esempio, in 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"
      ]
    }
  }
}

Sviluppa il tuo client MCP

Per ulteriori riferimenti di codice su come richiamare l'endpoint MCP del Registry, anche da IDE più diffusi come Kiro o Claude Code, fai riferimento ai riferimenti di codice di esempio nel repository di codice pubblico.