aws-sso-refresh

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:

1. Looks up the correct AWS profile from MCP config files
2. Initiates the SSO login flow
3. 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:

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

2. Call the refresh tool with the server name:

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

3. Inform the user: "Your AWS SSO session has expired. Please complete the authentication in your browser."

4. Wait for completion: The tool will return success/failure status

5. 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