Cosmo Docs
Troubleshooting

Connection Troubleshooting

Troubleshooting MCP integration connections and tool availability.

Integration Won't Connect

OAuth flow doesn't complete

Symptoms: Clicking "Connect" opens the browser but the integration never shows as connected.

  1. Check that your browser allows the redirect. After authorizing on the external service, the browser redirects back to Cosmo. If your browser blocks popups or redirects, this will fail. Allow redirects from the service's domain.

  2. Check that you're authorizing with the right account. If you're signed into multiple accounts (e.g., two Google accounts), make sure you authorize with the one you intend to use.

  3. Try in a different browser. Some browser extensions (ad blockers, privacy extensions) interfere with OAuth redirects.

  4. Check if the external service is accessible. Try opening the service directly (e.g., drive.google.com) to rule out a service outage.

  5. Disconnect and try again. If the integration shows as partially connected, disconnect it first:

    • Go to Settings → Integrations
    • Click the integration
    • Click Disconnect
    • Click Connect and retry the OAuth flow

OAuth tokens expired

OAuth tokens from most services expire after 60–90 days and need to be refreshed.

Symptoms: Integration was working before but now shows as disconnected or errors appear when using tools.

Fix:

  1. Go to Settings → Integrations
  2. Find the expired integration (it may show a warning badge)
  3. Click Reconnect
  4. Complete the OAuth flow again

Your integration configuration (which instance, any custom settings) is preserved when you reconnect — you only re-authorize the credentials.

"Access denied" or "Insufficient permissions" errors

The integration was authorized with an account that doesn't have permission to access the resource you're asking about.

  1. Check that the authorized account has access to the files, projects, or data you're trying to use
  2. If needed, disconnect and reconnect with an account that has the appropriate access
  3. For Google Drive: ensure you've granted access to the specific folders or shared drives you need

API key integration won't connect

Symptoms: After pasting an API key, the integration shows as "Invalid credentials" or fails to connect.

  1. Verify the key is correct. Copy-paste it fresh from the external service — don't retype it.
  2. Check for leading/trailing spaces. The key field may have accidentally captured whitespace.
  3. Check the key's permissions. Some services require specific scopes on API keys. Review the integration's setup guide to see what permissions are needed.
  4. Check if the key is active. Some services let you deactivate keys. Verify the key is active in the service's settings.
  5. Check for key expiry. Some services issue keys with expiry dates.

Tools Not Appearing in Chat

Connected integration's tools don't show up

After connecting an integration, its tools should be available to AI in every conversation. If they're not:

  1. Ensure the integration is enabled for your workspace. Go to Settings → Integrations and check that the integration is toggled on for your current workspace. Some integrations can be enabled/disabled per workspace.

  2. Refresh the session. Start a new chat session — tool availability is loaded at session start.

  3. Check the integration's status. Go to Settings → Integrations and verify the integration shows as "Connected" (green). If it shows an error, reconnect it.

  4. Verify you're in the right organization. Tools are scoped to an organization's connections. If you're in a different org than where you set up the integration, the tools won't be available.

Some tools work but others don't

Each integration exposes multiple tools. A tool-level failure usually means:

  1. Permission issue — the authorized account doesn't have access to perform that specific action (e.g., can read files but not create them)
  2. Service-specific limitation — the external service has rate limits, requires a higher plan, or has disabled the API feature
  3. Scope issue — the OAuth authorization didn't include the necessary scope. Disconnect, reconnect, and ensure you grant all requested permissions during OAuth

Tools appear but return errors when used

"Rate limit exceeded"
The external service is throttling requests. Wait a few minutes and try again. For heavy usage, check if the service has a paid tier with higher limits.

"Resource not found"
The resource you asked about doesn't exist, was deleted, or the authorized account can't see it. Verify the resource exists in the external service directly.

"Authentication failed" during tool use
The stored credentials are invalid or expired. Reconnect the integration.

"Service unavailable" or timeout
The external service is having an outage or is slow. Check the service's status page. Retry after a few minutes.

