What is aws-sso-refresh?

The AWS SSO Token Refresh skill is designed to eliminate authentication friction for developers using AWS Model Context Protocol (MCP) tools. It proactively detects expired SSO sessions and automates the re-authentication workflow, ensuring that AI-driven cloud operations remain uninterrupted by handling token refreshes across multiple IDEs and CLI environments.

When should I use aws-sso-refresh?

aws-sso-refresh is useful in the following scenarios: • Automatically resolving 'ExpiredTokenException' or 'Token has expired' errors during cloud resource management tasks in Claude Code or Cursor. • Streamlining multi-profile AWS management by automatically mapping specific MCP servers to their corresponding AWS SSO profiles for quick re-authentication. • Maintaining continuous development workflows in VS Code or Claude Desktop by triggering browser-based SSO logins only when necessary, preventing manual CLI interruptions. • Simplifying the recovery process when AWS Bedrock or S3 tools fail due to session timeouts, allowing the AI to self-heal the connection and retry the operation.

name	aws-sso-refresh
description	Automatically refresh AWS SSO authentication tokens when encountering expiration errors. Use when AWS MCP tools fail due to expired SSO sessions.

AWS SSO Token Refresh

You are an expert at handling AWS SSO authentication token expiration and refresh.

When to Use This Skill

Activate this skill when you encounter AWS SSO token expiration errors, such as:

"Token has expired and refresh failed"
"Error when retrieving token from sso"
"The SSO session associated with this profile has expired"
"ExpiredTokenException"
Any AWS MCP tool failures mentioning authentication or token issues

How to Refresh

Use the mcp__aws-sso__refresh_aws_sso_token tool. It automatically:

Looks up the correct AWS profile from MCP config files
Initiates the SSO login flow
Opens a browser for authentication

Option 1: Pass the Server Name (Recommended)

When an MCP tool fails, pass the server name to automatically find the correct profile:

mcp__aws-sso__refresh_aws_sso_token(server: "bedrock-kb")

The tool searches multiple MCP client configs (Claude Code, Claude Desktop, Cursor, VS Code, Gemini CLI, etc.) to find the AWS_PROFILE for that server.

Option 2: Pass the Profile Directly

If you know the profile name:

mcp__aws-sso__refresh_aws_sso_token(profile: "MCPServerReadAccess")

Note: At least one of server or profile must be provided. The tool does not use a default profile to prevent unintended authentication actions.

Workflow

When an AWS MCP operation fails due to expired tokens:

Identify the failing MCP server: Note which tool failed (e.g., mcp__bedrock-kb__* → server is bedrock-kb)

Call the refresh tool with the server name:

mcp__aws-sso__refresh_aws_sso_token(server: "bedrock-kb")

Inform the user: "Your AWS SSO session has expired. Please complete the authentication in your browser."
Wait for completion: The tool will return success/failure status
Retry the operation: Once refreshed, retry the original AWS operation

Example

Tool mcp__bedrock-kb__ListKnowledgeBases fails:

Error: Token has expired and refresh failed

Response:

mcp__aws-sso__refresh_aws_sso_token(server: "bedrock-kb")

Result:

{
  "success": true,
  "profile": "MCPServerReadAccess",
  "profileSource": "mcp_config",
  "message": "Successfully refreshed SSO token for profile \"MCPServerReadAccess\"."
}

Then retry ListKnowledgeBases.

Supported MCP Clients

The tool automatically searches these config locations:

Client	Config Location
Claude Code	`.mcp.json`
Claude Desktop	Platform app support directory
Cursor	`.cursor/mcp.json`
VS Code	`.vscode/mcp.json`
Gemini CLI	`.gemini/settings.json`
Copilot CLI	`~/.copilot/mcp-config.json`
Amazon Q	`~/.aws/amazonq/mcp.json`
Cline	VS Code extension settings

Proactive Behavior

Automatically detect token expiration errors
Use the server parameter to find the correct profile automatically
If profile lookup fails, always ask the user which profile to use before retrying
Never call the tool without a server or profile parameter
Keep the user informed about authentication status

Important Notes

SSO login opens a browser window - ensure user can access it
Tokens typically expire after several hours
Multiple MCP servers may share the same profile
After refresh, all servers using that profile will work again
The tool has a 2-minute timeout for browser authentication

aws-sso-refresh

When & Why to Use This Skill

Use Cases