Skip to main content

Managing Credentials

Provider credentials are the authentication keys, tokens, or OAuth connections that allow MCPBundles to access external APIs on your behalf. This guide covers everything you need to know about creating, editing, validating, and managing credentials.

What Are Credentials?​

Credentials are encrypted authentication information that MCPBundles uses to connect to external service providers like Resend, Google, Slack, or PostgreSQL. Each credential is:

  • User-specific - Only you can access your credentials
  • Encrypted at rest - All credential data is encrypted in the database
  • Provider-scoped - Each credential belongs to one provider
  • Validation-ready - Can be tested with validation tools

Credential Types​

MCPBundles supports four credential types:

TypeDescriptionExample Providers
API CredentialsSimple API key authenticationResend, OpenAI, HubSpot
OAuth 2.0OAuth 2.0 with automatic refreshGoogle, Slack, GitHub
OAuth 1.0OAuth 1.0 authentication flowTwitter, some legacy APIs
No AuthenticationPublic APIs requiring no credentialsWeather services, public data APIs

Creating Credentials​

Overview​

You can create credentials from multiple entry points, all opening the credential panel on the right side of your screen:

From Bundle Page:

  1. Click "Configure" next to a provider that needs credentials
  2. In the dialog, click "+ Add New Credential"
  3. Credential panel slides in from the right

From Provider Detail Page:

  1. Navigate to Dashboard → Providers → Select provider
  2. Click "Add Credential" button
  3. Credential panel opens

From Add Tool Dialog:

  1. While adding tools to a bundle, select a provider
  2. Click "+ Add New" to create a credential
  3. Credential panel opens

Key Feature: The credential panel stays open throughout the entire process, even during OAuth flows. You won't lose your place!

Credential Panel

API Key Credentials​

For providers that use API keys (like Resend, OpenAI, Smartlead):

Schema-Driven Credentials​

Modern providers use credential schemas that define multiple fields with types, validation, and help text.

Provider without credentials

Example: Resend Provider

When you click "Add Credential" on the Resend provider, you'll see a form with:

  • API Key (required, password type)
    • Description: "Your Resend API Key. Get it from https://resend.com/api-keys"
    • Input: Password field with show/hide toggle
    • Masked when saved: Shows ●●●●●●●●last4

How schema-driven credentials work:

The provider's credential_schema defines the fields:

{
  "fields": {
    "api_key": {
      "type": "password",
      "label": "API Key",
      "required": true,
      "description": "Your Resend API Key. Get it from https://resend.com/api-keys",
      "placeholder": "re_..."
    }
  }
}

The UI automatically generates:

  • Appropriate input type (text, password, number, select)
  • Show/hide toggle for password fields
  • Required field indicators (*)
  • Help text from descriptions
  • Default values

Multi-field credentials:

Some providers require multiple fields:

{
  "fields": {
    "host": {
      "type": "string",
      "label": "Database Host",
      "required": true,
      "placeholder": "localhost"
    },
    "port": {
      "type": "number",
      "label": "Port",
      "required": true,
      "default": 5432
    },
    "database": {
      "type": "string",
      "label": "Database Name",
      "required": true
    },
    "user": {
      "type": "string",
      "label": "Username",
      "required": true
    },
    "password": {
      "type": "password",
      "label": "Password",
      "required": true
    }
  }
}

This creates a comprehensive form with all necessary database connection parameters.

Steps:

  1. Credential panel opens on the right side
  2. Fill in all required fields (marked with *)
  3. (Optional) Enter a Credential Name (e.g., "Production Database", "Staging API")
  4. Click "Create Credential"
  5. 🎯 Automatic validation begins - System selects and runs an appropriate validation tool
  6. Success! Status changes to VERIFIED and tools become available

What happens automatically:

  • System chooses the best validation tool for your provider
  • Runs a test API call using your credentials
  • Updates credential status based on results
  • No manual selection required for most providers

Field Types​

The schema system supports various field types:

