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:

Type	Description	Example Providers
API_KEY	Simple API key authentication	Resend, OpenAI, HubSpot
OAUTH2_TOKEN	OAuth 2.0 with automatic refresh	Google, Slack, GitHub
BEARER_TOKEN	Bearer token authentication	Some payment processors
NONE	No authentication required	Public APIs, weather services

Creating Credentials

Overview

The credential creation process varies based on the provider's authentication type:

1. Navigate to provider → Go to Dashboard → Providers → Select provider
2. Add credential → Click "Add Credential" button
3. Enter details → Fill in required fields (or connect OAuth)
4. Choose validator → Select a validation tool (optional)
5. Validate → Test the credential to verify it works

API Key Credentials

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

Schema-Driven Credentials

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

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.

Field Types

The schema system supports various field types:

Type	Input	Example
string	Text input	Email addresses, URLs
password	Password input with toggle	API keys, passwords
number / integer	Number input	Ports, timeouts
select	Dropdown	Regions, environments
boolean	Checkbox	Enable features

OAuth2 Credentials

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

OAuth Flow:

1. Click "Add Credential"
2. Select "OAuth2" as credential type (default for OAuth providers)
3. Click "Connect with [Provider]"
4. Automatic endpoint discovery happens in the background:
   • System discovers OAuth authorization endpoint
   • System discovers token endpoint
   • System discovers registration endpoint (if available)
5. Browser opens provider's authorization page
6. Log in and approve requested scopes
7. Browser redirects back to MCPBundles
8. Token is saved and encrypted automatically
9. Validation tool selection appears

Key OAuth Features:

• PKCE Support - Secure authorization flow
• Dynamic Client Registration - Automatic OAuth app creation when supported
• Automatic Token Refresh - Background refresh before expiration
• Scope Management - Shows granted scopes on credential

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:

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 be operational

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 hasn't been tested
• No validation tool selected yet, OR validation tool selected but not run
• Tools using this provider are hidden
• Bundles show "Blocked" or "Partial" status

Next steps:

1. Choose a validation tool (if not selected)
2. Click "VALIDATE NOW"
3. Wait for validation to complete

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:

Status	Meaning	Actions
ACTIVE	Ready to use	Can validate, can be used by tools
DISABLED	Temporarily inactive	Can re-enable
EXPIRED	OAuth token expired	Re-authorize needed

Editing Credentials

Editing Existing Credentials

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

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

Recommended validators are shown first - these tools:

• 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

Provider-level vs Credential-level:

• Provider-level default - Set on the provider for all users
• Credential-level override - Set on your specific credential
• Credential-level takes precedence

How to set:

1. During credential creation - Select from "Validation Tool (Optional)" section
2. After creation - Click "Change Tool" on credential card
3. Modal shows all available tools for the provider

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".

Running Validation

From credential card:

1. Click "VALIDATE NOW" (large green button)
2. Tool executes with your credential
3. Status updates in real-time
4. Result message appears

Validation process:

1. System retrieves saved validation_args (if any)
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 "Blocked"

Advanced Features

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

• Validate immediately after creating credentials
• Choose simple validation tools without required args
• Update credentials when rotating API keys
• Use descriptive names if provider supports named credentials
• Keep credentials verified by re-validating periodically
• 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 skip validation - always test before using
• Don't use destructive tools for validation
• Don't hardcode credentials in tools - always use provider auth
• Don't screenshot unmasked credentials - security risk

Related Documentation

• Validating Credentials - Detailed validation guide
• Understanding Providers - Provider concepts and auth types
• Bundle Studio - Test tools with credentials
• Quick Start Guide - Get your first credential working

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.