Skip to main content

Setting Up Credentials

Credentials are the authentication keys and tokens that allow MCPBundles to access external APIs on your behalf. This guide covers everything from adding your first credential to advanced management.

Why Credentials Matter​

Before tools can access external services (like Resend, Google, Slack), you need to connect credentials. Without them:

  • Tools won't appear in your AI
  • Bundles show "Connection Error" status
  • You can't test or use tools

With valid credentials:

  • All tools become immediately available
  • Bundles show "Ready - Credentials valid" status
  • Your AI can perform real actions

Understanding Credential Types​

MCPBundles supports four authentication methods:

TypeDescriptionWhen It's Used
API KeySimple API key (copy/paste)Resend, OpenAI, HubSpot
OAuth 2.0Secure login flow (popup)Google, Slack, GitHub
Bearer TokenToken-based authSome payment processors
NoneNo authentication neededPublic APIs, weather services

Quick Start: Adding Your First Credential​

You can add credentials from multiple entry points in MCPBundles:

Option A: From Bundle Page (Recommended)​

When to use: Setting up a specific bundle's required providers

  1. Go to Dashboard → Bundles
  2. Click on a bundle that needs credentials
  3. Look for the "Configuration Required" section
  4. Click "Configure" next to a provider
  5. In the dialog, click "+ Add New Credential"
  6. Credential panel slides in from the right side of your screen

Bundle Credential Status

Option B: From Provider Page​

When to use: Adding credentials before choosing bundles

  1. Go to Dashboard → Providers
  2. Click on a provider card
  3. Click the "Add Credential" button
  4. Credential panel slides in from the right side

Provider Without Credentials

Option C: From Add Tool Dialog​

When to use: While customizing a bundle's tools

  1. In a bundle, click "+ Add Tool"
  2. Select a provider
  3. Click "+ Add New" to create a credential
  4. Credential panel slides in from the right side

What happens next depends on the credential type:

  • API Key → Fill in fields and click "Create Credential"
  • OAuth → Click OAuth button, authorize in popup window
  • None → Connection created automatically (no auth needed)

Adding API Key Credentials​

Modern providers use schema-driven credentials - the credential panel dynamically generates fields based on what the provider needs.

Credential Sidemenu

Example: Single-Field Credential (Resend)​

When you add a Resend credential in the credential panel:

API Key Field:

  • Label: "API Key"
  • Type: Password (with show/hide toggle)
  • Description: "Your Resend API Key. Get it from https://resend.com/api-keys"
  • Placeholder: re_...

Steps:

  1. Credential panel opens on the right side
  2. Paste your API key from Resend dashboard
  3. (Optional) Enter a Credential Name (e.g., "Production", "Staging")
  4. (Optional) Click eye icon to verify it's correct
  5. Click "Create Credential"
  6. 🎯 Validation tool picker automatically opens

Result: Credential saved with "UNVERIFIED" status. Select a validation tool and click "Validate Now" to test it!

Example: Multi-Field Credential (Database)​

Some providers require multiple fields:

PostgreSQL Credential Form:

  • Host - Database server address (e.g., localhost)
  • Port - Port number (default: 5432)
  • Database - Database name
  • Username - Database user
  • Password - User password (masked)

Steps:

  1. Fill in all required fields (marked with *)
  2. Optional fields can be left empty
  3. Click "Create Credential"

Where to Find API Keys​

Each provider has their own location:

Resend:

  1. Go to https://resend.com/api-keys
  2. Click "Create API Key"
  3. Copy the key immediately (only shown once)

OpenAI:

  1. Go to https://platform.openai.com/api-keys
  2. Click "Create new secret key"
  3. Copy and save immediately

HubSpot:

  1. Settings → Integrations → API Key
  2. Click "Show" or "Generate"
  3. Copy the key
tip

Always store API keys in a secure location (password manager) before pasting into MCPBundles.

Adding OAuth Credentials​

