View a markdown version of this page

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

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用登錄檔 MCP 端點

遷移現已開啟

AWS 代理程式登錄檔已在新的agent-registry命名空間下啟動。公有預覽bedrock-agentcore命名空間的支援將於 2026 年 9 月 17 日停止。如需遷移說明，請參閱綜合登錄遷移指南。

概觀

每個登錄檔都會根據模型內容通訊協定網站上的 2025-11-25 規格公開 MCP 相容端點。端點支援工具清單和工具叫用，以搜尋登錄檔記錄。

範例
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

在agent-registry命名空間中，MCP 端點會將所有三個探索資料平面 APIs 公開為 MCP 工具：

  • search_discoverable_registry_records — 自然語言搜尋已核准的記錄。

  • list_discoverable_registry_records — 已核准記錄的分頁清單。

  • batch_get_discoverable_registry_record — 依記錄 ID 大量擷取完整記錄內容。

在bedrock-agentcore命名空間中，只會公開search_registry_records工具。下表顯示工具定義：

範例
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"}}

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

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

許可

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

.well-known/oauth-protected-resource 路徑為： 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>/mcp適用於仍在 bedrock-agentcore 命名空間上的登錄檔）。

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

範例
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"

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

範例
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"}}}'

根據您的授權伺服器和組織的安全需求，您可以選擇下列其中一種方法來設定 MCP 用戶端：

  1. 承載字符：使用單獨的程序來擷取承載字符，並在 MCP 用戶端標頭中進行設定

  2. 預先註冊的用戶端：在您的授權伺服器中建立用戶端，並在登錄檔的組態上允許列出用戶端。

  3. 動態用戶端註冊：如果您的授權伺服器支援動態用戶端註冊 (DCR)，您可以在登錄檔的組態中允許列出對象。

OAuth 型 MCP 用戶端設定

使用承載字符

在大多數 IDEs 中，您可以在 mcp 組態中設定授權標頭承載字符。例如，Kiro IDE 支援使用 ${ENV_VAR} 語法的環境變數。如需詳細資訊，請參閱 Kiro 網站上的保護 MCP 連線。您可以使用下列範例：

範例
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}"
      }
    }
  }
}

預先註冊的用戶端

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

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

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

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

範例
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>"
      }
    }
  }
}
注意

Auth0 和 Cognito 等某些授權伺服器不會讓您將連接埠範圍設定為允許的重新導向 URIs，因此您需要在預先註冊的用戶端允許的重新導向/回呼 URL 以及 mcp.json 中明確設定連接埠範圍。

動態用戶端註冊

大多數 MCP 用戶端應用程式都支援動態用戶端註冊。在此情況下，您不應該在登錄檔中指定allowedClients值。反之，您可以選擇設定 allowedAudience。此值可以與您的 MCP 登錄檔相同。您應該將授權伺服器設定為向具有與 中相同值aud的欄位發出 JWTallowedAudience。

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

然後，您只需使用 url 設定 MCP 用戶端：

範例
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"
    }
  }
}

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

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

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

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

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

許可

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

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

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

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

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

範例
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 型 MCP 用戶端設定

您可以在 GitHub 網站上使用 mcp-proxy-for-aws 連線到 IAM 型登錄檔。例如，在 Kiro mcp.json 中：

範例
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"
      ]
    }
  }
}

開發您自己的 MCP 用戶端

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