Example: Connect Redshift through a collection agent with Claude

This example connects a private Redshift Serverless workgroup through an AWS collection agent that's already registered. Don't have one yet? Start with Create and register an AWS collection agent with Terraform (or with the AWS CLI). For a Redshift that Monte Carlo reaches directly, with Monte Carlo storing the password, see Connect Redshift from the Monte Carlo cloud.

Before you start

• Claude with the Agent Toolkit plugin, signed in to the Monte Carlo MCP server. See Agent Toolkit.
• A registered AWS collection agent that can reach Redshift: the agent's subnets route to the workgroup or cluster, and its security group allows port 5439 from the agent (or the VPC).
• A Redshift user with the grants in Redshift, and at least one table.

1. Store the credentials in AWS Secrets Manager

The agent expects the Redshift keys under connect_args. For Serverless, host is the workgroup endpoint (<workgroup>.<account-id>.<region>.redshift-serverless.amazonaws.com). The password is read from a hidden prompt and passed through the environment, so it isn't shown, saved in your shell history, or visible in the process list:

REGION=<region>
read -r -s -p "Redshift password: " RSPASS; echo
RSPASS="$RSPASS" jq -n \
  --arg host "<endpoint>" --argjson port 5439 \
  --arg db "<database>" --arg user "<monte-carlo-user>" \
  '{connect_args: {host: $host, port: $port, dbname: $db, user: $user, password: $ENV.RSPASS}}' \
  | aws secretsmanager create-secret --region "$REGION" \
      --name mc/redshift --secret-string file:///dev/stdin \
      --query ARN --output text
unset RSPASS

In zsh, replace the read line with read -r -s "RSPASS?Redshift password: ".

2. Ask Claude

/monte-carlo-onboarding add our Redshift Serverless through our existing AWS agent; credentials are in AWS Secrets Manager

Claude reads your account first. In this example it reported the existing agent and what's on it, confirmed that redshift can be connected through it with a Secrets Manager reference, and checked that no Redshift warehouse or connection exists yet, so nothing would be collected twice. It then listed the steps on your side, starting with the agent's read access to the secret, and what it still needed.

3. Let the agent read the new secret

Claude gives you this before checking the secret: a check only passes once the agent can read it. A separately named inline policy leaves the agent's existing grants untouched; list the role's policies first, because put-role-policy replaces a policy with the same name.

REGION=<region>
STACK=<agent-stack-name>
ROLE=$(aws cloudformation describe-stack-resource \
  --region "$REGION" --stack-name "$STACK" \
  --logical-resource-id ExecutionRole \
  --query StackResourceDetail.PhysicalResourceId --output text)
SECRET_ARN=<redshift-secret-arn>
aws iam list-role-policies --role-name "$ROLE"

cat > secret-policy.json <<EOF
{"Version": "2012-10-17", "Statement": [{"Effect": "Allow",
  "Action": "secretsmanager:GetSecretValue", "Resource": "${SECRET_ARN}"}]}
EOF
aws iam put-role-policy --role-name "$ROLE" \
  --policy-name mc-agent-read-redshift-secret \
  --policy-document file://secret-policy.json

For an agent deployed with Terraform, the execution role is the mcd-agent module's mcd_agent_execution_role. Add kms:Decrypt if the secret uses a customer-managed KMS key.

4. Answer Claude's questions

Approved. Details:
- Secret: <redshift-secret-arn> (<region>, default KMS key). Keys under connect_args: host (the workgroup endpoint), port, dbname, user, password.
- The agent's execution role has a new inline policy mc-agent-read-redshift-secret with GetSecretValue on that ARN.
- Network: the workgroup is private in the same VPC as the agent; its security group allows 5439 from the VPC CIDR.
- The user has the grants from the Redshift docs.
- Warehouse name: <warehouse-name>. Connection name: <connection-name>.

5. Claude finishes

In this example both the secret check and the connection passed 15/15: the agent read the secret, connected to the workgroup, reached its storage bucket, and read databases, tables, views and query logs (the STL and SYS views). The default jobs are metadata, query_logs, sql_query, json_schema and direct_lineage. The run ends with:

Created in this run
  credentials   <id>  redshift  aws_secrets_manager
  warehouse     <id>  <warehouse-name>  redshift
  connection    <id>  <connection-name>  redshift
  validation    <id>  passed  15/15 passed  (secret reference, before creating)
  validation    <id>  passed  15/15 passed  (connection)

Reused (excluded from cleanup)
  deployment    <id>  COLLECTION_AGENT/AWS  enabled=true
  agent         <id>

Cleanup if you abandon this: delete_connection → delete_warehouse →
delete_aws_secrets_manager_credentials. Keep the deployment and agent.

Collection starts on its own; the first metadata appears within about an hour.

Claude also passed on one non-blocking warning: "Could not run select on the svv_external_tables view." It matters only if you use Redshift Spectrum or other external schemas; then grant USAGE on those schemas to the user in the secret. And if the secret holds an admin user, consider a dedicated least-privilege Monte Carlo user: update the secret, and nothing changes in Monte Carlo.

Troubleshooting