TypeInputExample
stringText inputEmail addresses, URLs
passwordPassword input with toggleAPI keys, passwords
number / integerNumber inputPorts, timeouts
selectDropdownRegions, environments
booleanCheckboxEnable features

OAuth2 Credentials​

For providers that use OAuth (like GitHub, Slack, Sentry, Google):

OAuth Credential Panel

OAuth Flow:

  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. Automatic endpoint discovery happens in the background:
    • System discovers OAuth authorization endpoint
    • System discovers token endpoint
    • System discovers registration endpoint (if available)
  5. OAuth window opens → Provider's authorization page loads
  6. Log in to your provider account
  7. Review and approve the requested scopes/permissions
  8. OAuth window closes → Browser returns to MCPBundles
  9. 🎯 Credential panel automatically reopens (context-aware return!)
  10. 🎯 Automatic validation begins - System validates OAuth credentials
  11. Success! Status changes to VERIFIED and tools become available

Validation Tool Picker

Key OAuth Features:

  • Context-Aware Return - Panel reopens exactly where you left off after OAuth
  • PKCE Support - Secure authorization flow (prevents interception)
  • Dynamic Client Registration - Automatic OAuth app creation when supported
  • Automatic Token Refresh - Background refresh before expiration
  • Scope Management - Shows granted scopes on credential card
  • No Page Redirect - Stay on the same page throughout OAuth flow

What happens automatically: OAuth credentials are validated immediately after creation using provider-appropriate test calls. Most OAuth providers work without manual validation tool selection.

None Credentials​

For providers that don't require authentication:

  1. Click "Create Connection & Test"
  2. Empty credential record is created
  3. Choose validation tool
  4. Validate to confirm provider is reachable

This creates a connection record for tracking purposes, even though no actual credentials are stored.

Understanding Credential Status​

Verification Status​

Every credential has a verification status that indicates whether it's been tested:

Provider detail with verified credential

VERIFIED​

Appearance:

  • Green background on credential card
  • Large checkmark icon
  • "VERIFIED" text prominently displayed
  • Shows last validation time

What it means:

  • Credential was successfully tested with a validation tool
  • API is reachable and accepting authentication
  • Tools using this provider are available
  • Bundles using this provider can function properly

Actions available:

  • Re-validate - Test again to confirm still working
  • Change Tool - Select different validation tool
  • Edit - Update credential values

UNVERIFIED​

Appearance:

  • Amber/yellow background
  • Warning icon
  • "UNVERIFIED" text
  • Call-to-action to validate

What it means:

  • Credential exists but validation failed or is pending
  • Automatic validation didn't complete successfully
  • Tools using this provider are hidden
  • Bundles show "Setup Required" status

Next steps:

  1. Click "Re-validate" on the credential card
  2. System will automatically retry validation
  3. If still failing, check credential values or contact support

ERROR​

Appearance:

  • Red background
  • Error icon
  • "ERROR" text
  • Error message details

What it means:

  • Validation test failed
  • Credential may be invalid, expired, or revoked
  • API may be unreachable
  • Tools won't work

Troubleshooting:

  1. Check error message for specific issue
  2. Verify credential is correct
  3. Check if API key was rotated
  4. Try different validation tool
  5. Re-authorize if OAuth
  6. Contact provider support if persistent

Credential Activity Status​

Beyond verification, credentials have an activity status:

StatusMeaningActions
ACTIVEReady to useCan validate, can be used by tools
DISABLEDTemporarily inactiveCan re-enable
EXPIREDOAuth token expiredRe-authorize needed

Editing Credentials​

Editing Existing Credentials​

Edit credential modal with masked value

When you edit an existing credential, you'll see:

Masked Current Values:

  • Shows ●●●●●●●●last4 for each field
  • Green checkmark: "✓ Currently set: ●●●●●●●●JGhm"
  • Confirms credential exists without exposing full value

Selective Updates:

  • Leave fields blank to keep current values
  • Only enter new values for fields you want to change
  • Placeholder text: "Leave blank to keep current, or enter new value"