OAuth is the most secure authentication method. The credential panel stays open throughout the entire process!

OAuth Credential Flow

How OAuth Works (New Context-Aware Flow)​

  1. Credential panel opens on the right side
  2. (Optional) Enter a credential name (e.g., "Work GitHub", "Production Slack")
  3. Click "Connect with [Provider]" button
  4. OAuth window opens → Log in to provider
  5. Review permissions → See what access is requested
  6. Click "Allow" → Authorize MCPBundles
  7. OAuth window closes → You return to the bundle/provider page
  8. 🎯 Credential panel automatically reopens! (Context-aware return)
  9. 🎯 Validation tool picker automatically opens!
  10. Select a validation tool and click "Validate Now"

Key Feature: The credential panel remembers where you were and reopens automatically after OAuth completes. No need to navigate back!

Validation Tool Picker

Example: Connecting Google​

  1. Click "Add Credential" on Google provider
  2. Click "Authorize with Google"
  3. Popup opens → Select your Google account
  4. Review requested permissions:
    • View and manage Gmail
    • View and manage Calendar
    • View Drive files
  5. Click "Allow"
  6. Popup closes automatically
  7. Credential is saved and ready to validate

OAuth Scopes​

Scopes determine what your AI can access:

Read-only scopes:

  • View emails (Gmail)
  • Read calendar events
  • List repositories (GitHub)

Write scopes:

  • Send emails
  • Create calendar events
  • Create/update GitHub issues

Why scopes matter:

  • More specific permissions = more secure
  • Tools only work if required scopes are granted
  • You can revoke access anytime

Managing OAuth Tokens​

OAuth tokens are automatically refreshed by MCPBundles when they expire. You don't need to reconnect unless:

  • You explicitly revoke access in the provider's app
  • The provider changes their required scopes
  • The credential shows "ERROR" status

Validating Credentials​

After adding a credential, you must validate it to confirm it works.

Why Validate?​

Validation:

  • Confirms credentials are correct
  • Tests API connectivity
  • Checks permissions (OAuth scopes)
  • Activates tools
  • Prevents runtime errors

The Validation Process​

After creating a credential, the validation tool picker automatically opens:

Validation Tool Picker

Step 1: Choose a Validation Tool​

The picker opens automatically showing all available tools for this provider.

Status Badge shows: "UNVERIFIED" (yellow/amber)

  1. Look for "Recommended" badges - These tools are safe and simple
  2. Select a simple, safe tool (usually a list/fetch operation)
  3. Click "Use as validator" on your chosen tool

Examples of good validation tools:

  • list_campaigns (Smartlead) - Lists email campaigns
  • get_user (Google) - Gets your user profile
  • list_repos (GitHub) - Lists your repositories
  • fetch_account_info (Stripe) - Gets account details
  • analytics_links (Ayrshare) - Gets analytics data

Avoid validation tools that:

  • Create or delete data
  • Send emails or messages
  • Cost money (like SMS)
  • Require complex parameters

Step 2: Configure Validation Parameters (If Needed)​

Most validation tools don't need parameters, but some do:

Example: get_campaign needs campaign_id

  1. After selecting the tool, you'll see a "Validation Parameters" section
  2. Click "Configure" to open the parameter form
  3. Fill in required parameters (use test data or IDs you know exist)
  4. Click "Save"

Tip: Choose tools without parameters when possible - they're faster to validate!

Step 3: Run Validation​

After selecting a tool (and configuring parameters if needed):

Validate Now Button

  1. Click the large green "Validate Now" button
  2. System calls the validation tool with your credential
  3. Wait 1-3 seconds for results

Three possible outcomes:

✅ VERIFIED - CREDENTIAL VALIDATED

  • Green badge with checkmark icon
  • Credential works perfectly
  • All tools are now available
  • Panel may close automatically

🟡 UNVERIFIED - NEEDS VALIDATION

  • Yellow badge with warning icon
  • Haven't validated yet or validation tool not selected
  • Choose a validation tool and run it

