# Searching the registry Consumers search the registry to discover MCP servers, agents, skills, and other resources that have been approved and published. AWS Agent Registry combines semantic search with keyword matching to deliver relevant results for any type of query. This section covers how to search for registry records and how to use the Registry MCP endpoint. **Topics** + [ # Search for registry records ](registry-search-records.md) + [ # Using the Registry MCP endpoint ](registry-mcp-endpoint.md) # Search for registry records ## Request Parameters + **searchQuery** (required): Can be any natural language query from 1–256 characters + **registryIds** (required): Which Registry to conduct the Search in. Supports exactly one registry ARN or ID + **maxResults** (optional): How many records are returned in the Search response. Can take any value between 1–20 and defaults to 10 + **filters** (optional) — Metadata filter expression ## Metadata filters Operators: `$eq` , `$ne` , `$in` . Logical: `$and` , `$or` . Fields: name, descriptorType, version. Example: `{"descriptorType": {"$eq": "MCP"}}` Combined: `{"$and": [{"descriptorType": {"$eq": "MCP"}}, {"version": {"$eq": "1.0"}}]}` ## Console 1. Open the registry detail page. 1. Choose the **Search records** tab. 1. Enter your search query and view results. **Note** Console search is available for IAM-authorized registries only. For JWT-authorized registries, use the search API directly with an HTTP client (such as `curl` ) and a valid JWT bearer token, or use the MCP endpoint for the registry via an MCP client. ## AWS CLI (Registry with IAM based Inbound Authorization) ``` aws bedrock-agentcore search-registry-records \ --search-query "weather" \ --registry-ids "" \ --region us-east-1 ``` ## AWS SDK (Registry with IAM based Inbound Authorization) ``` import boto3 client = boto3.client('bedrock-agentcore') response = client.search_registry_records( registryIds=[''], searchQuery='weather', maxResults=10 ) for record in response['registryRecords']: print(f"{record['name']} - {record['descriptorType']} - {record['status']}") ``` ## HTTP client (Registry with OAuth based Inbound Authorization) First obtain a bearer token: ``` SECRET_HASH=$(echo -n "" | openssl dgst -sha256 -hmac "" -binary | base64) aws cognito-idp initiate-auth \ --client-id "" \ --auth-flow USER_PASSWORD_AUTH \ --auth-parameters USERNAME="",PASSWORD='',SECRET_HASH="$SECRET_HASH" \ --region us-east-1 | jq -r '.AuthenticationResult.AccessToken' ``` Then search with the bearer token: ``` curl -X POST "https://bedrock-agentcore..amazonaws.com/registry-records/search" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"registryIds": [""], "searchQuery": "weather", "maxResults": 10}' ``` ## Eventual consistency in AWS Agent Registry search AWS Agent Registry uses an eventually consistent model for search indexing. When you approve a registry record by calling `UpdateRegistryRecordStatus` or through the console, the record does not appear in `SearchRegistryRecords` or `InvokeRegistryMcp` results immediately. It typically takes a few seconds for the approved record to be indexed and become discoverable, but in some cases it can take up to a few minutes. During this time, you might observe the following behavior: + A `SearchRegistryRecords` query does not return a record that was just approved. + The registry MCP endpoint ( `InvokeRegistryMcp` ) does not include a recently approved record in tool results. Only records in **Approved** status are included in search results. Records in Draft, Pending Approval, Rejected, or Deprecated status are never returned by `SearchRegistryRecords` or `InvokeRegistryMcp` . You can verify a record’s current status by calling `GetRegistryRecord` , which always returns the latest revision regardless of indexing state. To handle eventual consistency in your application, we recommend the following: + After approving a record, confirm it is discoverable by calling `SearchRegistryRecords` with a retry strategy that includes exponential backoff. + Do not assume a record is missing from the registry if it does not appear in search results immediately after approval. Call `GetRegistryRecord` to verify the record’s status. + If you are integrating approval workflows through Amazon EventBridge and `UpdateRegistryRecordStatus` , add a brief delay before downstream systems query the search API for the newly approved record. For general guidance on configuring retry behavior in AWS SDKs, see [Retry behavior](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) in the * AWS SDKs and Tools Reference Guide*. ## How record attributes affect search relevance AWS Agent Registry uses hybrid search that combines semantic understanding with keyword matching to return relevant results. If a record you expect to find does not appear in search results, understanding which record attributes influence search can help. ### Which record attributes are used for search The following attributes from your registry record are used to determine search relevance: + **Name** — Used for keyword matching. Clear, descriptive names that reflect what the resource does improve discoverability for exact and partial name lookups. + **Description** — Used for both keyword and semantic matching. Descriptions written in natural language that explain the resource’s purpose and common use cases are more discoverable than terse technical labels. + **Descriptors** — The full content of your protocol definition (MCP server definition, agent card, skill documentation, or custom JSON) is used for semantic matching. This includes tool names, tool descriptions, input parameter names, and capability summaries. + **Version and descriptor type** — Available as filterable fields. Consumers can narrow results using metadata filters on `name` , `descriptorType` , and `version`. ### How search queries are processed When you call `SearchRegistryRecords` , AWS Agent Registry runs two searches in parallel against the same set of indexed records and merges the results: + **Semantic search** — Your query is converted into a vector representation and compared against the vector representations of indexed records. This finds conceptually related records even when the exact words in your query don’t appear in the record. For example, a query for "book a flight" can match a record named "travel-reservation-service." + **Keyword search** — Your query is matched against the text content of record fields using traditional keyword relevance. This is effective for exact name lookups and specific technical terms. For example, a query for "weather-api-v2" matches records containing that exact text. If you include metadata filters in your request, the filters are applied to both searches before results are scored and ranked. This means filters reduce the candidate set that both semantic and keyword search operate on, rather than filtering results after ranking. ### How results are ranked Results from both semantic and keyword search are combined into a single ranked list and returned in order of relevance, with the most relevant record first. Each result’s final position is determined by its relevance across both searches — a record that ranks highly in both semantic and keyword results will appear higher than a record that ranks highly in only one. Within keyword search, the record name has the strongest influence on ranking, followed by the description and descriptor content, which contribute equally. Because both search modes always run and contribute to the final ranking, how you write your query affects which records surface. The following guidance can help you get better results depending on your intent. ### Writing effective search queries **When you know the exact name or identifier** , use a short, specific query. Keyword search matches exact text against record names, descriptions, and descriptor content. Short queries like "weather-api-v2" or "pdf-processing" are effective for finding records by name. **When you’re exploring by capability or use case** , use a natural language description of what you need. Semantic search understands conceptual intent, so queries like "find a tool that can book flights" or "extract structured data from PDF documents" can match relevant records even if those exact words don’t appear in the record metadata. **Avoid mixing filter-like constraints with descriptive intent in the same query.** A query like "find all MCP servers for weather forecasts" sends the entire sentence through both semantic and keyword search. The semantic component interprets the full sentence as a conceptual intent, which can surface records that are conceptually related but don’t match the specific attribute you intended to constrain. Instead, use metadata filters for attribute-based constraints and keep the query focused on the topic. See [When to use metadata filters versus query text](#registry-search-filters-vs-query). ### Writing discoverable records + Write descriptions that explain what the resource does and the problems it solves. Semantic search understands intent, so "helps customers track package deliveries" is more discoverable than "delivery-status-endpoint." + Provide complete tool definitions for MCP servers. Tool descriptions and input parameter descriptions all contribute to search relevance. + Include relevant keywords in your name and description. Keyword search matches exact text, so if consumers are likely to search for specific terms, make sure those terms appear in your record. ### When to use metadata filters versus query text Use metadata filters when your intent is to constrain results by a known attribute such as record type, name, or version. Do not embed filter-like constraints in the query text itself. For example, if you want to find all MCP servers related to weather, use a metadata filter for the record type and a query for the topic: ``` { "searchQuery": "weather forecast", "filters": { "descriptorType": { "$eq": "MCP" } } } ``` Avoid putting the constraint into the query text like "find all MCP servers for weather forecasts". Because longer queries lean toward semantic matching, the words "MCP servers" are interpreted as part of the conceptual intent rather than as an exact filter. This can cause the semantic component to return records that are conceptually related to the full sentence but don’t match the specific attribute you intended to filter on — for example, returning agent records about weather alongside MCP server records. The same applies to any attribute-based constraint. If you want records with a specific name, version, or type, use the corresponding metadata filter rather than including those terms in the query. You can filter on the following fields: + `name` — Match records by exact name. + `descriptorType` — Match records by resource type (for example, `MCP` , `A2A` , `SKILL` , `CUSTOM` ). + `version` — Match records by version string. Filters support `$eq` (equals), `$ne` (not equals), and `$in` (matches any value in a list) operators, and can be combined using `$and` and `$or` logic. For example, to search for weather-related MCP servers only: ``` { "searchQuery": "weather forecast", "filters": { "descriptorType": { "$eq": "MCP" } } } ``` To exclude a specific resource type: ``` { "searchQuery": "", "filters": { "descriptorType": { "$ne": "CUSTOM" } } } ``` To match any of several versions: ``` { "filters": { "version": { "$in": ["1.0", "1.1", "2.0"] } } } ``` ### Search returns only approved records Only records in **Approved** status appear in search results and through the MCP endpoint. Records in Draft, Pending Approval, Rejected, or Deprecated status are not returned. If a recently approved record does not appear in results, see [Eventual consistency in AWS Agent Registry search](#registry-search-eventual-consistency). # Using the Registry MCP endpoint ## Overview Each registry exposes an MCP-compatible endpoint following [2025-11-25 specification](https://modelcontextprotocol.io/specification/2025-11-25) . The endpoint supports tool listing and tool invocation for searching registry records. ``` https://bedrock-agentcore..amazonaws.com/registry//mcp ``` The MCP contains one tool named "search\$1registry\$1records". ``` 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"}} ``` You can connect to registry from an existing MCP client, such as Kiro, Claude, etc. ## Connect to OAuth-based registry MCP endpoint from an existing MCP client ### Permissions The MCP endpoint will use the same **CustomJWTAuthorizerConfiguration** to authorize the incoming requests. The `.well-known/oauth-protected-resource` path is: `https://bedrock-agentcore..amazonaws.com/.well-known/oauth-protected-resource/registry//mcp`. The client can discover the metadata from `WWW-Authenticate` header as well: ``` www-authenticate: Bearer resource_metadata="https://bedrock-agentcore..amazonaws.com/.well-known/oauth-protected-resource/registry//mcp" ``` Once you obtained the access token, you can validate it: ``` curl -s -X POST "https://bedrock-agentcore..amazonaws.com/registry//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"}}}' ``` Depending on your authorization server and organization’s security requirements, you may choose one of the following approaches to configure your MCP client: 1. Bearer token: use a separate process to fetch bearer token and configure it in MCP client header 1. Pre-registered client: create a client in your authorization server, and allowlist the client on registry’s configuration. 1. Dynamic client registration: if your authorization server supports dynamic client registration (DCR), you can allowlist the audience in registry’s configuration. ### OAuth-based MCP client setup #### Use bearer token In most IDEs, you can configure authorization header bearer token in an mcp configuration. For example, [Kiro supports](https://kiro.dev/blog/introducing-remote-mcp/#securing-mcp-connections) environment variables using the `${ENV_VAR}` syntax. You can use following example: ``` { "mcpServers": { "my-registry": { "type": "http", "url": "https://bedrock-agentcore..amazonaws.com/registry//mcp", "headers": { "Authorization": "Bearer ${ACCESS_TOKEN}" } } } } ``` #### Pre-registered client You can create a new client based on authorization code grant in your authorization server, and use the client to access registry. For example, [create a client in Cognito](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-idp-cognito.html) user pool. Once you have the client ID, make sure you allowlist it in registry: ``` aws bedrock-agentcore-control update-registry \ --registry-id \ --authorizer-configuration '{ "optionalValue": { "customJWTAuthorizer": { "discoveryUrl": "https:///.well-known/openid-configuration", "allowedClients": [""] } } }' ``` Then you can configure your MCP client if it supports specifying clientId. An example in Claude code: ``` { "mcpServers": { "pre-registered-registry": { "type": "http", "url": "https://bedrock-agentcore..amazonaws.com/registry//mcp", "oauth": { "clientId": "", "callbackPort": "" } } } } ``` **Note** Some authorization servers like Auth0 and Cognito don’t let you configure a range of ports as allowed redirect URIs, so you need to explicitly set one in the preregistered client’s allowed redirect/callback URL, as well as in the mcp.json. #### Dynamic client registration Most MCP client applications support dynamic client registration. In this case, you should NOT specify `allowedClients` value in registry. Instead, you can choose to set `allowedAudience` . The value can be the same as your MCP registry. You should configure your authorization server to issue JWT with `aud` field with the same value as in `allowedAudience`. ``` aws bedrock-agentcore-control update-registry \ --registry-id \ --authorizer-configuration '{ "optionalValue": { "customJWTAuthorizer": { "discoveryUrl": "https:///.well-known/openid-configuration", "allowedAudience": ["https://bedrock-agentcore..amazonaws.com/registry//mcp"] } } }' ``` Then you can configure your MCP client simply using an url: ``` { "mcpServers": { "dcr-registry": { "type": "http", "url": "https://bedrock-agentcore..amazonaws.com/registry//mcp" } } } ``` Common errors when you setup dynamic client registration: + You must ensure the authorization server supports dynamic client registration. + The authorization server must issue JWT with `aud` field, which is allowed in your registry’s CustomJWTAuthorizerConfiguration. + Currently registry does not return scope challenge in www-authenticate header. Some MCP clients support explicitly defining `oauthScopes` in configuration, such as [Kiro](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#oauth-configuration). ## Connect to IAM-based registry MCP endpoint from an existing MCP client ### Permissions For MCP initialization and tool listing: ``` { "Effect": "Allow", "Action": "bedrock-agentcore:InvokeRegistryMcp", "Resource": "arn:aws:bedrock-agentcore:*::registry/*" } ``` For searching via MCP tool invocation, you also need: ``` { "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeRegistryMcp", "bedrock-agentcore:SearchRegistryRecords" ], "Resource": "arn:aws:bedrock-agentcore:*::registry/*" } ``` You can verify permission with command: ``` curl -s -X POST "https://bedrock-agentcore..amazonaws.com/registry//mcp" \ -H "Content-Type: application/json" \ -H "X-Amz-Security-Token: ${AWS_SESSION_TOKEN}" \ --aws-sigv4 "aws:amz::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 client setup You can use [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) to connect to an IAM-based registry. For example, in Kiro mcp.json: ``` { "mcpServers": { "iam-based-registry": { "disabled": false, "type": "stdio", "command": "uvx", "args": [ "mcp-proxy-for-aws@latest", "https://bedrock-agentcore..amazonaws.com/registry//mcp", "--service", "bedrock-agentcore", "--region", "", "--profile", "my-profile" ] } } } ``` ## Develop your own MCP client For more code references of how to invoke the Registry MCP endpoint, including from popular IDEs like Kiro or Claude Code, please refer to sample code references in the public code repository.