How it works:

When you save, the system:

  1. Checks which fields have new values (non-empty)
  2. Merges new values with existing encrypted data
  3. Re-encrypts the combined credential
  4. Preserves unchanged fields

Example:

Original credential:

{
  "api_key": "re_abc123xyz789",
  "instance_url": "https://company.example.com"
}

Edit form shows:

  • API Key: ✓ Currently set: ●●●●●●●●x789
  • Instance URL: ✓ Currently set: ●●●●●●●●e.com

User enters:

  • API Key: re_new_key_456 (changing)
  • Instance URL: `` (blank - keeping current)

Result:

{
  "api_key": "re_new_key_456",
  "instance_url": "https://company.example.com"
}

When to Edit Credentials​

Edit credentials when:

  • API key was rotated
  • Password changed
  • Moving between environments (dev → prod)
  • Correcting a typo
  • Updating instance URL

Don't edit if:

  • OAuth token expired - use "Re-authorize" instead
  • Completely changing provider account - create new credential
  • Testing different keys - create additional credential

Validation Tools​

Automatic Validation​

MCPBundles now automatically validates credentials for most providers. When you create a credential:

  1. System selects the best validation tool for your provider
  2. Runs test API call using your new credentials
  3. Updates status to VERIFIED or ERROR automatically
  4. No manual intervention required

What happens in the background:

  • System analyzes provider configuration for validation tools
  • Chooses read-only tools that require minimal parameters
  • Executes test API calls safely
  • Updates credential verification status

When Manual Selection is Needed​

For some providers or advanced use cases, you may need to manually select validation tools:

  • Complex providers requiring specific parameters
  • Custom validation scenarios with particular test cases
  • Troubleshooting failed automatic validation

What is a Validation Tool?​

A validation tool is a read-only tool that tests your credential by making a real API call to the provider. If the call succeeds, your credential is verified.

Choosing a Validation Tool (Advanced)​

When manual selection is needed, choose tools that:

  • Require no input arguments (or all inputs are optional)
  • Are read-only (list, get, search operations)
  • Execute quickly
  • Work reliably for testing

Good validation tools:

  • list_campaigns - Lists your campaigns
  • get_account_info - Gets your account details
  • list_domains - Lists verified domains
  • get_user - Gets current user info

Avoid for validation:

  • Tools that create/delete resources
  • Tools that require specific IDs you don't have
  • Tools that modify data
  • Tools with many required arguments

Validation Tool Selection (Advanced)​

Provider-level vs Credential-level:

  • Provider-level default - Set on the provider for all users (automatic)
  • Credential-level override - Manually set on specific credentials

How to manually set:

  1. On credential card - Click "Change Tool" button
  2. Modal shows all available tools for the provider
  3. Select appropriate tool and configure parameters if needed

Validation Arguments​

Some validation tools require input parameters:

Example: Get Campaign Stats

  • Requires: campaign_id (string)
  • Optional: include_details (boolean)

Validation Parameters UI:

  • Appears after selecting a tool with required inputs
  • Click "Configure" to expand parameter form
  • Form auto-generated from tool's input schema
  • Shows required fields with *
  • Arguments are saved with credential for reuse

Saved validation args:

When you configure validation arguments, they're stored with the credential:

{
  "credential_id": "uuid",
  "validation_tool_id": "tool_uuid",
  "validation_args": {
    "campaign_id": "camp_123abc",
    "include_details": true
  }
}

These args are automatically used every time you click "Re-validate".

Manual Validation (Troubleshooting)​

While validation is usually automatic, you can manually re-validate credentials:

When to manually validate:

  • Automatic validation failed
  • You updated credential values
  • You suspect API issues
  • Tools stopped working unexpectedly

From credential card:

  1. Click "Re-validate" button
  2. System automatically selects and runs validation tool
  3. Status updates in real-time
  4. Result message appears

Advanced: Change validation tool

  1. Click "Change Tool" on credential card
  2. Select different validation tool if needed
  3. Configure parameters if required
  4. Click "Validate Now"