❌ ERROR - VALIDATION FAILED

  • Red badge with X icon
  • Something went wrong (wrong API key, insufficient permissions, etc.)
  • Check error message for details
  • See Troubleshooting for common fixes

Re-Validating Credentials​

Credentials should be re-validated when:

  • You change the credential data
  • Provider API changes
  • Error status appears
  • Tools stop working unexpectedly

How to re-validate:

From Bundle Page:

  1. Go to your bundle
  2. Click "Edit" next to the provider credential
  3. Credential panel opens
  4. Click "Re-validate" button
  5. System runs the validation tool again

From Provider Page:

  1. Go to Dashboard → Providers → Select provider
  2. Find your credential card
  3. Click "Re-validate" button
  4. System runs the validation tool again

Editing Credentials​

You can edit credentials to:

  • Update API keys (after rotation)
  • Change multi-field values
  • Modify validation tool selection
  • Update validation arguments

Editing API Key Credentials​

Edit Credential Modal

From Bundle Page:

  1. Go to your bundle
  2. Find the provider in the Configuration section
  3. Click "Edit" next to the credential
  4. Credential panel slides in showing masked values
  5. Make your changes
  6. Click "Update Credential"
  7. Re-validate to confirm changes work

From Provider Page:

  1. Go to Dashboard → Providers → Select provider
  2. Find your credential card
  3. Click the "Edit" button (pencil icon)
  4. Credential panel opens showing:
    • Masked values - Sensitive data shown as ●●●●●●●●last4
    • Show button - Click eye icon to reveal full value
    • Form fields - Edit any field
  5. Make changes
  6. Click "Update Credential"
  7. Re-validate to confirm changes work

After editing:

  • Credential status becomes "UNVERIFIED"
  • You must re-validate to confirm changes work
warning

Always validate after editing to ensure the new credential data is correct!

Editing OAuth Credentials​

OAuth credentials cannot be edited directly. To change the connected account:

  1. Open the credential (Edit button)
  2. Click "Connect with [Provider]" again → Reauthorize with new account
  3. Credential panel reopens automatically after OAuth
  4. Validate the new credential to confirm it works

Changing Validation Tool​

You can change which tool validates your credential:

  1. Open the credential (Edit button)
  2. Click "Select Validation Tool" or "Change Tool"
  3. Validation tool picker opens
  4. Select a new tool from the list
  5. (Optional) Configure parameters if needed
  6. Click "Validate Now" to test with the new tool
  7. Run validation with the new tool

When to change validation tool:

  • Current validation tool is unreliable
  • Tool requires parameters you don't have
  • Want to test a different permission scope
  • Previous tool was deprecated

Managing Multiple Credentials​

You can have multiple credentials per provider for:

  • Different accounts - Personal vs work
  • Different environments - Staging vs production
  • Different permission scopes - Read-only vs full access
  • Team members - Each person's credentials

Viewing All Credentials​

On Bundle Page:

  • View credentials bound to specific providers for that bundle
  • See which credential is currently selected for each provider
  • Quick access to Edit, Change, or Unbind

On Provider Page: Go to Dashboard → Providers → Select provider to see:

  • All credentials listed as cards
  • Each shows:
    • Verification status (VERIFIED, UNVERIFIED, ERROR)
    • Masked credential data
    • Validation tool being used
    • Last validated timestamp
    • Edit and Delete buttons

Selecting Which Credential to Use​

On Bundle Page:

  1. Click "Configure" next to a provider
  2. Dialog shows all available credentials for that provider
  3. Select the credential you want to use
  4. Click "Save"

When a bundle uses a provider, MCPBundles prioritizes credentials in this order:

  1. The credential you explicitly selected for that bundle
  2. First VERIFIED credential if no selection made
  3. First UNVERIFIED credential if none verified
  4. ERROR credentials are skipped

Best practice: Explicitly select credentials for each bundle if you have multiple accounts.

