• STATUS
  • DETAILS
  • LOGS
  • HUMAN

How to troubleshoot SSO connections with your AI

Connect WorkOS to your AI client to turn login errors into actionable fixes. Your agent handles the data retrieval so you can focus on the configuration.

Ask AI about this page

Short answer

Why can't my users log in via SSO?

Your AI pulls real-time connection status and metadata from WorkOS to find misconfigured SAML or OIDC settings. It identifies exactly where the handshake is failing so you can fix it.

Troubleshooting outcomes

Where every issue lands.

The AI categorizes the data it finds into these specific outcomes.

STATUS

Connection health check

The AI checks the current state of all active SSO links. You get a clear view of which connections are active or broken.

DETAILS

Metadata inspection

The agent pulls specific configuration details for a single connection. This helps you see if an IDP or ACS URL is wrong.

LOGS

Error identification

The AI looks for specific metadata that points to failed handshakes. It highlights the exact reason a login attempt failed.

HUMAN

Manual fixes needed

The AI identifies where the configuration is broken. You must go into the WorkOS dashboard or your IDP to apply the actual changes.

The workflow

What your AI does when the issue arrives.

Instead of clicking through dashboards, you just describe the problem to your agent.

  1. Scan connections

    The AI looks through your WorkOS environment to find the specific SSO setup causing trouble.

    list_sso_connections

  2. Deep dive into settings

    Once the problematic connection is found, the AI pulls the specific technical parameters for that link.

    get_sso_connection_details

  3. Analyze the mismatch

    The agent compares the retrieved metadata against your troubleshooting requirements to find the error.

    get_sso_connection_details

  4. Report the fix

    The AI summarizes the findings and tells you which setting needs to change in your IDP.

    list_sso_connections

Try it

Copy these to start.

Use these prompts to kick off a troubleshooting session.

Starting points

Replace the bracketed text with your specific connection names or error types.

WorkOS Connector

You're all set. Choose your MCP client and follow the setup instructions.

Connector linkhttps://edge.vinkius.com/vk_preview_rwxMA9lZDQOsPAB4YWRqrtYcwkF7I80gqKgTYNRP/mcp

Claude Desktop

Follow the steps below to connect in seconds.

  1. 1In Claude Desktop, open Settings → Connectors.
  2. 2Click “Add custom connector” and paste the connector link above as the remote MCP server URL.
  3. 3Click Add and start a new chat — WorkOS capabilities are ready to use.
Configuration · claude_desktop_config.jsonCopy
{
  "mcpServers": {
    "workos-mcp": {
      "url": "https://edge.vinkius.com/vk_preview_rwxMA9lZDQOsPAB4YWRqrtYcwkF7I80gqKgTYNRP/mcp"
    }
  }
}
Copy into chat04

  • List all my SSO connections and tell me if any are currently inactive.

  • Get the details for the 'Acme Corp' SAML connection and check the ACS URL.

  • Check the metadata for my OIDC connection to see if the client ID matches my expectations.

  • Find the SSO connection named 'Global Enterprise' and tell me why it might be failing.

  • Claude
  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Code
  • JetBrains
  • Cline

Start here

Connect WorkOS once, then ask.

Link your WorkOS account to Vinkius in one click. Your credentials stay encrypted, and your AI client gets immediate access to your SSO data.

Connect WorkOS to your AI

FAQ

How this task behaves.

  • 01

    Can the AI change my SSO settings?

    No. The AI can only read connection lists and metadata. You have to make all configuration changes manually in WorkOS.

  • 02

    Can it fix a broken SAML assertion?

    No. The AI can identify that an assertion is failing by looking at the connection details, but it cannot rewrite the assertion itself.

  • 03

    Does it see my users' passwords?

    No. The tools only access SSO connection metadata, not individual user credentials or passwords.

  • 04

    How does it know which connection is broken?

    It uses the connection metadata to find discrepancies in the configuration that lead to login failures.

  • 05

    Can I use this to set up a new connection?

    No. This specific task is for auditing and troubleshooting existing connections using the available read tools.

  • More questions about WorkOS? See everything the WorkOS Connector can do

Connect WorkOS to Claude, Cursor, ChatGPT & more