Skip to main content

Troubleshooting Common Issues

This guide covers the most common problems you'll encounter and how to fix them.

MCP server issues​

MCP server shows "Needs Credentials" or "Connection Error"​

Symptom: Your MCP server shows "Connection Error" or "Credentials expired" warning

Cause: One or more providers don't have credentials configured or have expired credentials.

Fix:

  1. Go to MCP Servers
  2. Open the MCP server
  3. Scroll to the "Credentials" section
  4. Find provider cards marked "Not configured" (amber badge) or showing "Error" badges
  5. Click "Add Credential" (or "Edit" if credential exists) on the provider card
  6. Credential panel slides in from the right
  7. Complete the OAuth flow or enter your API key
  8. Select a validation tool and click "Validate Now"
  9. Status should update to "Ready" with "Credentials valid" subtext when all providers are verified

Still not working? See Credential Verification Issues

Remote agent or Routine says MCP server unavailable​

Symptom: Service OAuth is connected in the dashboard (e.g. QuickBooks shows verified), the generic MCP URL https://mcp.mcpbundles.com/bundle/{slug} is configured in a remote client or Claude Code Routine, but tools fail or the server shows unavailable.

Cause: Missing MCPBundles platform auth — the remote client is not sending your workspace API key on MCP HTTP requests.

Fix:

  1. Go to Settings → Workspace API Keys and create a key (mb_…) if you do not have one
  2. Configure the remote client to send the key in a header on every MCP request — X-API-Key: mb_… or Authorization: Api-Key mb_…
  3. Do not put the key in the URL (no ?token= query parameters)
  4. See Using API Keys and Claude Code Routines

Still not working? Confirm the MCP server slug in the URL matches your dashboard and that service credentials are verified for all required providers.

MCP server shows "Setup Required"​

Symptom: Status shows "Setup Required" (orange badge)

Cause: Required providers don't have credentials configured yet.

What this means:

  • MCP server has never been configured
  • All required providers need credentials
  • Tools won't be available until credentials are added

Fix:

  1. Open the MCP server detail page
  2. Scroll to the "Credentials" section
  3. For each provider card showing "Not configured" badge:
    • Click "Add Credential" button on the provider card
    • Follow the credential setup flow in the credential panel
    • Select a validation tool and click "Validate Now"
  4. Once all required providers show "Verified" badges, status shows "Ready" with "Credentials valid" subtext

Tools disappeared from AI​

Symptom: Tools were working, now AI says "I don't see any tools"

Possible Causes:

1. MCP URL changed​

You might have copied a different MCP URL (/bundle/{slug}).

Fix:

  • Go to MCP Servers
  • Open the MCP server you want to use
  • Copy the MCP URL shown
  • Update it in your AI settings
  • Restart your AI app

2. MCP server was disabled​

You may have disabled it.

Fix:

  • Go to MCP Servers
  • Find the MCP server
  • Click "Enable" if it shows "Disabled"

3. AI app needs restart​

MCP connections sometimes need a refresh.

Fix:

  • Quit your AI app completely
  • Reopen it
  • Wait 10-30 seconds for tools to load

4. Network issue​

MCPBundles servers might be unreachable.

Fix:

  • Open mcpbundles.com
  • Confirm your internet connection
  • Try again in a few minutes

Credential issues​

OAuth flow opens but nothing happens​

Symptom: Clicked "Connect with [Provider]" → OAuth window opens → complete login → window closes → credential panel doesn't reopen or show success

Possible Causes:

1. Pop-up blocker​

Browser blocked the OAuth window or the return.

Fix:

  • Look in the browser address bar for blocked pop-up icon
  • Allow pop-ups from mcpbundles.com
  • Try the OAuth flow again
  • Credential panel should reopen automatically after OAuth completes

2. Third-party cookies disabled​

OAuth requires session cookies.

Fix:

  • Chrome/Edge: Settings → Privacy → Third-party cookies → Add exception for mcpbundles.com
  • Firefox: Settings → Privacy → Enhanced Tracking Protection → Add exception
  • Safari: Preferences → Privacy → Uncheck "Block all cookies"
  • Try OAuth flow again

3. Browser extensions​

Ad blockers or privacy extensions might interfere.

