Skip to main content

Validating Credentials

Credential validation happens automatically in MCPBundles. When you add credentials to a provider, the system automatically tests them to ensure they work correctly.

How Validation Works​

MCPBundles validates credentials automatically in the background:

✅ Automatic testing - System runs validation tests immediately after you add credentials
✅ Real API calls - Uses actual provider APIs to verify credentials work
✅ Smart tool selection - Automatically chooses safe, reliable validation tools
✅ Status updates - Credentials show VERIFIED or ERROR status automatically
✅ No manual steps - You don't need to select tools or click validate buttons

What happens automatically:

  • API keys are tested with read-only API calls
  • OAuth tokens are validated with provider APIs
  • Database connections are tested with simple queries
  • Status updates to show if credentials work

Without valid credentials:

  • Tools won't appear in your AI
  • Bundles show "Setup Required" status
  • You'll discover credential issues later when tools fail

With valid credentials:

  • All tools become immediately available
  • Bundles show "Ready - Credentials valid" status
  • Everything works seamlessly

The Validation Process​

Automatic Validation​

Credential validation happens automatically - no manual steps required:

  1. Add Credential → Enter API key or complete OAuth
  2. Automatic Validation → System tests credentials in the background
  3. Status Update → Credentials show VERIFIED or ERROR status

Credential Setup Flow

How it works: When you save a credential, MCPBundles automatically selects and runs an appropriate validation tool to test your credentials with real API calls.

Adding Credentials​

You can add credentials from several places:

  • Bundle Page → Click "Configure" next to a provider → Click "+ Add New Credential"
  • Provider Detail Page → Click "Add Credential"
  • Add Tool Dialog → When selecting tools, click "+ Add New Credential"

All paths open the credential panel where you enter your credentials.

API Key Credentials​

Example: Smartlead, OpenAI, HubSpot

  1. Credential panel opens on the right side
  2. Get your API key from the provider's website (Settings → API Keys)
  3. Paste the API key into the credential panel field
  4. (Optional) Enter a descriptive Credential Name (e.g., "Production Account")
  5. Fill any other required fields (like Instance URL for HubSpot)
  6. Click "Create Credential"

Result:

  • ✅ Credential is saved successfully
  • 🎯 Automatic validation begins immediately
  • Status shows "VERIFIED" or "ERROR" automatically

OAuth Credentials​

Example: GitHub, Slack, Sentry, Google

  1. Credential panel opens on the right side
  2. (Optional) Enter a descriptive Credential Name (e.g., "Work GitHub", "Production Sentry")
  3. Click the large blue "Connect with [Provider]" button
  4. OAuth window opens → Log in to the provider
  5. Review and approve the requested permissions (scopes)
  6. Click "Allow" or "Authorize"
  7. OAuth window closes → You return to the credential panel

Result:

  • ✅ OAuth token is saved successfully
  • 🎯 Automatic validation begins immediately
  • Status shows "VERIFIED" or "ERROR" automatically

Key Feature: The credential panel automatically reopens after OAuth and validation happens seamlessly.

Public APIs (No Auth)​

Example: OpenWeatherMap free tier, NASA API

These providers don't require authentication. A connection record is created automatically and validated immediately.

What Happens During Automatic Validation​

When you save credentials, MCPBundles automatically:

1. Selects a Validation Tool​

The system automatically chooses the best validation tool for your provider:

Smart selection criteria:

  • ✅ Read-only operations (list, get, fetch)
  • ✅ No required parameters
  • ✅ Quick to execute (< 2 seconds)
  • ✅ Don't modify data
  • ✅ Reliable for testing

Examples of tools automatically selected:

  • get_user - Gets your account information
  • list_campaigns - Lists your campaigns
  • get_account_info - Retrieves account details
  • list_projects - Lists available projects

2. Runs the Validation Test​

The system makes a real API call to test your credentials:

For API Keys:

  • Injects your API key into the request
  • Calls a read-only endpoint
  • Verifies the response is successful

For OAuth:

  • Uses your access token
  • Tests the granted scopes
  • Confirms token is valid

For Database connections:

  • Tests the connection string
  • Runs a simple query (like SELECT 1)
  • Verifies connection works

3. Updates Status Automatically​

Based on the API response:

✅ VERIFIED - Credentials work correctly

  • Green checkmark badge
  • Tools become available immediately
  • Bundle status updates to "Ready"

❌ ERROR - Validation failed

  • Red error badge
  • Shows specific error message
  • Tools remain unavailable
  • Clear troubleshooting guidance provided

Understanding Validation Results​

After adding credentials, you'll see one of these status updates:

✅ VERIFIED Status​

What you'll see:

  • Green checkmark badge with "VERIFIED"
  • Success message: "Credentials validated successfully"
  • Timestamp showing when validation occurred
  • All tools for this provider become available immediately