Validation process (automatic):

  1. System selects appropriate validation tool
  2. Injects your encrypted credential
  3. Calls the validation tool
  4. Tool makes API request to provider
  5. Returns success or failure
  6. Updates credential.verification_status

Success:

  • Status → VERIFIED
  • Green success message
  • Shows what was returned
  • Timestamp updated

Failure:

  • Status → ERROR
  • Red error message
  • Shows specific error
  • Suggests fixes

Credential Security​

Encryption​

At Rest:

  • All credential data encrypted with Fernet (symmetric encryption)
  • Encryption keys stored separately from database
  • Each user's credentials completely isolated

In Transit:

  • HTTPS for all API calls
  • Credentials never logged
  • Masked in UI displays
  • Never exposed in responses

Access Control​

User Isolation:

  • You can only access your own credentials
  • Database queries automatically scoped to your user ID
  • Admins cannot view your encrypted credentials
  • Shared bundles use each user's own credentials

Permissions:

  • Creating credentials - your own only
  • Reading credentials - masked view of your own
  • Updating credentials - your own only
  • Deleting credentials - your own only

OAuth Security​

PKCE (Proof Key for Code Exchange):

  • Secure authorization flow
  • Prevents authorization code interception
  • Required for public OAuth clients

Dynamic Client Registration:

  • Automatic OAuth app creation when supported
  • No manual app registration needed
  • Client secrets encrypted per-credential

Token Management:

  • Access tokens encrypted
  • Refresh tokens encrypted
  • Automatic refresh before expiration
  • Expired tokens trigger re-authorization

Credential Usage​

Tracking Usage​

Each credential tracks:

  • Last Used At - When last used by a tool
  • Usage Count - How many times executed
  • Used By Bundles - Which bundles reference it

Viewing usage:

On the credential card:

  • "Last Used: 13/10/2025"
  • "Used by 2 bundle(s)"
    • Shows bundle names with links
    • Click to view bundle details

Multiple Credentials​

Can you have multiple credentials per provider?

Yes, but only one can be active at a time:

Use cases:

  • Development vs Production keys
  • Multiple accounts (personal + business)
  • Testing new credentials before switching

How to switch:

  1. Add new credential
  2. Validate new credential
  3. Delete or disable old credential
  4. New credential becomes active

Binding to bundles:

When a bundle needs a provider:

  • If one VERIFIED credential exists → auto-binds
  • If multiple exist → manual selection required
  • If none exist → bundle shows "Setup Required"

Advanced Features​

Configurable Defaults​

Some providers support configurable defaults - pre-configured tool parameters that are automatically injected at runtime.

What Are Configurable Defaults?​

Configurable defaults let you set common parameters once at the credential level, instead of specifying them every time you use a tool.

Example: Database Connection

  • Set database: "production" in your PostgreSQL credential
  • All database tools automatically use the production database
  • No need to specify database parameter each time

Example: API Instance

  • Set instance_url: "https://mycompany.atlassian.net" in Jira credential
  • All Jira tools automatically connect to your instance
  • No need to specify instance URL each time

How It Works​

  1. Provider defines configurable parameters in its configuration
  2. You set default values when adding/editing credentials
  3. Parameters are hidden from tool schemas (already have defaults)
  4. Tools receive pre-configured values automatically at runtime

Setting Configurable Defaults​

During Credential Creation:

  1. Add credential as usual
  2. Look for "Default Configuration" section in credential panel
  3. Fill in common parameters (optional)
  4. Save credential

During Credential Editing:

  1. Edit existing credential
  2. Expand "Default Configuration" section
  3. Update parameter defaults
  4. Save changes

Benefits:

  • Convenience: Common parameters set once, used everywhere
  • Consistency: All tools use the same defaults
  • Safety: Reduces parameter errors
  • Customization: Different credentials can have different defaults

Which Providers Support It?​

Configurable defaults are available for providers that:

  • Connect to multiple instances (SaaS multi-tenancy)
  • Have database connections
  • Require common API parameters

