RFC: Add AWS Agent Registry discovery tools to amazon-bedrock-agentcore-mcp-server

[pymia]

Is this related to an existing feature request or issue?

No response

Summary

Add AWS Agent Registry discovery tools to the amazon-bedrock-agentcore-mcp-server package, enabling AI assistants to search, list, and inspect Registry records and registries programmatically through four new MCP tools.

Use case

AWS Agent Registry is a fully managed discovery service that provides a centralized catalog for organizing, curating, and discovering MCP servers, A2A agents, agent skills, and custom resources. Currently, the agentcore MCP server has no tools for interacting with the Registry. Users must use the AWS CLI or SDK directly to discover what's available. AI assistants using the MCP server cannot help users find relevant tools, agents, or resources registered in their account.

Proposal

Before:
The agentcore MCP server provides documentation, runtime, memory, gateway, browser, and code interpreter tools. There is no way for an AI assistant to discover or inspect Registry resources through the MCP server.

After:
Four new MCP tools are available:

1. search_registry — Semantic search across approved registry records using natural language. Accepts a query, registry ARN, and optional max results. For MCP descriptor records, parses inline JSON to extract endpoint, transport type, and tool names.
2. list_records — List all records in a specific registry with name, record ID, descriptor type, and status.
3. get_record — Get full details of a specific registry record. Strips ResponseMetadata, parses inline JSON content in MCP/A2A/custom descriptors with graceful fallback on malformed JSON.
4. list_registries — List all registries in the AWS account with name, registry ID, status, and auto-approval configuration.
   Users can enable/disable these tools via the existing AGENTCORE_ENABLE_TOOLS / AGENTCORE_DISABLE_TOOLS environment variables using the service name registry.

Out of scope

• Creating, updating, or deleting registry records (write operations)
• Creating or deleting registries
• Publishing records to registries
• Managing approval workflows
• Pagination support for large result sets (can be added later)
• Potential challenges

Potential challenges

Two boto3 clients required:

1. The Registry APIs are split across bedrock-agentcore-control (CRUD operations) and bedrock-agentcore-registry (semantic search). The data plane client requires a custom endpoint URL (https://bedrock-agentcore.{region}.amazonaws.com). This is handled via lazy initialization with separate _get_cp_client() and _get_dp_client() helpers.
2. Inline JSON parsing: Registry record descriptors contain JSON strings as inlineContent fields. Malformed JSON in these fields must not break the tool response — handled via a _parse_inline_json helper that returns None on failure.

Service availability:
The bedrock-agentcore-control and bedrock-agentcore-registry services may not be available in all AWS regions. The implementation defaults to us-west-2 and reads AWS_REGION from the environment.

Dependencies and Integrations

The implementation uses boto3 (already available via bedrock-agentcore dependency), json (stdlib), os (stdlib), loguru (already a dependency at >=0.7.0), and pydantic Field (already a dependency at >=2.10.6). All existing dependencies remain unchanged.

Alternative solutions

Using the standalone prototype in mcp-server/. This was the initial implementation but uses eager client initialization, the low-level `mcp.server.Server` API instead of FastMCP, and doesn't integrate with the existing service-enable guard system. Integrating into the existing package provides a consistent user experience and avoids running a separate server.

Exposing raw boto3 calls as a generic tool. This would be more flexible but less user-friendly for LLM consumers. Dedicated tools with structured JSON responses are easier for AI assistants to work with.