MCP Server AWS IAM — assume roles, simulate policies, and detect privilege escalation

SDK setup and credential providers

The AWS SDK v3 uses modular clients. Install only the services you need — this keeps Lambda deployment packages small and makes tree-shaking effective. Use the fromNodeProviderChain credential provider, which automatically resolves credentials from environment variables, AWS profiles, instance metadata, and ECS task roles in priority order.

import { STSClient, AssumeRoleCommand, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
import { IAMClient, ListPoliciesCommand, SimulatePrincipalPolicyCommand, CreateAccessKeyCommand, GetUserPolicyCommand, ListAttachedUserPoliciesCommand } from '@aws-sdk/client-iam';
import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

const region = process.env.AWS_REGION ?? 'us-east-1';

const baseConfig = {
  region,
  credentials: fromNodeProviderChain()   // env → profile → EC2 IMDS → ECS
};

const stsClient = new STSClient(baseConfig);
const iamClient = new IAMClient(baseConfig);

// Cache for assumed role credentials, keyed by role ARN
const roleCredentialCache = new Map();

async function getAssumedRoleCredentials(roleArn: string, sessionName: string) {
  const cached = roleCredentialCache.get(roleArn);
  // Renew 60 seconds before expiry
  if (cached && cached.expiresAt.getTime() - Date.now() > 60_000) {
    return cached;
  }

  const res = await stsClient.send(new AssumeRoleCommand({
    RoleArn: roleArn,
    RoleSessionName: sessionName,
    DurationSeconds: 3600   // 1 hour; max depends on role's MaxSessionDuration
  }));

  const creds = {
    accessKeyId: res.Credentials!.AccessKeyId!,
    secretAccessKey: res.Credentials!.SecretAccessKey!,
    sessionToken: res.Credentials!.SessionToken!,
    expiresAt: res.Credentials!.Expiration!
  };

  roleCredentialCache.set(roleArn, creds);
  return creds;
}

assume_role tool

The assume_role MCP tool lets agents temporarily adopt a different IAM identity — typically a cross-account role or a role with elevated permissions for a specific task. The key constraint is that the calling principal must have sts:AssumeRole permission on the target role, and the target role's trust policy must allow the calling principal.

import { z } from 'zod';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

server.tool(
  'assume_role',
  {
    role_arn: z.string().regex(/^arn:aws:iam::\d{12}:role\/.+/, 'Must be a valid IAM role ARN'),
    session_name: z.string().min(2).max(64).default('mcp-session'),
    duration_seconds: z.number().int().min(900).max(43200).default(3600)
  },
  async ({ role_arn, session_name, duration_seconds }) => {
    try {
      const res = await stsClient.send(new AssumeRoleCommand({
        RoleArn: role_arn,
        RoleSessionName: session_name,
        DurationSeconds: duration_seconds
      }));

      const creds = res.Credentials!;
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            assumed_role_arn: res.AssumedRoleUser?.Arn,
            access_key_id: creds.AccessKeyId,
            // Do NOT return the secret key in plaintext — return a masked indicator
            secret_access_key_set: true,
            session_token_set: true,
            expires_at: creds.Expiration?.toISOString(),
            assumed_role_id: res.AssumedRoleUser?.AssumedRoleId
          }, null, 2)
        }]
      };
    } catch (err: any) {
      if (err.name === 'AccessDenied') {
        throw new McpError(ErrorCode.InvalidRequest,
          `Access denied: the calling principal lacks sts:AssumeRole on ${role_arn}`);
      }
      throw err;
    }
  }
);

list_iam_policies and get_effective_permissions tools

IAM has three types of policies: AWS managed (owned by AWS, versioned automatically), customer managed (your own reusable policies), and inline (embedded in a user/role/group). The list_iam_policies tool filters by scope. For effective permissions, always use the policy simulation API — it accounts for all layers: SCPs, permission boundaries, session policies, and resource policies.