Examples:

  • PostgreSQL/MySQL: host, port, database, schema
  • Salesforce/Jira: instance_url, api_version
  • HubSpot: portal_id, api_version

Contact support if you need configurable defaults for a specific provider.

Granted OAuth Scopes​

For OAuth2 credentials, view granted scopes:

Displays:

  • List of scope strings
  • Example: read:campaigns, write:contacts
  • Shows what permissions were actually granted

Scope mismatches:

If a tool needs write:campaigns but you only granted read:campaigns:

  • Tool shows "Insufficient Scopes" error
  • Solution: Re-authorize with broader scopes

Masked Credential Data​

When editing, credential data is masked:

Masking format:

  • Short values (≤4 chars): ●●●●
  • Longer values: ●●●●●●●●last4
  • Example: ●●●●●●●●JGhm for re_abc123JGhm

Purpose:

  • Confirm credential exists
  • Verify you're editing the right one
  • Don't expose full credential in UI

Expected Credential Fields​

Provider pages show required fields:

Expected Credential Fields Section:

  • Lists all fields the provider needs
  • Shows field names and types
  • Indicates required vs optional
  • Provides help text and links

This helps you:

  • Know what to prepare before adding credential
  • Understand what information is needed
  • Find where to get credentials from provider

Troubleshooting​

Common Issues​

"Validation failed: Invalid API key"​

Causes:

  • Typo when pasting
  • Key was deleted/revoked
  • Wrong provider account
  • Key hasn't been activated yet

Solutions:

  1. Re-copy API key from provider dashboard
  2. Verify key is for correct account/environment
  3. Check provider's API key settings
  4. Generate new key if needed
  5. Edit credential and paste new key

"OAuth token expired"​

Causes:

  • Token expired and auto-refresh failed
  • Provider revoked access
  • OAuth app was deleted

Solutions:

  1. Click "Re-authorize" on credential card
  2. Complete OAuth flow again
  3. New token is saved automatically
  4. Validate to confirm working

"Insufficient scopes"​

Causes:

  • Tool needs permissions you didn't grant
  • OAuth was authorized with minimal scopes

Solutions:

  1. Note which scopes are needed (in error message)
  2. Click "Re-authorize"
  3. Grant additional scopes when prompted
  4. Re-validate credential

"Validation tool requires arguments"​

Causes:

  • Selected tool needs input parameters
  • Required fields not filled

Solutions:

  1. Click "Configure" in Validation Parameters
  2. Fill required fields
  3. Arguments are saved for next time
  4. Click validate

Alternatively:

  1. Click "Change Tool"
  2. Select simpler tool without required args
  3. Validate with that tool instead

"Can't find credential value for field X"​

Causes:

  • Schema-driven field missing in saved data
  • Credential created before schema was defined
  • Field was removed from schema

Solutions:

  1. Edit credential
  2. Enter value for missing field
  3. Save to update credential data

Getting Help​

If you encounter issues not covered here:

  1. Check error message - Often contains specific fix
  2. Try different validation tool - May provide more detail
  3. Check provider status - API might be down
  4. Review provider docs - Verify credential format
  5. Contact support - help@mcpbundles.com

Best Practices​

Do​

  • Check verification status after creating credentials (usually automatic)
  • Re-validate manually if tools stop working
  • Update credentials when rotating API keys
  • Use descriptive names if provider supports named credentials
  • Monitor credential status in bundle and provider views
  • Use OAuth when available - more secure than API keys

Don't​

  • Don't share credentials between users (each user needs their own)
  • Don't use production keys in test/dev bundles
  • Don't ignore ERROR status - always troubleshoot failed credentials
  • Don't use destructive tools for manual validation
  • Don't hardcode credentials in tools - always use provider auth
  • Don't screenshot unmasked credentials - security risk

Need Help?​

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

Credentials are the foundation of tool execution in MCPBundles. With proper credential management, you can securely connect to any provider and unlock powerful AI-driven workflows.