📘 Cloudamize MCP Server End User & Integration Guide

🌐 Overview

The Cloudamize MCP Server is a containerized MCP gateway that exposes Cloudamize APIs to AI tools it connects Cloudamize to AI assistants, AI agents, and large-scale agentic systems through the Model Context Protocol (MCP).

It enables external systems to securely access and use Cloudamize data such as:

📦 Migration Plans

View migration plans, statuses, and provider-specific plan details.

Example Questions

• “What migration plans do I have for AWS?”

• “Show my active plans”

💰 Cost (TCO) Insights

Analyze migration costs and TCO summaries.

Example Questions

• “What is the total cost of my migration plan?”

• “TCO for plan 12345”

🖥 Infrastructure Insights

Explore discovered infrastructure, applications, and assessment data.

Example Questions

• “Summarize my infrastructure”

• “Show unmanaged servers”

• “What applications are running?”

💡 Workload Recommendations

Get cloud sizing and migration recommendations.

Example Questions

• “What instance recommendations do you suggest?”

• “Show AWS recommendations”

🧭 Migration Planning & Connectivity

Understand migration groups, waves, and server dependencies.

Example Questions

• “How are servers grouped for migration?”

• “Show server connectivity for Machine HOST-123”

Cloudamize MCP allows AI systems and agentic workflows to programmatically retrieve and act on Cloudamize assessment and migration data.

🔗 Hosted MCP Endpoints

There are two hosted endpoints. Pick the one that matches how your tool signs in — both expose the same tools and the same data, and neither replaces the other.

🧠 Supported Consumers

Cloudamize MCP can be used by:

🤖 AI Assistants

• Cursor

• Claude Desktop

• IDE copilots

⚙️ AI Agents

• Custom automation agents

• Workflow agents

• Internal orchestration tools

🏗️ Agentic Systems (Enterprise Scale)

• AWS Transform

• Kiro agent

• Internal enterprise migration agents

• Multi-step autonomous workflows

• Cloud optimisation pipelines

💡 What MCP enables

AI systems can:

• Query Cloudamize assessment data

• Retrieve migration plans

• Generate cost and TCO insights

• Fetch workload recommendations

• Understand migration grouping strategies

• Use data inside multi-step automated workflows

🔁 Typical Usage Flow

1. System requests migration or assessment data

2. MCP server fetches Cloudamize data securely

3. Response is returned in structured format

4. AI agent/assistant uses it in reasoning or automation

🌐 Access Modes

❤️ Health check

GET /healthz

Response:

204 No Content

📡 MCP endpoint

POST https://mcp.cloudamize.com/

or local:

POST http://localhost:8080/

🔐 Authentication Methods

The MCP server supports three ways to authenticate. Which ones are available depends on the endpoint you connect to.

1. OAuth browser sign-in — connect.cloudamize.com

Your MCP client opens a Cloudamize sign-in page in your browser. You sign in with your Cloudamize email and password, or your email and API key. The client receives an access token automatically — you never copy or paste a token. This is the recommended method for Claude Desktop; see Connect via OAuth below.

2. Bearer Token — mcp.cloudamize.com

Authorization: Bearer <access_token>

A per-user, 12-hour token you generate yourself (see Generate Access Token below) and paste into your client’s configuration.

🔑 Generate Access Token

#!/usr/bin/env bash
#===============================================================================
# cmz-auth.sh
#
# Retrieves a scoped bearer token from the Cloudamize PreCloud API. Exchanges
# Basic-auth credentials for an access token and — when the account spans
# multiple engagements — prompts for a customer ID and returns a
# customer-scoped token.
#
# Copyright (c) 2026 Cloudamize. All rights reserved.
# Proprietary and confidential. Internal use only — do not distribute.
#
# Product    : Cloudamize — Cloud Migration, Analytics & FinOps Platform
# Component  : PreCloud API / Authentication
# Maintainer : Platform Engineering <platform@cloudamize.com>
# Version    : 1.0.0
# Updated    : 2026-08-06
#
# Usage:
#   API_USER='<email>' API_PASS='<password>' ./cmz-auth.sh
#   TOKEN=$(API_USER='<email>' API_PASS='<password>' ./cmz-auth.sh)
#
#   Credentials are read from the environment — never hardcode them here.
#
# Requirements : bash 4+, curl 7.76+ (--fail-with-body), jq 1.6+
#
# Exit codes:
#   0  success — token written to stdout
#   1  missing credentials, auth failure, or malformed API response
#===============================================================================
 
set -euo pipefail
 
API_BASE="https://precloud-api.cloudamize.com"
 
CLOUDAMIZE_USER="${API_USER:-your-email@email.com}"
CLOUDAMIZE_PASS="${API_PASS:-your password}"
 
CURL=(curl --fail-with-body --silent --show-error --location
      --connect-timeout 5 --max-time 30)
 
log() { printf '%s\n' "$*" >&2; }
die() { log "ERROR: $*"; exit 1; }
 
api_get() {  # url token
  "${CURL[@]}" "$1" -H "Authorization: Bearer $2"
}
 
log "Requesting initial token..."
auth_json=$("${CURL[@]}" --user "$CLOUDAMIZE_USER:$CLOUDAMIZE_PASS" \
            "$API_BASE/auth/token?termsAccepted=true") \
  || die "auth/token failed"
token=$(jq -er '.access_token' <<<"$auth_json") \
  || die "no access_token: $auth_json"
log "Initial token received."
 
user_json=$(api_get "$API_BASE/user/data" "$token") \
  || die "user/data failed"
has_multi=$(jq -r '(.hasMultipleEngagements // false)' <<<"$user_json")
 
