ADR: bringing governed agents into Amazon Quick

In financial environments, the first wave of agents is usually productive and risky at the same time. One team creates an MCP server for ticket lookup, another publishes a tool for contract search, a third connects an internal credit-risk API, and soon there is a collection of endpoints with unclear owners, scopes, credentials, and versions. MCP itself is not the issue. The issue is the lack of a reliable inventory once those servers become an operational surface.

What Amazon Quick changes is that this inventory becomes directly consumable by users in the same workspace where they chat, build apps, automate flows, and run research. AWS Agent Registry already provided the catalog, hybrid search, approval, and records for MCP servers, agents, skills, and custom resources. The Quick integration adds the last mile: a user can find an approved resource and create a connector with pre-filled details instead of relying on a wiki, an issue, or a Slack message containing the right URL.

The main architectural force is governance without excessive friction. If I let every area connect MCP servers directly in Quick, I gain local speed and lose traceability. If I centralize too aggressively, I create a queue and encourage bypasses. The governed registry is the middle ground: distributed publishing, centralized discovery, explicit approval, and consumption close to the work.

I would decide on one registry per relevant operating environment, starting with production rather than dozens of squad-level catalogs. AWS Agent Registry allows registries to be organized by type, stage, team, or business unit, but in a large organization, early fragmentation destroys discovery. For Quick, I would start with a regional registry aligned to the Quick account itself, because the integration documentation requires the same account and same Region, a READY registry, AWS_IAM authorization with SigV4, the agent-registry namespace, and only one active registry per Quick account.

This has an important consequence: if the company has multiple accounts producing agents, the decision is not merely technical. It is a multi-account governance decision. The Agent Registry general availability announcement mentions AWS RAM sharing and automatic detection of AgentCore Runtime and Gateway resources across an organization, but the Quick integration creates a practical consumption boundary in the Quick account and Region. I would design the topology with a platform account for curation and a Quick account per domain only when regulatory or data-segregation reasons justify it.

The registry must not be populated by enthusiasm. Each record needs a stable name, version, owner, data class, authentication policy, runbook, expected SLO, and domain tags. Without that, the catalog becomes a polished storefront for invisible coupling.

The most sensitive decision is not semantic search in the catalog; it is the authorization path between the user, Quick, the connector, and the MCP server. The Quick documentation indicates that Agent Registry does not store connector authentication credentials; each user authenticates or provides credentials according to the connector setup. That is the right model for environments where an account lookup, ticket update, or report generation must reflect the real user identity, not a generic automation identity.

I would avoid service connectors for mutable operations in financial domains unless there is an explicit business authorization layer behind them. For reads, I would still require minimal scopes and domain segmentation. For writes, I would make idempotency keys mandatory, validate payloads, enforce per-user rate limits, and require human confirmation for commands that move money, alter critical registration data, change risk parameters, or affect regulated servicing.

The MCP server design must be as rigorous as an internal public API. Tool names should be stable; schemas should reject extra fields; responses should carry a correlation id; timeouts should be lower than the maximum acceptable interaction time in Quick. As an operating reference, I would target p95 under 2 seconds for simple reads, 5 to 10 seconds for aggregations, and asynchronous execution with Step Functions or a queue for anything beyond that.

An agent catalog only works if the lifecycle is explicit. I would define states similar to draft, approved, deprecated, and revoked, even when part of that already exists as a native registry workflow. Draft is technical publication that is not yet consumable. Approved requires security review, a business owner, test evidence, and data classification. Deprecated preserves compatibility for a defined window. Revoked removes discovery immediately when there is an incident, loss of ownership, or scope change.

The registry version must mean contract, not decorative release notes. If an MCP server changes a tool schema, changes authorization semantics, or starts performing a write where it previously only read, that is a new version and a new approval. I would use names like domain/capability and semantic versions when the contract is consumed by multiple agents. Tags should carry domain, data-classification, environment, owner, cost-center, and criticality. In AWS accounts, that aligns with IAM conditions and governance reporting, even when the end user only sees a connector in Quick.

For observability, I would require three trails. CloudTrail for Registry control APIs. Structured MCP logs with tenant, pseudonymized user subject, tool, registry-record-version, latency, outcome, and correlation id. Tool-level metrics in CloudWatch or Datadog: invocation count, error rate, p95, timeout rate, auth failures, and deny decisions. Without these trails, the platform cannot distinguish healthy adoption from uncontrolled automation.

My reference implementation would start small: one production registry in the Region where Quick and AgentCore are available for the domain, linked by an administrator through Manage account, Permissions, AWS Agent Registry. The minimum policy for the Quick managed or customer role needs to allow reading and searching discoverable records, including agent-registry:SearchDiscoverableRegistryRecords and agent-registry:GetDiscoverableRegistryRecord; administrators also need to list and view registries for setup to appear.

MCP servers would sit behind AgentCore Gateway when there is a need to transform APIs, Lambda functions, or existing services into tools with more governed inbound and outbound authentication. For sensitive internal APIs, I would prefer VPC, PrivateLink, or private connectivity where the integration pattern supports it. The Quick MCP documentation also supports private servers reachable through a Quick VPC connection, but requires the OAuth endpoints used by the MCP server to be publicly reachable; that must enter the security review because many companies wrongly assume the entire authentication path can remain private.

In the backend, DynamoDB can store idempotency state with partition key userId#toolName and sort key idempotencyKey, a TTL of 24 to 72 hours, and an attribute_not_exists condition on first execution. Step Functions should orchestrate long operations with explicit retries, backoff, and compensation. S3 with SSE-KMS stores non-sensitive execution evidence. The key is not putting risk logic in the prompt: authorization, validation, and auditability live in code and policy.