Fix:

  • Disable extensions temporarily (try incognito/private mode)
  • If it works, add mcpbundles.com to the extension's whitelist
  • Re-enable extensions

4. OAuth redirect loop​

Provider's OAuth sent you back, but MCPBundles didn't capture the token.

What to look at:

  • Browser URL — does it have ?code= or ?error= in it?
  • Open browser console (F12) and look for errors

Fix:

  • Go back to your MCP server or provider page
  • Credential panel should reopen automatically after OAuth completes
  • If not, click "Add Credential" on the provider card to try again
  • If you see an error code in the URL, contact the provider's support

5. SessionStorage cleared​

Browser cleared session data during OAuth.

Fix:

  • Don't close the main MCPBundles tab during OAuth
  • Don't click "Clear browsing data" during OAuth
  • Try the flow again - credential panel will reopen after OAuth

Key Feature: The credential panel automatically reopens after OAuth completes! If it doesn't, you may have a browser configuration issue.

Credential verification failed​

Symptom: You entered credentials but validation failed with an error message

Common Causes:

1. Wrong API key​

You copied the wrong key or it has a typo.

Fix:

  • Go back to the provider's website
  • Generate a new API key
  • Copy it carefully (no extra spaces, no line breaks)
  • In the credential panel, update the API key
  • Click "Validate Now" to test again

2. Insufficient Permissions (OAuth)​

Your OAuth token doesn't have the required scopes.

Fix:

  • In the credential panel, click "Connect with [Provider]" again
  • When the OAuth window opens, approve all requested permissions
  • After OAuth completes, the validation tool picker will reopen
  • Select a validation tool and click "Validate Now"

3. API key expired or revoked​

The key is no longer valid on the provider's side.

Fix:

  • Log in to the provider's dashboard
  • Confirm the API key is still active
  • Generate a new API key if needed
  • Update it in MCPBundles credential panel
  • Validate again

4. Rate limit or temporary block​

The provider is temporarily blocking requests.

Fix:

  • Wait 5-10 minutes
  • Try validating again with the same validation tool
  • If it persists, open the provider's status page
  • Try a different validation tool (might use a different API endpoint)

5. Wrong Account (OAuth)​

You connected OAuth with the wrong account.

Fix:

  • In the credential panel, click "Connect with [Provider]" again to re-authenticate
  • Log in with the correct account
  • After OAuth completes, validate the credential

"Scope mismatch" error when using tool​

Symptom: Tool works in test, but when AI calls it you get "scope mismatch" error

Cause: Your OAuth token is missing required scopes.

Fix:

  1. Go to Settings → Credentials
  2. Find the provider
  3. Scroll to the "Credentials" section
  4. Click "Edit" on the credential card
  5. In the credential panel, click "Connect with [Provider]" again
  6. Approve all permissions in the OAuth flow
  7. Complete the flow
  8. Re-validate the credential
  9. Try the tool again

Example: Smartlead might ask for:

  • Read campaigns
  • Write campaigns
  • Read leads
  • Write leads

You must approve ALL of them, not just "Read campaigns."

Tool execution issues​

Tool call fails with "401 Unauthorized"​

Symptom: AI tries to call a tool → gets error "401 Unauthorized"

Cause: Credentials are invalid or expired.

Fix:

  1. Go to Settings → Credentials
  2. Find the provider for that tool
  3. Confirm status is "Verified"
  4. If not, reconnect/reverify credentials
  5. For OAuth: tokens might have expired—reconnect
  6. For API keys: generate a new one

Tool call fails with "404 Not Found"​

Symptom: Tool exists but returns 404 when called

Possible Causes:

1. Provider API changed​

The external API endpoint changed.

Fix:

  • Platform-side fix
  • Reach MCPBundles support
  • We'll update the tool definition

2. Resource doesn't exist​