Integration-Specific Issues

Google Drive

  • Can't find files: Files in "Shared with me" require the "Files: All files including those shared with me" permission scope. Reconnect the integration and grant all requested permissions.
  • Shared drives not accessible: Google Workspace shared drives require explicit access. Ensure the authorized account is a member of the shared drive.
  • PDF files can't be read: Google Drive's API can't export arbitrary PDFs through the standard API. Export the PDF as Google Doc format first, or use the file's content if it was originally a Google Doc.

Notion

  • Pages not accessible: Notion's API only exposes pages that were explicitly shared with the integration. In Notion, go to the page, click Share, and add the Cosmo integration under "Connections".
  • Database queries fail: Ensure the database page is also shared with the Cosmo integration, not just the parent workspace.

Atlassian (Jira / Confluence)

  • "This app is not authorized" error: Atlassian uses OAuth 2.1 for remote MCP servers. The auth flow is handled by Atlassian's MCP server, not Cosmo directly. Try disconnecting and reconnecting — the server re-initiates the auth flow.
  • Can only access one Atlassian site: If you have multiple Atlassian sites, you may need to connect separate instances (one per site). Use the Add instance option in the integrations settings.

Microsoft 365

  • Admin consent required: Microsoft 365 integrations require an admin in your Microsoft tenant to grant consent. If you're not the M365 admin, request that your admin complete the consent flow at Settings → Integrations → Microsoft 365 → Admin Consent.
  • "AADSTS65001" error: This means admin consent hasn't been granted. See above.
  • Can access some services but not others: M365 encompasses many services (Teams, SharePoint, OneDrive, Outlook). Each service may require additional permissions. Review and re-consent with expanded permissions if needed.

ClickUp

  • Tasks not showing: Ensure the ClickUp workspace/space/folder you're asking about is accessible to the authorized account.
  • "Workspace not found": ClickUp uses workspace IDs in its API. If you recently renamed or reorganized your ClickUp workspace, the stored reference may be stale. Reconnect the integration.

Pylon

  • Tickets not loading: Verify the API key has the appropriate Pylon permissions. Pylon API keys may be scoped to specific functions — use a key with at minimum read access to tickets.

Multiple Instances

Setting up multiple instances of the same integration

Cosmo supports connecting the same integration multiple times — for example, two Google Drive accounts or two Slack workspaces.

  1. Go to Settings → Integrations
  2. Click the integration you want to add another instance of
  3. Click Add instance
  4. Give it a descriptive name (e.g., "Personal Drive" vs "Work Drive")
  5. Complete the OAuth flow for the new account

When using tools in chat, you can specify which instance: "Search my Work Drive for the Q3 brief".

Removing an integration instance

  1. Go to Settings → Integrations
  2. Click the integration
  3. Click the instance you want to remove
  4. Click Remove instance

This revokes Cosmo's access to that account. It doesn't revoke access at the provider side — to fully revoke, also remove Cosmo from the app's authorized connections in the external service.

Getting More Help

If your integration issue isn't covered here:

  1. Check if the external service has an active incident on their status page
  2. Try the integration in a private/incognito browser window to rule out extension interference
  3. Contact support@getcosmo.app with:
    • Which integration you're having trouble with
    • Whether it's a new setup or was previously working
    • The exact error message shown
    • Your OS and Cosmo version (Settings → About)

Desktop Troubleshooting

Solutions to common issues with the Cosmo desktop app.

Glossary

Key terms and definitions used throughout Cosmo.

On this page

Integration Won't ConnectOAuth flow doesn't completeOAuth tokens expired"Access denied" or "Insufficient permissions" errorsAPI key integration won't connectTools Not Appearing in ChatConnected integration's tools don't show upSome tools work but others don'tTools appear but return errors when usedIntegration-Specific IssuesGoogle DriveNotionAtlassian (Jira / Confluence)Microsoft 365ClickUpPylonMultiple InstancesSetting up multiple instances of the same integrationRemoving an integration instanceGetting More Help