What this means:

  • Your credentials are correct and working
  • API connectivity is confirmed
  • OAuth scopes are sufficient (if applicable)
  • Tools can now be used in bundles and AI integrations

❌ ERROR Status​

What you'll see:

  • Red X badge with "ERROR"
  • Specific error message explaining the problem
  • Clear troubleshooting suggestions
  • Tools remain unavailable until fixed

Common error messages:

"Invalid API key"

  • Your API key is incorrect or expired
  • Check for typos when copying
  • Generate a new key from the provider

"Authentication failed"

  • OAuth token is invalid or expired
  • Re-authorize with the provider
  • Check if you approved the correct scopes

"Connection failed"

  • Provider API is temporarily unavailable
  • Network connectivity issues
  • Try again in a few minutes

"Insufficient permissions"

  • OAuth token lacks required scopes
  • Re-authorize and approve all requested permissions
  • API key may need higher access level

Advanced: Manual Validation (Rare Cases)​

In rare cases where automatic validation fails, you can manually validate credentials:

When Manual Validation is Needed​

  • Automatic validation repeatedly fails
  • You suspect a specific validation issue
  • You want to test with a different validation method
  • Debugging complex credential problems

Manual Validation Process​

  1. Go to the credential card
  2. Click "Re-validate" button
  3. The system will automatically retry validation
  4. Check the updated status and any error messages

Changing Validation Method (Advanced)​

For troubleshooting, you can change which validation method is used:

  1. Click "Change Tool" on the credential card
  2. Select a different validation tool from the list
  3. Configure any required parameters
  4. Click "Validate Now" to test with the new method

Note: Manual validation is rarely needed. Most credential issues are resolved by checking your API key or re-authorizing OAuth.

After Adding Credentials​

Once you add credentials successfully:

✅ VERIFIED Credentials Activate Everything

  • Green checkmark badge appears
  • Status shows "VERIFIED"
  • All tools for this provider become available immediately
  • Bundles update to "Ready - Credentials valid" status

📦 Bundle Impact:

  • Provider shows "Verified" badge (green)
  • Bundle readiness recalculates automatically
  • "Setup Required" status may change to "Ready"
  • AI integrations can now use the tools

🎯 Tools Are Ready:

  • All provider tools appear in your AI
  • Can be tested in Bundle Studio
  • Available in bundle configurations
  • Work immediately in AI conversations

Managing Credentials Later​

Re-validation:

  • Click "Re-validate" if tools stop working
  • System automatically tests credentials again
  • Useful after API key rotation or OAuth expiry

Editing Credentials:

  • Update API keys when they expire
  • Change credential names for organization
  • Modify database connection details
  • Re-authorize OAuth tokens

Multiple Credentials:

  • Have different credentials for dev/prod environments
  • Use separate accounts for different projects
  • Switch credentials per bundle if needed

Credential Status Reference​

Status Badges Explained​

🟡 UNVERIFIED (Yellow/Amber) - Rare

  • What it means: Credential saved but automatic validation is pending or failed
  • Next action: Wait for automatic validation, or click "Re-validate"
  • Tools status: Unavailable until verified
  • Cause: Usually temporary during credential setup

🟢 VERIFIED (Green)

  • What it means: Credentials automatically validated and working
  • Next action: None required - ready to use!
  • Tools status: All tools available
  • Buttons: "Re-validate" (optional), "Edit" (optional)

🔴 ERROR (Red)

  • What it means: Automatic validation failed
  • Next action: Fix the credential (check API key, re-authorize OAuth)
  • Tools status: Unavailable until fixed
  • Buttons: "Re-validate", "Edit", "Re-authorize"

Troubleshooting Failed Validation​

When automatic validation fails, here's how to fix common issues:

Invalid API Key​

Symptoms: "Authentication failed: Invalid API key"

Causes:

  • Typo when copying the key
  • API key expired or revoked
  • Wrong environment (dev vs prod key)

Solutions:

  1. Double-check the API key in your provider's dashboard
  2. Generate a new key if expired
  3. Click "Edit" on the credential and update the key
  4. The system will automatically re-validate

OAuth Token Issues​

Symptoms: "Authorization failed" or "Token expired"

Causes:

  • OAuth token expired (tokens auto-refresh, but this can fail)
  • Insufficient permissions/scopes granted
  • Provider revoked access

Solutions:

  1. Click "Re-authorize" on the credential
  2. Complete the OAuth flow again
  3. Ensure you approve ALL requested permissions
  4. Credentials will validate automatically

Network/Connectivity Issues​

Symptoms: "Connection failed" or "Service unavailable"

Causes:

  • Provider API is temporarily unavailable
  • Network connectivity problems
  • Firewall blocking requests

Solutions:

  1. Wait 5-10 minutes and try "Re-validate"
  2. Check the provider's status page
  3. Verify your internet connection
  4. Contact support if the issue persists