You're trying to access something that doesn't exist (e.g., campaign ID 999 doesn't exist).

Fix:

  • Use list_campaigns first to see available IDs
  • Pass a valid ID to the tool

Tool call fails with "Rate limit exceeded"​

Symptom: Tool works sometimes, then fails with "429 Too Many Requests"

Cause: The external API has rate limits (e.g., 100 requests/hour).

Fix:

  • Wait for the rate limit to reset (often about 1 hour)
  • Reduce how often you call tools
  • Read the provider's documentation for limits
  • Consider upgrading your plan with the provider (not MCPBundles)

Note: MCPBundles doesn't add its own rate limits—these come from external API providers.

Tool returns empty results​

Symptom: Tool runs successfully but returns [] or empty data

Possible Causes:

1. No data exists​

There's actually nothing to return.

Example: list_campaigns returns [] if you have no campaigns.

Fix: Create some data in the provider's app first.

2. Filters too restrictive​

Your query filters out everything.

Example: list_campaigns(status="paused") returns [] if all campaigns are active.

Fix: Try without filters or use different filter values.

3. Wrong account​

You're connected to a different account than expected.

Fix:

  • Open Settings → Credentials
  • See which account is connected
  • Reconnect with the correct account if needed

AI platform issues​

ChatGPT won't load MCP URL​

Symptom: Added MCP URL in ChatGPT settings → nothing happens

Fix:

  1. Confirm ChatGPT Plus or Team (MCP requires paid plan)
  2. Go to Settings → Apps → Advanced settings
  3. Enable Developer mode
  4. Click "Create app"
  5. Paste the full URL including https:// in the MCP Server URL field
  6. Select OAuth for Authentication
  7. Confirm "I understand and want to continue"
  8. Click "Connect"
  9. Wait 10-20 seconds for validation
  10. If it fails, copy the URL again (might have extra spaces)

See ChatGPT Integration Guide for detailed steps.

Cursor can't find MCP settings​

Symptom: Can't find where to add MCP URL in Cursor

Fix:

  1. Cursor 0.40+ (update if needed)
  2. Settings → Features → MCP
  3. If "MCP" is missing, update Cursor
  4. Add URL in the MCP servers section

See Cursor Integration Guide for detailed steps.

Claude Desktop says "Server not responding"​

Symptom: Added MCP URL to config file → Claude says server not responding

Fix:

  1. Config must be valid JSON
  2. Put the URL in quotes
  3. Restart Claude Desktop completely
  4. Confirm the URL opens in a browser (if applicable)

See Claude Desktop Integration Guide for config examples.

General debugging steps​

If you're stuck, try these in order:

1. MCP server status​

  • MCP Servers → [your MCP server]
  • "Ready" with "Credentials valid"? If not, fix credentials first

2. Provider status​

  • Settings → Credentials
  • All needed providers Verified? If not, reconnect

3. Restart your AI​

  • Quit completely (not just close window)
  • Reopen
  • Wait 30 seconds

4. Try a different tool​

  • If one tool fails, try another from the same MCP server
  • Helps isolate tool-specific vs MCP-server–wide issues

5. Provider's website​

  • Log in to the external service (Smartlead, GitHub, etc.)
  • Confirm data exists
  • Confirm API key/account is active

6. Test in Dashboard​

  • Some MCP servers have a "Test" action
  • Run the tool directly in MCPBundles to bypass the AI client

Error messages reference​

"Bundle not found" / MCP URL invalid​

Cause: The slug in /bundle/{slug} is wrong or the MCP server was deleted.
Fix: Copy a fresh MCP URL from MCP Servers.

"Authentication required"​

Cause: Provider credentials are missing or invalid.
Fix: Connect/verify credentials in Settings → Credentials.

"Provider verification failed"​

Cause: Credentials are wrong or don't have proper permissions.
Fix: Re-enter API keys or redo OAuth with all scopes.

"Tool not found in bundle"​

Cause: Tool doesn't exist on this MCP server (some errors still say "bundle").
Fix: Open the MCP server's tool list in the dashboard — the AI may be using the wrong tool name.

"Insufficient permissions"​

Cause: OAuth token lacks required scopes.
Fix: Reconnect provider and approve all permissions.

"Provider API error"​

Cause: External API returned an error.
Fix: Read the details — rate limit, bad parameters, or provider downtime.

"Invalid tool arguments"​

Cause: AI called with wrong parameter types or values.
Fix: Read tool documentation for correct formats — often prompts need tightening.

Still having issues?​

Contact Support:

  • Email: help@mcpbundles.com
  • Include:
    • MCP server name or ID / slug used in MCP URL
    • Provider name
    • Tool name (if specific to one tool)
    • Error message (exact text)
    • Steps already attempted

Check the FAQ:

Browse the docs: