Quick Space Migrator — Amazon Bedrock AgentCore MCP Server

Quick Space Migrator — Amazon Bedrock AgentCore MCP Server

Migrate Amazon Quick Suite resources — Spaces, Chat Agents, ActionConnectors, and S3 Knowledge Bases — between AWS accounts through aModel Context Protocol (MCP) server hosted onAmazon Bedrock AgentCore Runtime. The server can be driven directly fromAmazon Quick (as an action connector) or from any MCP-compatible client.

The migrator recreates every link exactly as it exists in the source —agents are created with their Spaces and Action Connectors attached, andknowledge bases are wired back to their spaces. There is no manual re-linkingstep. Permissions are not hard-coded: the server describes each sourceresource's permissions and replays the identical actions in the target,remapping principals to a real registered user in the target account.

Problem statement

Promoting a Quick Space from one account to another (for example, dev → prod)by hand is slow and error-prone:

1. Each Space, Agent, Connector, and Knowledge Base must be recreatedindividually with the correct configuration.
2. Resource permissions must be re-granted, with principals remapped to thetarget account's registered users.
3. Every link (agent ↔ space, connector ↔ space, KB ↔ space) has to berebuilt so the migrated app behaves like the original.
4. S3-backed knowledge bases need their bucket, bucket policy, and data sourceprovisioned before the KB can be attached.

Doing this repeatedly across environments is exactly the kind of deterministic,idempotent work that should be automated.

What this solution provides

• A single migrate_spaces MCP tool that performs the full cross-accountmigration in one call, and a read-only preview_migration tool for a dryrun.
• Idempotency — every resource is created-or-updated, so re-running amigration converges instead of producing duplicates.
• Faithful linkage — agents, connectors, and knowledge bases are linked totheir spaces exactly as in the source.
• Permission fidelity — permissions are copied by describing the source andreplicating the exact actions, with principals resolved to a real user in thetarget account.
• Infrastructure as code — CloudFormation templates for the IAM roles, VPCnetwork, and the AgentCore runtime (Cognito JWT auth + VPC network mode).

Architecture

Migration flow (migrate_spaces)

1. Resolve spaces — expand "all" or the comma-separated space IDs.
2. Read source spaces — describe each space and its resources.
3. Discover agents — find agents linked to those spaces.
4. Create spaces in the target (update-on-exists).
5. Create connectors — authentication config is sanitized to the create(write) model with placeholder secrets; connectors are re-authenticated inthe target UI.
6. Migrate S3 knowledge bases — create the target bucket(knowledge-base-<env>-<account>) + bucket policy + data source + KB, thencopy KB permissions and attach to the target space.
7. Create agents linked to their spaces and connectors — exactly as in thesource.

Data note: the migrator provisions the target KB bucket and registers theknowledge base, but does not copy the S3 objects themselves. Sync thedocuments (e.g. aws s3 sync) and trigger a KB ingestion separately. Seedocs/knowledge-base-iam-setup.md.

Repository layout

quick-space-migrator-mcp/
├── src/
│   └── server.py                     # The MCP server (the only first-party runtime file)
├── infrastructure/                   # CloudFormation templates (deploy in this order)
│   ├── runner-role.yaml              #   1. Central account: AgentCore execution role
│   ├── quick-migrator-role.yaml      #   2. Source & target account cross-account role
│   ├── network.yaml                  #   3. VPC, subnets, NAT, endpoints, security groups
│   └── agentcore-runtime.yaml        #   4. Cognito + AgentCore runtime
├── scripts/                          # Deployment automation (wrappers over the templates)
│   ├── build.sh                      #   Package server.py + deps → build/deployment.zip (ARM64)
│   ├── deploy-roles.sh               #   Deploy runner → source → target roles (ordered)
│   ├── deploy-network.sh             #   Deploy the VPC network stack
│   └── deploy.sh                     #   Build, upload artifact, deploy the runtime
├── examples/                         # Optional helper scripts for testing
│   ├── setup_source.py               #   Seed a source account with sample spaces/agents/KB
│   └── manage_agent_space.py         #   Attach/detach a space from an agent
├── docs/
│   ├── knowledge-base-iam-setup.md   #   KB IAM policy + S3 bucket naming convention
│   └── quick-app-integration.md      #   Build a Quick App on top of the MCP connector
├── images/
│   └── architecture.svg
├── requirements.txt                  # Runtime dependencies (resolved at build time)
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── THIRD_PARTY_LICENSES
└── LICENSE

No dependencies are vendored into the repository — scripts/build.sh resolvesthem from PyPI at package time into a git-ignored build/ directory.

Prerequisites

Install the following locally:

• AWS CLI v2 — configured with credentials/profiles for each account
• Python 3.14 — the AgentCore runtime targets Python 3.14 on Linux ARM64
• Bash and zip
• Three AWS accounts (or three roles): central/runner, source, target(source and target may be the same account for a smoke test)

ARM64 note: AgentCore Runtime runs on AWS Graviton (Linux aarch64).scripts/build.sh uses pip --platform manylinux2014_aarch64 --only-binary=:all:so it produces a correct bundle even when run from an Intel or Apple-SiliconMac.

Deployment

Deploy the stacks in the order below. All commands assume you are in therepository root.

