Cloudamize MCP Pull Agent User Guide

Version: 1.0.0
Last Updated: 2026-07-01
AWS Marketplace: Cloudamize MCP Pull Agent

Overview

The Cloudamize MCP Pull Agent retrieves migration discovery data from Cloudamize and delivers it in the AWS Transform schema. It pulls server inventory, application details, dependencies, and database information from a Cloudamize plan, then returns a normalized JSON payload ready for AWS migration planning.

Use this agent when you already have Cloudamize discovery data and want to bring it into AWS Transform without manual export or reformatting.

How the solution works

Two agents work together on the AWS Transform platform:

• Cloudamize Migration Orchestrator — the agent you interact with in the Transform chat UI. It handles credential setup and coordinates the pull workflow.

• Cloudamize MCP Pull Agent — a background worker that connects to the Cloudamize MCP server, retrieves data, and normalizes it.

You interact only with the orchestrator. The pull agent runs automatically behind the scenes.

Normalized output collections

Prerequisites

Complete the following requirements before deployment.

• An active AWS account with AWS Transform enabled

• Your account allowlisted for the Cloudamize agents in AWS Transform

• Visibility of cloudamize-data-pull-agent and cloudamize-migration-orchestrator in the Transform configuration flow

• Bedrock model access enabled for us.anthropic.claude-sonnet-4-5-20250929-v1:0

• A Cloudamize account with at least one active migration plan

• A valid Cloudamize JWT token for MCP access

• IAM permissions to deploy CloudFormation stacks, create IAM roles, and manage Secrets Manager secrets

JWT token requirement

Generate a JWT token from the Cloudamize MCP Server Admin Setup Guide: Cloudamize MCP Server Admin Setup Guide.

Tokens are valid for 12 hours. Store the token in AWS Secrets Manager immediately after generating it.

Container images

The pre-built container images are shared with your AWS account from the Cloudamize production registry. The default image URIs in the CloudFormation template already point to the production account. You do not need to build or push images.

If your account has not yet been granted access to the images, contact Cloudamize support.

Network access requirements

The agent containers require outbound HTTPS access to the following endpoints:

• mcp.cloudamize.com on port 443

• AWS Secrets Manager API endpoints

• AWS CloudWatch Logs API endpoints

• Amazon ECR endpoints for image pulls

• Bedrock model inference endpoints

• AWS Transform Agentic API endpoints

If deploying in VPC mode, ensure egress is available through a NAT gateway or equivalent routing path.

Installation

Deployment uses a single CloudFormation template that creates both agent runtimes, IAM roles, and optionally the JWT secret.

Deployment through the AWS Console

Step 1: Deploy the CloudFormation stack

1. Open the AWS CloudFormation console in us-east-1.

2. Select Create stack and choose With new resources (standard).

3. Upload the template file deployments/cloudformation/cloudamize-agents.yaml.

4. Enter the required and optional parameters shown below.

5. Acknowledge IAM resource creation and submit the stack.

6. Wait until the stack reaches CREATE_COMPLETE.

Required parameters

JWT secret options

Option A — Let the stack create the secret

Option B — Use an existing Secrets Manager secret

If you use an existing secret, its value must contain either a plain-text JWT string or a JSON object with the key CLOUDAMIZE_JWT_TOKEN.

Optional parameters

Step 2: Record stack outputs

After deployment completes, capture the following values from the Outputs tab.

Step 3: Bind runtimes in AWS Transform

1. Open AWS Transform and navigate to agent configuration.

2. Select Cloudamize Migration Orchestrator.

3. Enter the OrchestratorRuntimeArn and AWSTransformAgentInvokeRoleArn.

4. Repeat for Cloudamize MCP Pull Agent using PullAgentRuntimeArn.

5. Save the configuration.

Deployment through the CLI

Use the following commands if you prefer command-line deployment.

Deploy using an existing JWT secret

aws cloudformation deploy \
  --region us-east-1 \
  --stack-name cloudamize-agents \
  --template-file deployments/cloudformation/cloudamize-agents.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    JwtSecretArn=arn:aws:secretsmanager:us-east-1:<account>:secret:<name>

Deploy and let the stack create the secret