if [[ "$has_multi" == "true" ]]; then
  log "Multiple engagements found."
  eng_json=$(api_get "$API_BASE/engagements" "$token") \
    || die "engagements failed"
  # tolerate bare array or {engagements:[...]}
  jq -r '(if type=="array" then . else .engagements end)[]
         | "\(.customerId)\t\(.company // .customerName // .name)"' \
    <<<"$eng_json" | column -t -s $'\t' >&2
 
  read -rp "Enter Customer ID: " customer_id
  [[ -n "$customer_id" ]] || die "no customer ID entered"
 
  final_json=$(api_get "$API_BASE/auth/token?customerId=${customer_id}" "$token") \
    || die "customer token failed"
  final_token=$(jq -er '.access_token' <<<"$final_json") \
    || die "no access_token for $customer_id: $final_json"
else
  log "Single engagement found."
  final_token="$token"
fi
 
printf '%s\n' "$final_token"

How to Use cmz-auth.sh

1. Save the script as cmz-auth.sh in your working directory.

2. Make it executable:

bash

   chmod +x cmz-auth.sh

3. Run the script with your credentials:

bash

   API_USER='your-email@example.com' API_PASS='your-password' ./cmz-auth.sh

4. If multiple engagements are found, the script lists available Customer IDs — enter the relevant Customer ID when prompted.

5. Token is returned on stdout

⏳ Token Info

• Token validity: 12 hours

• Expired token → returns 401 Unauthorized

• Must be refreshed periodically

🔐 Connect via OAuth (Claude Desktop and other connector-based clients)

connect.cloudamize.com lets you connect without generating, pasting, or refreshing a token. You sign in to Cloudamize in your browser, and your MCP client handles the rest.

Prerequisites

• A Cloudamize assessment account (email + password, or email + API key)

• An MCP client that supports remote OAuth MCP servers — e.g. Claude Desktop custom connectors

Step 1 — Add the connector

In Claude Desktop: Settings → Connectors → Add custom connector. Enter the URL:

https://connect.cloudamize.com

Step 2 — Sign in

Click Connect. A browser window opens on the Cloudamize sign-in page:

• Email — your Cloudamize account email

• Password or API key — either works

Step 3 — Choose an engagement (only if you have more than one)

If your account has access to multiple engagements, you’ll see a Choose an engagement page. Pick the engagement you want this connection to use, and the session is scoped to it. If you have exactly one engagement, this page is skipped automatically.

Step 4 — Start using Cloudamize tools

The browser hands control back to your client, which discovers the Cloudamize tools automatically. Ask questions like:

• “Show my infrastructure assessment”

• “What is the TCO for my migration plan?”

• “Get migration recommendations”

⏳ Re-authentication

Your Cloudamize session lasts about 12 hours. When it expires, your client prompts you to sign in again and the browser window reopens. There is no token to refresh manually — this is by design: Cloudamize never stores your password, so a fresh sign-in is required.

⚠️ OAuth troubleshooting

🔑 Connect with a token (Cursor, config-file clients, agents)

Use this path when your client doesn’t support OAuth connectors, or when you’re wiring up automation.

Prerequisites

You need:

1. A Cloudamize API bearer token (see Generate Access Token), or an API key for automation

2. An MCP client that accepts a server URL plus headers — e.g. Cursor, Claude Code, custom agents

Step 1 — Obtain Your Access Token

As mentioned above in Authentication Methods Section

Example token:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Keep this token secure. It provides access to Cloudamize MCP tools and APIs.

Step 2 — Configure Your MCP Client

Add the Cloudamize MCP server to your MCP client configuration:

{
  "mcpServers": {
    "cloudamize": {
      "url": "https://mcp.cloudamize.com",
      "headers": {
        "Authorization": "Bearer $TOKEN"
      }
    }
  }
}

Replace $TOKEN with your actual bearer token.

For non-interactive automation, use an API key instead of a bearer token:

{
  "mcpServers": {
    "cloudamize": {
      "url": "https://mcp.cloudamize.com",
      "headers": {
        "X-API-Key": "$API_KEY",
        "X-Customer-Id": "$CUSTOMER_ID"
      }
    }
  }
}

Step 3 — Restart Your MCP Client

After saving the configuration:

• Restart Cursor / Claude Code / your AI assistant

• The MCP client will automatically:

  • initialize the session

  • negotiate capabilities

  • discover available tools

No manual protocol calls are required.

Step 4 — Start Using Cloudamize Tools

You can now ask natural-language questions such as:

• “Show my infrastructure assessment”

• “Get migration recommendations”

• “Show observed infrastructure”

• “Fetch application dependency data”

• “Get server connectivity details”

⚠️ Troubleshooting

🔐 Security

• Data stays within your Cloudamize account; no external data is used

• Tokens must not be shared or embedded in code

• Do not store credentials in chat

• Use API keys or tokens securely

• With OAuth, your Cloudamize password is never stored by the MCP server — it’s used once at sign-in to obtain a short-lived token

🧭 Decision Guide

👉 Use connect.cloudamize.com (OAuth) if:

• You’re on Claude Desktop or another connector-based client

• You’d rather sign in with a browser than manage a token

• You don’t want to re-paste a token every 12 hours

👉 Use mcp.cloudamize.com (token / API key) if:

• Your client configures MCP servers via a JSON file with headers (Cursor, Claude Code)

• You’re building an agent, pipeline, or CI job with no human to sign in

• You’re integrating AWS Transform, Kiro, or another agentic system

👉 Use Local MCP if:

• Remote MCP is blocked by your network

• You need offline / internal-network support

• You want full control over the deployment