1. IAM roles (runner → source → target)

The runner execution role is created first so the source/target trustpolicies can reference its ARN directly (no chicken-and-egg). Account IDs arederived automatically from each CLI profile.

./scripts/deploy-roles.sh \
  --runner-profile central \
  --source-profile source-acct \
  --target-profile target-acct \
  --artifact-bucket my-agentcore-artifacts

2. VPC network

AgentCore only supports specific Availability Zone IDs (in us-east-1:use1-az1, use1-az2, use1-az4). The script prints the AZ name→ID mapping soyou can confirm before deploying.

./scripts/deploy-network.sh --az1 us-east-1a --az2 us-east-1b

3. Build + deploy the AgentCore runtime

deploy.sh runs build.sh, uploads the artifact to S3, deploys the Cognito +runtime stack, and prints the token endpoint and client credentials.

./scripts/deploy.sh \
  --artifact-bucket my-agentcore-artifacts \
  --source-role-arn arn:aws:iam::<SOURCE_ACCOUNT_ID>:role/quick-space-migrator-role \
  --target-role-arn arn:aws:iam::<TARGET_ACCOUNT_ID>:role/quick-space-migrator-role \
  --cognito-domain-prefix quick-migrator-<CENTRAL_ACCOUNT_ID> \
  --runner-role-stack quick-space-migrator-runner-role \
  --network-stack quick-migrator-network

On success the script prints the Runtime ARN, token endpoint, appclient ID/secret, and a ready-to-run curl snippet for obtaining a JWT.

Runtime configuration

The runtime needs only two environment variables (plain-string role ARNs, notsecrets):

Everything else (accounts, spaces, envs, QuickSight service role) is passed as atool input at invocation time.

MCP tools

migrate_spaces inputs

The tool returns a JSON report with the created spaces, agents, connectors,knowledge bases, and buckets (each with linked_to_spaces), plus askipped_permissions block for any principals that could not be resolved in thetarget account.

Integrating with Amazon Quick

Once the runtime is healthy, register it in Amazon Quick as an MCP actionconnector, then let Quick build an app on top of it. You only need to createtwo connectors — the migrator MCP connector and (optionally) a Slackconnector for notifications; Quick generates the app UI for you from theinstructions in docs/quick-app-integration.md.

1. Register the migrator MCP connector

• Type: Action (MCP)
• Endpoint: the AgentCore MCP invocations URL from deploy.sh:https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-runtime-ARN>/invocations?qualifier=DEFAULT
• Network: Public — the AgentCore endpoint is public even in VPC networkmode (VPC mode only affects the runtime's outbound traffic).
• Authentication: Service authentication (2LO) with the Cognito clientID, client secret, token endpoint, and scope printed by deploy.sh.(Cognito does not support Dynamic Client Registration, so choose serviceauth rather than the discovery/DCR flow.)
• Exposes two actions: preview_migration and migrate_spaces.

2. (Optional) Register a Slack connector

• Type: Action
• Action: ChatPostMessage — used to post a summary to a channel after amigration completes.

3. Let Quick build the app

Open Amazon Quick, point it at the two connectors, and provide the buildspecification in docs/quick-app-integration.md.Quick generates the full web app (migration form, preview, confirmation,results with resource-linkage view, Slack notification, and history) — nofront-end code to write by hand.

MCP connector tips

• Tool inputSchema must be JSON Schema Draft 7 (required as an array).
• MCP operations have a 60-second timeout — keep individual calls fast.
• Connectors migrated by this tool carry placeholder secrets and must bere-authenticated in the target account's UI.

Testing with the example scripts

Seed a source account with two spaces (one with a Slack connector, one with anS3 knowledge base) and their agents:

python3 examples/setup_source.py \
  --account-id <SOURCE_ACCOUNT_ID> \
  --region us-east-1 --env dev \
  --qs-service-role aws-quicksight-service-role-v0

Inspect or adjust an agent's space links:

python3 examples/manage_agent_space.py show \
  --account-id <ACCOUNT_ID> --agent-id analytics-agent

Limitations

• S3 objects are not copied. The migrator provisions the target KB bucketand registers the knowledge base, but you must sync the documents and triggeringestion yourself.
• Connectors require re-authentication. Secrets are never read from thesource; migrated connectors carry placeholders and must be re-authorized inthe target UI.
• Principal resolution depends on target registration. Permissions aregranted to a target user only if that identity has been registered in thetarget account (i.e. has signed into QuickSight there at least once).Unresolved principals are reported under skipped_permissions.
• 60-second MCP timeout. Very large migrations (many KBs/agents that sit ina transient state) may approach the MCP socket timeout; the server-sideoperation still completes.

Security

• No credentials or secrets are stored in this repository. The runtime uses onlytwo plain-string role ARNs; the Cognito client secret is fetched from theCognito API by deploy.sh and never committed.
• Cross-account access is least-privilege: the source role is read-only and thetarget role is scoped to the QuickSight/KB/S3 actions required.
• See CONTRIBUTING.md for how toreport a security issue.

Contributing

See CONTRIBUTING.md.

License

This library is licensed under the MIT-0 License. See the LICENSEfile. Third-party dependency licenses are listed inTHIRD_PARTY_LICENSES.