View a markdown version of this page

使用注册表 MCP 端点 - 亚马逊基岩 AgentCore
概述从现有 MCP 客户端连接到 OAuth-based 注册表 MCP 端点从现有 MCP 客户端连接到 IAM-based 注册表 MCP 端点开发你自己的 MCP 客户端

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用注册表 MCP 端点

迁移现已开放

AWS 代理注册表已在新agent-registry命名空间下启动。对公共预览bedrock-agentcore命名空间的支持将于 2026 年 9 月 17 日停止。有关迁移说明，请参阅综合注册表迁移指南。

概述

每个注册管理机构都公开一个遵循模型上下文协议网站上2025-11-25规范的 MCP-compatible 端点。该端点支持工具列表和工具调用来搜索注册表记录。

例
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 端点将所有三个发现数据平面 API 作为 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-based 注册表 MCP 端点

Permissions

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. Pre-registered 客户端：在授权服务器中创建客户端，并根据注册表的配置将该客户端列入白名单。

  3. 动态客户端注册：如果您的授权服务器支持动态客户端注册 (DCR)，则可以在注册表的配置中将受众列入许可名单。

OAuth-based MCP 客户端设置

使用不记名代币

在大多数 IDE 中，您可以在 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}"
      }
    }
  }
}

Pre-registered 客户端

您可以根据授权服务器中授予的授权码创建新的客户端，并使用该客户端访问注册表。例如，在 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，则可以对其进行配置。克劳德代码中的一个例子：

例
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，不允许您将一系列端口配置为允许的重定向URI，因此您需要在预注册的客户端的允许 redirect/callback 网址以及mcp.json中明确设置一个端口。

动态客户注册

大多数 MCP 客户端应用程序都支持动态客户端注册。在这种情况下，你不应该在注册表中指定allowedClients值。相反，你可以选择设置allowedAudience。该值可以与您的 MCP 注册表相同。您应该将授权服务器配置为向 JWT 发aud放与中的allowedAudience值相同的字段。

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

然后，你可以简单地使用网址来配置你的 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"
    }
  }
}

设置动态客户端注册时的常见错误：

  • 必须确保授权服务器支持动态客户端注册。

  • 授权服务器必须向 JWT 发放一个aud字段，该字段在您的注册表中是允许的 CustomJWTAuthorizerConfiguration。

  • 目前，注册表不在 www-authenticate 标头中返回范围质询。某些 MCP 客户端支持oauthScopes在配置中明确定义，例如 Kir o。

从现有 MCP 客户端连接到 IAM-based 注册表 MCP 端点

Permissions

对于 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-based MCP 客户端设置

你可以在 GitHub 网站上使用 mcp-proxy-for-aws 来连接到注册表。 IAM-based 例如，在 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 等常用 IDE 的代码参考，请参阅公共代码存储库中的示例代码参考。