server.tool(
  'list_iam_policies',
  {
    scope: z.enum(['All', 'AWS', 'Local']).default('Local'),
    path_prefix: z.string().optional(),
    max_results: z.number().int().min(1).max(1000).default(50)
  },
  async ({ scope, path_prefix, max_results }) => {
    const policies: Array<{ name: string; arn: string; type: string; updated: string }> = [];
    let marker: string | undefined;

    do {
      const res = await iamClient.send(new ListPoliciesCommand({
        Scope: scope,
        PathPrefix: path_prefix,
        Marker: marker,
        MaxItems: Math.min(max_results - policies.length, 100)
      }));

      for (const p of res.Policies ?? []) {
        policies.push({
          name: p.PolicyName!,
          arn: p.Arn!,
          type: p.Arn!.startsWith('arn:aws:iam::aws:') ? 'AWS Managed' : 'Customer Managed',
          updated: p.UpdateTime?.toISOString() ?? ''
        });
      }

      marker = res.IsTruncated ? res.Marker : undefined;
    } while (marker && policies.length < max_results);

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ count: policies.length, scope, policies }, null, 2)
      }]
    };
  }
);

server.tool(
  'get_effective_permissions',
  {
    principal_arn: z.string().min(1),   // IAM user or role ARN
    action_names: z.array(z.string()).min(1).max(200),
    resource_arns: z.array(z.string()).default(['*'])
  },
  async ({ principal_arn, action_names, resource_arns }) => {
    const results: Array<{ action: string; resource: string; decision: string; reason: string }> = [];

    // SimulatePrincipalPolicy handles max 100 actions per call
    const chunks = [];
    for (let i = 0; i < action_names.length; i += 100) {
      chunks.push(action_names.slice(i, i + 100));
    }

    for (const chunk of chunks) {
      const res = await iamClient.send(new SimulatePrincipalPolicyCommand({
        PolicySourceArn: principal_arn,
        ActionNames: chunk,
        ResourceArns: resource_arns
      }));

      for (const result of res.EvaluationResults ?? []) {
        results.push({
          action: result.EvalActionName!,
          resource: result.EvalResourceName!,
          decision: result.EvalDecision!,  // 'allowed', 'explicitDeny', 'implicitDeny'
          reason: result.EvalDecisionDetails
            ? JSON.stringify(result.EvalDecisionDetails)
            : result.EvalDecision === 'allowed' ? 'allowed by policy' : 'no matching allow statement'
        });
      }
    }

    const allowed = results.filter(r => r.decision === 'allowed');
    const denied = results.filter(r => r.decision !== 'allowed');

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          principal: principal_arn,
          summary: { allowed: allowed.length, denied: denied.length },
          results
        }, null, 2)
      }]
    };
  }
);

detect_privilege_escalation tool

Privilege escalation in IAM occurs when a principal can combine lower-privilege permissions to grant themselves or others additional access. The three most dangerous patterns are: creating a role and attaching an admin policy (iam:CreateRole + iam:AttachRolePolicy), creating a new policy version with elevated permissions (iam:CreatePolicyVersion), and writing an inline policy directly to a user/role (iam:PutUserPolicy/iam:PutRolePolicy).

const ESCALATION_PATTERNS = [
  {
    name: 'CreateRole + AttachRolePolicy',
    required: ['iam:CreateRole', 'iam:AttachRolePolicy'],
    description: 'Can create a new role with an admin policy and assume it'
  },
  {
    name: 'CreatePolicyVersion',
    required: ['iam:CreatePolicyVersion'],
    description: 'Can overwrite existing policy with a more permissive version'
  },
  {
    name: 'PutUserPolicy / PutRolePolicy',
    required: ['iam:PutUserPolicy'],
    description: 'Can write a new inline policy directly to a user or role'
  },
  {
    name: 'AddUserToGroup',
    required: ['iam:AddUserToGroup'],
    description: 'Can add self to a group with admin permissions'
  },
  {
    name: 'PassRole + EC2/Lambda',
    required: ['iam:PassRole', 'ec2:RunInstances'],
    description: 'Can launch EC2 with an admin role attached'
  },
  {
    name: 'UpdateLoginProfile',
    required: ['iam:UpdateLoginProfile'],
    description: 'Can change another IAM user password and log in as them'
  }
];

server.tool(
  'detect_privilege_escalation',
  {
    principal_arn: z.string().min(1)
  },
  async ({ principal_arn }) => {
    // Collect all IAM actions we need to check
    const allActions = [...new Set(ESCALATION_PATTERNS.flatMap(p => p.required))];

    const res = await iamClient.send(new SimulatePrincipalPolicyCommand({
      PolicySourceArn: principal_arn,
      ActionNames: allActions,
      ResourceArns: ['*']
    }));

    const allowedActions = new Set(
      (res.EvaluationResults ?? [])
        .filter(r => r.EvalDecision === 'allowed')
        .map(r => r.EvalActionName!)
    );

    const risks = ESCALATION_PATTERNS.filter(pattern =>
      pattern.required.every(action => allowedActions.has(action))
    );

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          principal: principal_arn,
          privilege_escalation_risks: risks.length,
          risks: risks.map(r => ({ pattern: r.name, description: r.description, required_permissions: r.required })),
          all_iam_actions_allowed: [...allowedActions].filter(a => a.startsWith('iam:'))
        }, null, 2)
      }]
    };
  }
);

create_access_key tool with confirm guard

server.tool(
  'create_access_key',
  {
    username: z.string().min(1),
    confirm: z.literal(true)   // caller must pass confirm: true — prevents accidental key creation
  },
  async ({ username }) => {
    // Check existing key count first — IAM allows max 2 keys per user
    const existingRes = await iamClient.send(
      new ListAccessKeysCommand({ UserName: username })
    );
    const existing = existingRes.AccessKeyMetadata ?? [];

    if (existing.length >= 2) {
      throw new McpError(ErrorCode.InvalidRequest,
        `User ${username} already has 2 access keys (IAM maximum). Delete one before creating a new key.`);
    }

    const res = await iamClient.send(new CreateAccessKeyCommand({ UserName: username }));
    const key = res.AccessKey!;

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          username: key.UserName,
          access_key_id: key.AccessKeyId,
          secret_access_key: key.SecretAccessKey,   // only shown once at creation
          status: key.Status,
          created_at: key.CreateDate?.toISOString(),
          warning: 'Store the secret_access_key securely — it cannot be retrieved again'
        }, null, 2)
      }]
    };
  }
);

The minimum IAM policy needed by an MCP server that only reads IAM data and calls STS:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:ListPolicies",
        "iam:ListAttachedUserPolicies",
        "iam:ListUserPolicies",
        "iam:GetUserPolicy",
        "iam:SimulatePrincipalPolicy",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    }
  ]
}

Health endpoint: /health/iam

sts:GetCallerIdentity is the canonical IAM health check — it requires no permissions beyond valid credentials. If it succeeds, the credentials are valid and the AWS API is reachable. AliveMCP polls this endpoint and alerts you the moment credentials expire, are deactivated, or the IAM API becomes unreachable.

import express from 'express';

const app = express();

app.get('/health/iam', async (_req, res) => {
  const start = Date.now();
  try {
    const identity = await stsClient.send(new GetCallerIdentityCommand({}));

    res.status(200).json({
      status: 'ok',
      account: identity.Account,
      user_id: identity.UserId,
      arn: identity.Arn,
      latency_ms: Date.now() - start
    });
  } catch (err: any) {
    const status = err.name === 'ExpiredTokenException' ? 401 : 503;
    res.status(status).json({
      status: 'error',
      error_code: err.name,
      error: err.message,
      latency_ms: Date.now() - start
    });
  }
});

app.listen(3001);

Frequently asked questions

Further reading

• MCP Server Cloudflare Access — JWT validation and access policy management
• MCP Server Okta — user lifecycle, group management, and SSO integration
• MCP Server HashiCorp Vault — secrets management and AppRole auth
• MCP Server Authentication — token management and security patterns
• MCP Server Health Check — wiring /health endpoints for uptime monitoring