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 "Blocked" status
  • You can't test or use tools

With valid credentials:

  • All tools become immediately available
  • Bundles show "Operational" 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​

Dashboard Overview

Step 1: Navigate to Providers​

  1. Go to Dashboard
  2. Click Providers in the left navigation
  3. Browse or search for the provider you need

Step 2: Open Provider Details​

  1. Click on a provider card
  2. You'll see the provider detail page

Provider Without Credentials

Step 3: Add Credential​

Click the "Add Credential" button. What happens next depends on the credential type:

  • API Key → Form appears with fields to fill
  • OAuth → Popup opens for authorization
  • None → Connection created immediately

Adding API Key Credentials​

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

Example: Single-Field Credential (Resend)​

When you add a Resend credential, you'll see:

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. Click "Add Credential"
  2. Paste your API key from Resend dashboard
  3. (Optional) Click eye icon to verify it's correct
  4. Click "Create Credential"

Result: Credential saved with "UNVERIFIED" status (needs validation).

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. No need to copy/paste anything!

How OAuth Works​

  1. You click "Add Credential" → Modal opens
  2. Click "Connect with OAuth" → Popup window opens
  3. Log in to provider → Use your account credentials
  4. Review permissions → See what access is requested
  5. Click "Allow" → Authorize MCPBundles
  6. Popup closes → Token is saved automatically

Provider With Verified Credential

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​

Edit Credential Modal - Masked Values

Step 1: Choose a Validation Tool​

After creating a credential, you'll see:

Status Badge: UNVERIFIED - CHOOSE A VALIDATION TOOL

  1. Click "Choose Validation Tool" button
  2. A picker shows all available tools for this provider
  3. Select a simple, safe tool (usually a list/fetch operation)

Validation Tool Picker

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

Avoid validation tools that:

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

Step 2: Configure Validation Arguments (If Needed)​

Some tools require parameters to run:

Example: get_campaign needs campaign_id

  1. After selecting the tool, click "Configure Arguments"
  2. Fill in required parameters
  3. Use test data or IDs you know exist
  4. Click "Save Arguments"

Most list/fetch tools don't need parameters.

Step 3: Run Validation​

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

Three possible outcomes:

VERIFIED - CREDENTIAL VALIDATED

  • Green badge, checkmark icon
  • Credential works perfectly
  • All tools are now available

UNVERIFIED - NEEDS VALIDATION

  • Yellow badge, warning icon
  • Haven't validated yet
  • Choose a validation tool and run it

ERROR - VALIDATION FAILED

  • Red badge, X icon
  • Something went wrong
  • Check error message for details

Re-Validating Credentials​

Credentials should be re-validated when:

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

How to re-validate:

  1. Go to Provider detail page
  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

  1. Go to Provider detail page
  2. Find your credential card
  3. Click the Edit button (pencil icon)
  4. Edit modal opens showing:
    • Masked values - Sensitive data shown as ●●●●●●●●last4
    • Show button - Click to reveal full value
    • Form fields - Edit any field
  5. Make changes
  6. Click "Update Credential"

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. Delete the old credential (or click "Reconnect")
  2. Go through OAuth flow again with new account
  3. Validate the new credential

Changing Validation Tool​

You can change which tool validates your credential:

  1. Click "Edit" on credential card
  2. Click "Choose Different Validation Tool"
  3. Select a new tool from the picker
  4. (Optional) Configure arguments
  5. Click "Save"
  6. 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 the Provider detail page, you'll 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​

When a bundle uses a provider with multiple credentials, MCPBundles uses:

  1. The first VERIFIED credential found
  2. If none verified, uses first UNVERIFIED
  3. ERROR credentials are skipped

Best practice: Keep only one VERIFIED credential per provider (unless you need 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​

  1. Go to Provider detail page
  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" 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?​