Show the current AWS identity (account, role ARN, user ID) plus SSO token status and time remaining. Use this first to verify auth before running other AWS operations. Returns a structured fix-it message if SSO is expired.

Start an AWS SSO login via the device-code flow (no browser spawned from this process). Returns a verification URL and short code -- surface these to the user so they can open the URL in their own browser and paste the code. After they auth, call aws_login_complete with the returned sessionId to confirm completion.

Block until the SSO login started by aws_login_start finishes (user completed auth in browser, or subprocess exited with error). Returns the new identity on success, or a structured error.

Proactive SSO token check. If the cached token has fewer than thresholdMinutes left (default 10), this kicks off aws_login_start and returns the verification URL + code in one round-trip. If plenty of time remains, returns status: 'ok' with the minutes left. Use at the start of a multi-step AWS workflow to avoid mid-session expiry.

Set the default AWS profile and/or region for the rest of this MCP session. Subsequent calls to aws_whoami, aws_login_*, and other AWS tools will use these values unless they override explicitly. Use when the user says 'switch to prod', 'use us-west-2', 'look at the staging account', etc. Both params are optional; pass whichever changed. Returns the resulting session state.

Show the current session's default AWS profile and region, and where each value came from ('session' = set by aws_session_set, 'env' = AWS_PROFILE/AWS_REGION env var, 'default' = built-in fallback). Useful for confirming state before running operations or debugging why a call hit the wrong account.

Remove session-set profile and/or region overrides so subsequent calls fall back to env vars / defaults. No args clears both. Pass profile: true or region: true to clear just one. Use when the user says 'go back to the default profile,' 'unset the region,' or 'reset session.'

Run an arbitrary AWS API operation via the aws CLI. Use kebab-case service and operation names as in aws help (service='s3api', operation='list-buckets'). Pass params as a JSON object using the AWS API's PascalCase keys (e.g. {Bucket: 'foo'}); they go through --cli-input-json. Session profile/region (from aws_session_set) are used by default; override per-call when needed. For high-level wrappers like 'aws s3 cp' or 'aws ec2 wait', use your shell — this tool targets the low-level API. Returns parsed JSON output by default, plus the literal command that was run.

List AWS profiles configured in ~/.aws/config. Returns profile name, region, and SSO metadata (start URL, region, session name) where set, plus an isSso flag. Use when the user hasn't named a profile, when they ask to switch profiles, or when an SSO-expired error mentions a profile you haven't seen.

Fetch one page of a paginated AWS list/describe operation. Identical to aws_call plus maxItems (page size) and startingToken (resume cursor). When query is supplied it is wrapped server-side as {NextToken, items: } so pagination survives a projection that would otherwise drop NextToken; the handler unwraps items before returning. Returns the parsed response, a nextToken (null when the list is exhausted), and hasMore. Call again with the returned nextToken as startingToken until hasMore is false. Use this instead of aws_call for operations that might exceed the 5 MB stdout cap: list-objects-v2, describe-instances, describe-log-streams, list-roles, etc.

Call STS AssumeRole and stash the returned temporary credentials as a named profile in ~/.aws/credentials. Subsequent calls to aws_call / aws_whoami / aws_paginate can use profile='mcp-' (or your overridden targetProfile name). The raw secret key / session token are NOT returned to the caller — only the profile name, expiration, and assumed identity. Use for cross-account access: a source profile (your SSO identity) assumes a role in another account. Default timeout is 120s (raise via timeoutMs for slow SAML / credential_process setups on cold start).

Tail CloudWatch Logs for a log group. Wraps 'aws logs tail' (not the raw FilterLogEvents API) so you get the same server-side time parsing and event-grouping the CLI uses. Returns recent events as JSON. Does NOT stream -- run once to fetch the window, then call again with a later since. For long windows (> a few hundred events), narrow via filterPattern or lower since.

Query CloudWatch metrics via GetMetricData (the modern multi-metric / expression-capable API, not the legacy get-metric-statistics). Pass queries as a flat array of {id, namespace, metricName, dimensions?, statistic?, period?, expression?, label?}; the tool shapes them into MetricDataQueries for you. startTime/endTime accept ISO 8601 or relative shorthand ('15m', '1h', '1d', '1w'); endTime defaults to 'now'. Period is auto-picked from the time range when omitted (60s for <=3h, 300s for <=24h, 900s for <=15d, 3600s otherwise) to stay under CloudWatch's ~100,800-datapoint response cap. Returns {series: [{id, label?, timestamps, values, period?, statusCode?}], messages?, periodSeconds, profile, region, nextToken, hasMore}. Each series' period is the effective granularity for that query (its explicit period, or the auto-pick it inherited); it is omitted for an expression query that didn't set one. The top-level periodSeconds is always the auto-pick. When CloudWatch truncates a large response, hasMore is true and nextToken carries the resume cursor -- call again with nextToken set to fetch the next page (rare for typical agent queries that stay within the per-request cap). Use for 'show me the CPU on this instance for the last hour', 'sum lambda invocations across these 3 functions', or expression-based 'p99 latency divided by average latency' lookups.