Account/Access Issues​

Symptoms: "Access denied" or "Insufficient permissions"

Causes:

  • Wrong account used for OAuth
  • Account doesn't have required access level
  • API key lacks necessary permissions

Solutions:

  1. Verify you're using the correct account
  2. Check account permissions in the provider
  3. Create new credentials with proper access
  4. Contact your account admin if needed

Best Practices​

Monitor Status Automatically​

Since validation happens automatically, focus on monitoring:

  • Check credential status in bundle and provider views
  • Watch for ERROR badges that need attention
  • Re-validate periodically for important credentials
  • Update credentials when API keys expire

Keep Credentials Current​

  • Rotate API keys when they expire
  • Re-authorize OAuth when scopes change
  • Update database credentials when connections change
  • Test after updates by clicking "Re-validate"

Handle Multiple Environments​

For teams with multiple environments:

  • Use descriptive names like "Production API" vs "Staging API"
  • Separate credentials for different accounts
  • Test thoroughly in each environment
  • Document access for team members

Visual Status Reference​

┌─────────────────────────────────────────────────────────────┐
│ 1. ADD CREDENTIAL                                           │
│                                                             │
│ [API Key Field]                                             │
│ [Create Credential Button]                                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
            (Automatic Validation)
                          ↓
          ┌───────────────┴───────────────┐
          │                               │
       SUCCESS                         FAILURE
          │                               │
          ↓                               ↓
┌─────────────────┐            ┌─────────────────┐
│ VERIFIED        │            │ ERROR           │
│ ✅ Green badge  │            │ ❌ Red badge    │
│ Tools available │            │ Tools disabled  │
│ Ready to use    │            │ Fix required    │
└─────────────────┘            └─────────────────┘

What's Next?​

After adding credentials successfully:

1. Use Your Bundles​

Bundles with verified credentials show "Ready" status and can be used immediately.

2. Test in Bundle Studio​

Use Bundle Studio to test tools interactively.

3. Connect to AI​

Follow integration guides to use bundles in your AI applications.

4. Monitor Health​

Check credential status periodically to ensure everything stays working.

Need Help?​

  • Credential issues? Check the troubleshooting section above
  • Questions? Browse the sidebar for more guides
  • Support: Email help@mcpbundles.com

Note: Credential validation is now fully automated. You don't need to manually select validation tools or click "Validate Now" buttons. Just add your credentials and MCPBundles handles the rest!

Visual Guide to Status Flow​

┌─────────────────────────────────────────────────────────────┐
│ 1. ADD CREDENTIAL                                           │
│                                                             │
│ [API Key Input Field]                                       │
│ [Create Credential Button]                                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ UNVERIFIED - CHOOSE A VALIDATION TOOL                       │
│ Select a tool to test this credential                       │
│                                                             │
│ [ Choose Validation Tool ]  ← Click this                    │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ VALIDATION TOOL PICKER                                      │
│                                                             │
│ • list_campaigns       [Use as validator]                   │
│ • get_account_info     [Use as validator]  ← Click one      │
│ • list_contacts        [Use as validator]                   │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│ UNVERIFIED - READY TO VALIDATE                              │
│ Click validate to test this credential                      │
│                                                             │
│ Validation Tool: List Campaigns                             │
│                                                             │
│ [VALIDATE NOW]  ← Click this big green button               │
└─────────────────────────────────────────────────────────────┘
                          ↓
                   (Running...)
                          ↓
          ┌───────────────┴───────────────┐
          │                               │
       SUCCESS                         FAILURE
          │                               │
          ↓                               ↓
┌─────────────────────────┐  ┌─────────────────────────┐
│ VERIFIED                │  │ ERROR                    │
│ Just validated          │  │ Validation failed        │
│                         │  │                          │
│ Successfully            │  │ Validation Failed        │
│ Validated!              │  │                          │
│                         │  │ [Error details here]     │
│ Credential is working   │  │                          │
│ correctly               │  │ [VALIDATE NOW]           │
│                         │  │ (try again)              │
│ [Re-validate]           │  └─────────────────────────┘
│ [Change Tool]           │
└─────────────────────────┘

What's Next?​

After validating credentials:

1. Enable Bundles​

Go to Dashboard → Bundles and enable bundles that use your verified providers.

2. Test in Bundle Studio​

Use Bundle Studio to test tools interactively before adding to your AI.

3. Add to Your AI​

Follow integration guides to connect bundles to ChatGPT, Claude, Cursor, etc.

4. Monitor Status​

Check Dashboard → Providers regularly to ensure credentials stay verified.

Need Help?​

  • Email: help@mcpbundles.com
  • Docs: Browse sidebar for more guides
  • Support: Contact us with validation issues

Validation is quick and ensures everything works. Happy validating!