aws cloudformation deploy \
  --region us-east-1 \
  --stack-name cloudamize-agents \
  --template-file deployments/cloudformation/cloudamize-agents.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    CloudamizeJwtToken=<your-jwt-token> \
    JwtSecretName=cmz/auth/token

Reuse existing IAM roles

CreateAgentCoreExecutionRole=false \
ExistingAgentCoreExecutionRoleArn=arn:aws:iam::<account>:role/<role-name> \
CreateAWSTransformAgentInvokeRole=false \
ExistingAWSTransformAgentInvokeRoleArn=arn:aws:iam::<account>:role/<role-name>

Validation commands

aws cloudformation describe-stacks --stack-name cloudamize-agents \
  --query 'Stacks[0].StackStatus'

aws logs describe-log-streams \
  --log-group-name /aws/bedrock-agentcore/ \
  --order-by LastEventTime --descending --limit 5 \
  --region <region>

Running a Transform Job

Start a job

1. Open the AWS Transform chat UI.

2. Select the Cloudamize Migration Pull agent.

3. 
   

   • Pull the migration portfolio assessment for plan 5

   • List my Cloudamize plans

   • Get server and application data from Cloudamize plan 12

Connect credentials

On the first request in a job, the orchestrator prompts you to connect your Cloudamize credentials.

1. Select an existing Secrets Manager connector, or create a new one.

2. Provide the Secret ARN for the secret holding your JWT.

3. Optionally provide the KMS key ARN if the secret uses a customer-managed key.

4. Submit the form.

The agent resolves the JWT securely and caches it for the remainder of the job.

Find a plan ID

If you do not know the plan ID, ask the orchestrator to list available Cloudamize plans. It returns plan IDs and display names so you can choose the correct plan.

Retrieve assessment data

After credentials are resolved and a plan ID is provided, the workflow performs these actions:

1. Launches a subagent instance

2. Connects to the Cloudamize MCP server

3. Retrieves the full Migration Portfolio Assessment for the plan

4. Normalizes the data into the AWS Transform schema

5. Returns the result in chat

This process typically takes from 30 seconds to a few minutes depending on portfolio size.

Timeout behavior

Configuration Reference

Environment variables

The CloudFormation template sets required environment variables automatically. In most deployments, no manual changes are needed.

Automatically set variables

Optional advanced overrides

Using existing IAM roles

Your existing roles must provide the same permissions as the roles created by the deployment template.

IAM permission model

AgentCoreExecutionRole is used by Bedrock AgentCore to run agent containers and requires permissions to:

• Read the JWT secret from Secrets Manager

• Write logs to CloudWatch under /aws/bedrock-agentcore/

• Invoke Bedrock models

• Pull images from ECR

• Call AWS Transform Agentic APIs

AWSTransformAgentInvokeRole is used by AWS Transform and requires permissions to:

• Invoke your Bedrock AgentCore runtimes

• Get runtime status

• Get runtime endpoint information

Both roles use source-account and source-ARN conditions to reduce cross-account misuse risk.

Updating and Maintenance

JWT rotation

1. Generate a new token from the Cloudamize MCP Server Admin console.

2. Update the secret value in AWS Secrets Manager.

3. No redeployment is required. The next job uses the updated token.

Container image updates

1. Cloudamize publishes updated images to the production registry.

2. Update the CloudFormation stack if a new image URI or tag is provided.

3. The runtimes pull the updated image on the next invocation.

Changing network mode

1. Update the CloudFormation stack.

2. Change the NetworkMode parameter.

3. If switching to VPC mode, ensure outbound internet access is available.

Deleting the deployment

1. Unbind the runtimes in AWS Transform.

2. Delete the CloudFormation stack.

3. Optionally delete the Secrets Manager secret if it is no longer needed.

Troubleshooting

Where to view logs

Agent logs are available in CloudWatch Logs under /aws/bedrock-agentcore/. Logs are structured as JSON and sensitive values are redacted automatically.

Key log events

Common issues and resolutions

Agent fails to start

Symptom: Runtime never reaches a healthy state.

Resolution:

1. Check CloudWatch logs for environment.audit.

2. Verify CLOUDAMIZE_JWT_SECRET_ID points to a valid secret ARN.