Read a single AWS resource via Cloud Control API. Covers hundreds of resource types with a CloudFormation schema. typeName is '::::' (e.g. 'AWS::Lambda::Function'); identifier is the primary key for that type (function name, bucket name, IAM role name, ARN, or composite id). Returns parsed Properties. For resources not covered by CCAPI or for data-plane operations, use aws_call.

List resources of a given type via Cloud Control API, paginated. Returns an array of {identifier, properties}, a nextToken (null when exhausted), and hasMore. Some types need parent identifiers (e.g. nested resources under a cluster); pass those as resourceModel.

Create an AWS resource via Cloud Control API. Async by default: returns a ProgressEvent with OperationStatus=IN_PROGRESS and a requestToken (top-level) -- poll aws_resource_status with that token, or pass awaitCompletion: true to have the server poll for you and return the terminal event. desiredState is the resource properties JSON matching the CloudFormation schema for typeName.

Update an AWS resource via Cloud Control API using RFC 6902 JSON Patch. Async by default: returns a ProgressEvent with OperationStatus=IN_PROGRESS and a top-level requestToken. Pass awaitCompletion: true to have the server poll until terminal. Typical patch: [{op: 'replace', path: '/MemorySize', value: 512}].

Delete an AWS resource via Cloud Control API. Async by default: returns a ProgressEvent with OperationStatus=IN_PROGRESS and a top-level requestToken. Pass awaitCompletion: true to have the server poll until terminal. Destructive -- double-check identifier before calling.

Poll the status of an async Cloud Control API request (create/update/delete). Pass the requestToken returned by those tools. Returns the current ProgressEvent with OperationStatus: PENDING | IN_PROGRESS | SUCCESS | FAILED | CANCEL_IN_PROGRESS | CANCEL_COMPLETE.

Dry-run a CCAPI update: fetch the current resource state, simulate applying a JSON Patch in memory, and return before/after plus a flat list of changed paths. No mutation is sent to AWS. Use this before aws_resource_update to verify the patch does what you expect. Supports the add/remove/replace subset of RFC 6902 (covers the vast majority of CCAPI updates); 'move'/'copy'/'test' are rejected at schema validation -- use aws_resource_update directly if you need those (CCAPI accepts them, this preview tool just doesn't simulate them locally).

Run the same AWS API operation across multiple regions in parallel. Same shape as aws_call (service, operation, params?, query?, outputFormat?, timeoutMs?) but takes regions: string[] instead of region. Returns an array of {region, ok, data?, command?, error?, errorKind?} -- partial failure is expected (services aren't everywhere, perms may be region-scoped). Duplicate regions in the input are collapsed (first occurrence wins), so results.length may be less than regions.length; use the returned regionCount for the actual count run. Use for fleet-wide reads: 'describe-instances across all our regions', 'list buckets in every region', 'check IAM password policy everywhere'.

Simulate IAM permissions for a principal: can principal X do actions Y on resources Z? Wraps iam simulate-principal-policy. Returns one entry per (action, resource) pair with decision (allowed / explicitDeny / implicitDeny / unknown -- unknown is the malformed-response fallback when EvalDecision is missing or unrecognised), matchedStatementIds (which IAM statements decided), and missingContextValues (context keys the policy needed but you didn't provide -- common for tag-based policies). Use this BEFORE a risky operation to avoid a 403; pairs with the post-failure Suggestion you get from aws_call. Requires iam:SimulatePrincipalPolicy on the caller.

Search the live AWS documentation (the same backend that powers the docs.aws.amazon.com search box). Use this to discover the right doc page for a service, API, or concept the model may not know about -- new services, recently changed APIs, exact parameter names. Returns ranked results as {title, url, summary, excerpt}. Follow up with aws_docs_read on a result's url to get the full page as markdown.

Fetch an AWS documentation page and return it as markdown. url must be an https://docs.aws.amazon.com/...html page (typically one returned by aws_docs_search). Long pages are paginated: pass startIndex (default 0) and maxLength (default 5000 chars); the response includes hasMore and nextStartIndex -- call again with nextStartIndex to continue. Strips nav/cookie-banner/feedback chrome before converting.

Run a short JavaScript snippet that orchestrates other aws-mcp tools (aws.call, aws.paginate, aws.paginateAll, aws.resource.*, aws.logsTail, aws.metricsQuery, aws.iamSimulate, aws.multiRegion, aws.assumeRole, aws.docs.{search,read}) and returns a combined result. Best for batched read+filter+aggregate workflows that would otherwise need N tool round-trips: 'list all Lambdas, fetch each one's config, return those with memory > 1024'. Use return <value> at the end to surface a result; console.log lines are captured and returned alongside. Helpers throw Errors on failure -- use try/catch. NOT a security sandbox -- treat the same as any other tool the model can call.