Deleting Credentials​

When to delete a credential:

  • No longer using that provider
  • Credential was compromised
  • Switching to a different account
  • Testing is complete

How to Delete​

From Bundle Page:

  1. Go to your bundle
  2. Find the provider credential
  3. Click "Unbind" to remove from bundle (keeps credential)
  4. Or click "Edit" → "Delete Credential" to permanently delete

From Provider Page:

  1. Go to Dashboard → Providers → Select provider
  2. Find the credential card
  3. Click "Delete" button (trash icon)
  4. Confirm deletion in the modal
danger

Deletion is immediate and irreversible!

Deleting a credential:

  • Removes it from database permanently
  • Invalidates all bundles using it
  • Cannot be undone
  • Does NOT revoke OAuth tokens at the provider (do that separately)

Revoking OAuth Access​

After deleting an OAuth credential, also revoke access at the provider:

Google:

  1. Go to https://myaccount.google.com/permissions
  2. Find "MCPBundles"
  3. Click "Remove Access"

GitHub:

  1. Settings → Applications → Authorized OAuth Apps
  2. Find "MCPBundles"
  3. Click "Revoke"

Slack:

  1. Workspace Settings → Apps
  2. Find "MCPBundles"
  3. Click "Remove"

Security & Best Practices​

Credential Security​

MCPBundles takes security seriously:

Encryption:

  • All credentials encrypted at rest in database
  • Encryption keys stored separately
  • TLS for all API communications

Access Control:

  • Only you can access your credentials
  • Not visible to other users
  • Not shared between accounts

Masking:

  • Sensitive data shown as ●●●●●●●●last4
  • Full values never logged
  • UI requires explicit "Show" action

Best Practices​

DO:

  • Use OAuth whenever available (more secure than API keys)
  • Validate immediately after adding
  • Re-validate after making changes
  • Use minimal required scopes (read-only when possible)
  • Delete credentials you no longer need
  • Rotate API keys regularly
  • Keep API keys in a password manager

DON'T:

  • Share API keys with others
  • Commit API keys to version control
  • Use production credentials for testing
  • Grant more permissions than needed
  • Ignore ERROR status credentials
  • Leave unvalidated credentials

Troubleshooting​

"Validation Failed" Error​

Possible causes:

  1. Invalid API key

    • Fix: Double-check the key, copy again from provider
    • Ensure no extra spaces when pasting

  2. Insufficient permissions (OAuth)

    • Fix: Reconnect and approve ALL requested scopes
    • Check provider's app settings

  3. Provider API is down

    • Fix: Wait a few minutes and try again
    • Check provider's status page

  4. Rate limit exceeded

    • Fix: Wait 15-60 minutes
    • Choose a different validation tool

"Cannot connect to provider" Error​

Possible causes:

  1. Firewall blocking MCPBundles

    • Fix: Whitelist *.mcpbundles.com in your firewall

  2. Provider requires IP whitelisting

    • Fix: Add MCPBundles IPs to provider's allowlist
    • Contact support for IP addresses

  3. Provider endpoint changed

    • Fix: Re-add the credential
    • Contact support if issue persists

OAuth Popup Blocked​

Fix:

  1. Allow popups for mcpbundles.com in browser settings
  2. Click "Connect with [Provider]" again
  3. Popup should now open

"Scope mismatch" Error​

Cause: Provider requires different OAuth scopes than previously granted.

Fix:

  1. Delete the credential
  2. Add it again
  3. Approve ALL requested permissions in OAuth flow
  4. Validate

Credential Shows as "Expired"​

OAuth tokens: Automatically refreshed by MCPBundles. If you see "expired":

  1. Try re-validating (may trigger refresh)
  2. If still fails, reconnect OAuth

API keys: Don't expire unless provider rotates them. If not working:

  1. Generate new key from provider
  2. Edit credential and paste new key
  3. Validate

Next Steps​

Need Help?​