3. Confirm the execution role includes secretsmanager:GetSecretValue.

4. Confirm Bedrock model access is enabled for us.anthropic.claude-sonnet-4-5-20250929-v1:0.

Credential form does not appear

Symptom: Connector selection UI is blank or missing.

Resolution:

1. Verify you are running agent version 1.0.0 or later.

2. Check that the Transform job created a valid HITL step.

3. Contact AWS Transform support if the connector form does not render.

No CLOUDAMIZE_JWT_TOKEN present

Symptom: Job fails because the JWT could not be resolved.

Resolution:

1. Verify the secret exists at the configured ARN.

2. Verify the secret contains either a plain JWT string or JSON with the key CLOUDAMIZE_JWT_TOKEN.

3. Confirm the execution role can read the secret.

4. Check for orchestrator.get_credentials.success in logs.

Cannot connect to Cloudamize MCP server

Symptom: Connection failures to mcp.cloudamize.com.

Resolution:

1. Verify outbound HTTPS access on port 443.

2. If using VPC mode, confirm NAT or routing supports internet egress.

3. Verify DNS resolution for mcp.cloudamize.com.

4. Check whether proxy settings block the connection.

Subagent reached terminal status FAILED

Symptom: The orchestrator reports a subagent failure.

Resolution:

1. Review the subagent CloudWatch logs.

2. Verify the JWT is valid and not expired.

3. Confirm the plan ID exists in Cloudamize.

4. Confirm network connectivity to mcp.cloudamize.com.

Timeout after 600 seconds waiting for subagent

Symptom: The job fails after 10 minutes.

Resolution:

1. Large portfolios may take longer to retrieve and normalize.

2. Check network connectivity.

3. Check Cloudamize MCP server health.

4. For plans with more than 10,000 servers, contact Cloudamize support.

Zero records returned

Symptom: The job succeeds but record_counts are all zero.

Resolution:

1. Verify the selected plan contains discovery data.

2. Check logs for schema.map.completed.

3. Look for schema.map.empty_payload warnings.

Credential step keeps repeating

Symptom: The orchestrator asks for credentials repeatedly.

Resolution:

1. Verify you are using version 1.0.0 or later.

2. Start a new Transform job if the issue persists.

Error reference

Frequently Asked Questions

General

Do I need a Cloudamize subscription?
Yes. You need a Cloudamize account with active migration plans and MCP access.

What regions are supported?
The agent is tested in us-east-1. Other regions may work but have not been validated.

Can I pull data for multiple plans in one job?
No. Each job handles one plan. Run separate jobs for additional plans.

How do I find my plan ID?
Ask the orchestrator to list your Cloudamize plans and select the required ID from the returned list.

Security and operations

How often should I rotate the JWT?
Cloudamize tokens expire after 12 hours. Update the secret before each working session or automate rotation.

Is the JWT visible to the AI model?
No. The JWT is removed before the LLM processes the message and is redacted from logs.

Can I use a customer-managed KMS key?
Yes. Supply the KMS key ARN when creating or selecting the Secrets Manager connector.

What Bedrock model does the agent use?
us.anthropic.claude-sonnet-4-5-20250929-v1:0.

How do I update the JWT without redeploying?
Update the value in AWS Secrets Manager. The next job uses the new token automatically.

What happens if the Cloudamize MCP server is unavailable?
The agent retries transient failures such as HTTP 408, 429, and 5xx responses up to three times with exponential backoff.

Known Limitations

• One plan per job

• Plan IDs must be positive integers

• 10-minute timeout on subagent processing

• 30-minute timeout on credential form completion

• Validated in us-east-1 only

Security Summary

• Your Cloudamize JWT is stored in your own AWS Secrets Manager account

• The JWT is never exposed to the AI model and never appears in logs

• All communication with Cloudamize uses HTTPS

• IAM roles follow least-privilege design scoped to your resources

• Trust policies include source-account conditions to reduce cross-account misuse

• Sensitive values in logs are automatically redacted

• Cloudamize support — Contact your Cloudamize account team for JWT generation, MCP connectivity, and plan-related issues

• AWS Transform support — Use for platform issues, runtime binding problems, or HITL UI issues

• AWS Marketplace listing — Cloudamize MCP Pull Agent