View a markdown version of this page

使用登錄檔 MCP 端點 - Amazon Bedrock AgentCore
概觀從現有的 MCP 用戶端連線至以 OAuth 為基礎的登錄檔 MCP 端點從現有的 MCP 用戶端連線至 IAM 型登錄 MCP 端點開發您自己的 MCP 用戶端

使用登錄檔 MCP 端點

即將進行的命名空間遷移

AWS 客服人員登錄檔目前在 bedrock-agentcore 命名空間下為公開預覽。從 2026 年 8 月 6 日開始，服務會移至代理程式登錄命名空間。如果您使用 AWS 代理程式登錄檔，則必須更新端點、IAM 政策、SDK 用戶端、CLI 指令碼和登錄檔資料。如需從公有預覽遷移的詳細資訊，請參閱 綜合登錄遷移指南。

概觀

每個登錄檔都會根據 2025-11-25 規格公開與 MCP 相容的端點。端點支援工具清單和工具叫用，以搜尋登錄檔記錄。

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

MCP 包含一個名為 "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"}}

您可以從現有的 MCP 用戶端連線至登錄檔，例如 Kiro、Claude 等。

從現有的 MCP 用戶端連線至以 OAuth 為基礎的登錄檔 MCP 端點

許可

MCP 端點將使用相同的 CustomJWTAuthorizerConfiguration 來授權傳入的請求。

.well-known/oauth-protected-resource 路徑為：https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp。

用戶端也可以從 WWW-Authenticate 標頭探索中繼資料：

www-authenticate: Bearer resource_metadata="https://bedrock-agentcore.<region>.amazonaws.com/.well-known/oauth-protected-resource/registry/<registryId>/mcp"

取得存取權杖後，您可以驗證它：

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 支援使用 語法的環境變數。 ${ENV_VAR}您可以使用下列範例：

{
  "mcpServers": {
    "my-registry": {
      "type": "http",
      "url": "https://bedrock-agentcore.<region>.amazonaws.com/registry/<registryId>/mcp",
      "headers": {
        "Authorization": "Bearer ${ACCESS_TOKEN}"
      }
    }
  }
}

預先註冊的用戶端

您可以根據授權伺服器中的授權碼授予建立新的用戶端，並使用用戶端存取登錄檔。例如，在 Cognito 使用者集區中建立用戶端。

取得用戶端 ID 後，請務必在登錄檔中允許將其列出：

aws bedrock-agentcore-control update-registry \
  --registry-id <registryId> \
  --authorizer-configuration '{
    "optionalValue": {
      "customJWTAuthorizer": {
        "discoveryUrl": "https://<example-domain>/.well-known/openid-configuration",
        "allowedClients": ["<client-id>"]
      }
    }
  }'

然後，如果 MCP 用戶端支援指定 clientId。Claude 程式碼中的範例：

{
  "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的欄位發出 JWTallowedAudience。

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 用戶端：

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

設定動態用戶端註冊時的常見錯誤：

  • 您必須確保授權伺服器支援動態用戶端註冊。

  • 授權伺服器必須使用 aud 欄位發出 JWT，這是在登錄檔的 CustomJWTAuthorizerConfiguration 中允許的。

  • 目前登錄檔不會傳回 www-authenticate 標頭中的範圍挑戰。有些 MCP 用戶端支援在組態oauthScopes中明確定義，例如 Kiro。

從現有的 MCP 用戶端連線至 IAM 型登錄 MCP 端點

許可

對於 MCP 初始化和工具清單：

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

若要透過 MCP 工具叫用進行搜尋，您也需要：

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

您可以使用 命令來驗證許可：

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 用戶端設定

您可以使用 mcp-proxy-for-aws 連線到 IAM 型登錄檔。例如，在 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"
      ]
    }
  }
}

開發您自己的 MCP 用戶端

如需如何叫用登錄檔 MCP 端點的更多程式碼參考，包括來自 Kiro 或 Claude Code 等熱門 IDEs，請參閱公有程式碼儲存庫中的範例程式碼參考。