Skip to main content

Understanding Providers

Providers are the external services that tools connect to. This page explains what providers are, how authentication works, and how to manage your credentials.

What is a Provider?​

A provider is an external API service that tools use to perform actions.

Examples:

  • Smartlead - Email outreach platform
  • HubSpot - CRM and sales automation
  • OpenAI - AI text generation
  • Slack - Team communication
  • GitHub - Code hosting and collaboration
  • Stripe - Payment processing

Two Types of Providers​

1. API Providers​

Traditional REST APIs with OpenAPI specifications.

  • Smartlead, HubSpot, Slack, etc.
  • Require API keys or OAuth authentication
  • Tools make HTTP requests to their APIs
  • Most providers fall into this category

2. MCP Providers​

Other MCP servers you can connect to.

  • Another MCPBundles user's server
  • Self-hosted MCP servers
  • MCP servers from other platforms
  • Can discover their tools dynamically

Provider Categories​

Providers are organized by the type of service they provide (same categories as bundles):

  • Analytics: Google Analytics, Mixpanel
  • Cloud: AWS, Azure, Google Cloud
  • Collaboration: Slack, Microsoft Teams
  • CRM: HubSpot, Salesforce
  • Developer Tools: GitHub, GitLab
  • Email: SendGrid, Mailchimp
  • Financial: Stripe, PayPal
  • Marketing: Smartlead, ActiveCampaign
  • (and 26 more categories)

Authentication Methods​

Different providers require different ways to authenticate. MCPBundles supports four methods:

1. OAuth2 (Most Secure)​

How it works:

  1. You click "Connect" on a provider
  2. Browser opens the provider's authorization page
  3. You log in and approve access
  4. Provider sends back an access token
  5. Token is encrypted and stored
  6. System automatically refreshes the token before it expires

Advantages:

  • You never share your password
  • Tokens can be revoked anytime
  • Scoped permissions (read-only, write, admin)
  • Automatically refreshed
  • Most secure method

Examples:

  • Google (Gmail, Calendar, Drive)
  • Slack
  • GitHub
  • Microsoft 365

What you do:

  • Click "Add Credential" (provider page) or "Configure" (bundle page)
  • Authorize in the OAuth popup
  • Credential panel reopens automatically after OAuth
  • Select validation tool and validate
  • Done! Token is managed automatically

2. API Key (Most Common)​

How it works:

  1. You generate an API key from the provider's dashboard
  2. You copy the key
  3. You paste it into MCPBundles
  4. Key is encrypted and stored
  5. Tools use this key for authentication

Advantages:

  • Simple and quick
  • Works with most APIs
  • No browser popup needed
  • Long-lived (doesn't expire)

Disadvantages:

  • Less secure than OAuth
  • Must manually rotate if compromised
  • No automatic refresh

Examples:

  • Smartlead
  • OpenAI
  • HubSpot (also supports OAuth)
  • Many REST APIs

What you do:

  1. Go to provider's website → Settings → API Keys
  2. Click "Generate New API Key"
  3. Copy the key
  4. Go to MCPBundles:
    • From Bundle: Click "Configure" → "+ Add New Credential"
    • From Provider Page: Click "Add Credential"
  5. Credential panel opens → Paste the key
  6. Click "Create Credential"
  7. Select validation tool and click "Validate Now"

3. Bearer Token​

How it works: Similar to API keys, but used specifically for bearer token authentication (common in modern APIs).

Difference from API Key:

  • Sent in Authorization: Bearer {token} header
  • Often shorter-lived than API keys
  • Used by newer APIs

Examples:

  • Some payment processors
  • Modern SaaS APIs
  • Internal company APIs

What you do: Same process as API keys—generate, copy, paste, verify.

4. None (Public APIs)​

How it works: Provider doesn't require authentication. API is publicly accessible.

Use cases:

  • Public data sources
  • Weather APIs
  • Some government data
  • Free tier APIs

What you do:

  1. Go to provider page
  2. Click "Create Connection & Test"
  3. System creates a connection record (for tracking)
  4. Runs a validation tool to confirm it works

Note: Even though no credentials are needed, MCPBundles creates a "connection" record so it can track which providers you're using and verify they're functioning correctly.

Credential Storage & Security​

How Credentials Are Stored​

All credentials are encrypted at rest:

  • API keys encrypted with Fernet (symmetric encryption)
  • OAuth tokens encrypted with Fernet
  • Bearer tokens encrypted with Fernet
  • Encryption keys stored separately from data
  • Each user's credentials completely isolated

What we store:

  • Encrypted credential data (JSON structure with all credential fields)
  • Credential type (API_KEY, OAUTH2, etc.)
  • When it was created
  • When it was last used
  • Verification status
  • Granted OAuth scopes (if applicable)

What we DON'T store:

  • Your password (for OAuth)
  • Unencrypted keys
  • Data from the provider's API

Schema-Driven Credentials​

Some providers use schema-driven credentials that define multiple fields instead of a single API key. This provides:

For SaaS providers:

  • instance_url - Your organization's unique instance URL
  • api_key - Your API key for that instance
  • Example: Salesforce, ServiceNow, Jira Cloud

For database providers:

  • host - Database server hostname
  • port - Database port number
  • user - Database username
  • password - Database password
  • database - Database name
  • Example: PostgreSQL, MySQL, MongoDB

How it works:

  1. Provider defines a credential_schema with expected fields
  2. UI automatically renders form inputs for each field
  3. Backend injects standardized headers based on schema:
    • x-{provider}-instance-url for instance URLs
    • x-{provider}-dsn for database connection strings
    • x-{provider}-{field} for individual connection parameters
  4. Tools read from these headers to connect dynamically

Benefits:

  • No hardcoded base URLs in provider config
  • Support for multi-tenant SaaS (each user connects to their instance)
  • Consistent database connection patterns
  • Self-documenting credential requirements

User Isolation​

Your credentials are completely isolated from other users:

  • No user can see another user's credentials
  • Shared bundles use each user's own credentials
  • Even admins can't view your encrypted keys
  • Database queries are automatically scoped to your user ID

Credential Verification​

After adding credentials, the system verifies they work by running a test tool.

Verification Process​

When you add credentials:

  1. Credentials Saved

    • Status: ACTIVE
    • Verification: UNVERIFIED

  2. Choose Validation Tool

    • Pick a tool to test with (e.g., "List Campaigns")
    • Provide any required arguments
    • Click "Run Validation"

  3. Validation Runs

    • Tool calls the provider's API using your credentials
    • If successful: status changes to VERIFIED
    • If failed: status changes to ERROR

  4. Result Displayed

    • Success: Green checkmark, "Credentials verified!"
    • Failure: Red X, error message with details

Why Verification Matters​

Unverified credentials:

  • Tools using this provider won't appear in your AI
  • Bundles show as "Setup Required"
  • You can't use any tools that need this provider

Verified credentials:

  • All tools become available
  • Bundles show as "Ready - Credentials valid"
  • Tools work in your AI immediately

Verification Statuses​

StatusIconMeaningWhat to Do
Verified🟢Tested and workingNothing - ready to use
Unverified🟡Not tested yetRun validation
Error🔴Validation failedCheck credentials, try again
Expired🟠OAuth token expiredRe-authorize (auto-refresh failed)
Pending⚪Validation in progressWait for completion

OAuth Scopes & Permissions​

OAuth providers use "scopes" to control what your tools can access.

What Are Scopes?​

Scopes are specific permissions that define what actions are allowed.

Examples:

  • read:campaigns - Read campaign data
  • write:campaigns - Create/modify campaigns
  • admin:account - Full account access
  • email.send - Send emails
  • calendar.readonly - Read calendar events

How Scopes Work in MCPBundles​

When you connect a provider:

  1. System requests specific scopes based on which tools you're using
  2. Provider shows you what permissions are being requested
  3. You approve (or deny)
  4. Token is granted with those scopes

What tools can do:

  • Tools that need read:campaigns will work
  • Tools that need write:campaigns won't work (if you only granted read)
  • You'll see a "Scope Mismatch" error for those tools

Scope Mismatches​

Sometimes a tool needs more permissions than you've granted.

Example:

  • You authorized Smartlead with read:campaigns scope
  • Tool "Create Campaign" needs write:campaigns scope
  • Tool appears as "Scope Mismatch" and won't work

How to fix:

  1. Go to Provider → Re-authorize
  2. Grant additional scopes when prompted
  3. System updates your credential
  4. Tool becomes available

Granting Minimal Scopes​

Best practice: Only grant scopes you actually need.

  • Review what each scope allows
  • Start with read-only scopes
  • Add write scopes only for tools you trust
  • Avoid "admin" or "full access" scopes unless necessary

OAuth Token Refresh​

OAuth tokens expire after a certain time (1 hour, 1 day, 1 week, etc.). MCPBundles automatically refreshes them.

How Auto-Refresh Works​

Background process:

  1. System checks tokens every hour
  2. If token expires in < 24 hours, refresh it
  3. Use refresh token to get new access token
  4. Update credential with new token
  5. No action needed from you

If refresh fails:

  • Status changes to EXPIRED
  • You'll see "Re-authorization required"
  • Click "Re-authorize" to get a new token
  • All tools resume working

Manual Re-authorization​

If automatic refresh fails (provider revoked access, refresh token expired, etc.):

  1. Go to Provider page
  2. Click "Re-authorize"
  3. Complete OAuth flow again
  4. New token is stored
  5. Status changes back to VERIFIED

Connection States​

Providers show different connection states based on your credentials:

Connected 🟢​

You have verified credentials. Provider is working.

  • At least one credential is ACTIVE and VERIFIED
  • All tools using this provider are available
  • No action needed

Unverified 🟡​

You have credentials but they haven't been tested yet.

  • Credential exists but verification status is UNVERIFIED
  • Tools using this provider are hidden
  • Run validation to fix

Error 🔴​

Credentials exist but validation failed.

  • Latest validation returned an error
  • Credential might be invalid, expired, or revoked
  • Delete and re-add credentials, or re-authorize

None ⚪​

No credentials exist for this provider.

  • You haven't added credentials yet
  • Tools needing this provider won't work
  • Click "Add Credential" (provider page) or "Configure" (bundle page) to fix

Attention​

Mix of error and unverified credentials.

  • Some credentials have errors
  • Some need verification
  • Review each credential's status

Managing Multiple Credentials​

Some users need multiple credentials for the same provider:

Use Cases​

  • Production vs. Development: Different API keys for different environments
  • Multiple Accounts: Personal and business Slack workspaces
  • Team Members: Different GitHub accounts for different projects

How It Works​

  • Only one credential can be active per provider per user
  • Last verified credential becomes the active one
  • Tools use the active credential
  • Switching credentials: disable old, add new

Switching Credentials​

To switch from production to development API key:

  1. Go to Provider → Credentials
  2. Delete or disable the old credential
  3. Add new credential
  4. Verify the new one
  5. Tools now use the new credential

Provider Status​

Providers themselves have status beyond your credentials:

Active​

Provider is functioning and supported.

  • You can connect credentials
  • Tools work normally
  • Regular updates and maintenance

Inactive​

Provider is temporarily unavailable.

  • Platform issues
  • API maintenance
  • System can't reach provider
  • Your credentials are saved but tools won't work

Deprecated​

Provider is being phased out.

  • Still works but no longer recommended
  • Migrate to alternative provider
  • Will eventually become inactive

Common Workflows​

Workflow 1: Connecting OAuth Provider​

  1. From Bundle: Click "Configure" next to provider → "+ Add New Credential" OR From Provider Page: Dashboard → Providers → Find provider → Click "Add Credential"
  2. Credential panel slides in from the right
  3. (Optional) Enter credential name
  4. Click "Connect with [Provider]" (e.g., "Connect with Slack")
  5. OAuth window opens → Slack's authorization page loads
  6. Review requested scopes (read messages, post messages, etc.)
  7. Click "Allow" to authorize MCPBundles
  8. OAuth window closes → You return to MCPBundles
  9. 🎯 Credential panel automatically reopens!
  10. 🎯 Validation tool picker automatically opens!
  11. Select a validation tool and click "Validate Now"
  12. Success! Status changes to VERIFIED
  13. Credential is saved (encrypted), verified, and ready to use
  14. All provider tools are now available

Workflow 2: Connecting API Key Provider​

  1. Go to Smartlead.ai → Settings → API Keys
  2. Click "Generate API Key"
  3. Copy the key
  4. Go to MCPBundles:
    • From Bundle: Click "Configure" next to Smartlead → "+ Add New Credential"
    • OR From Provider Page: Dashboard → Providers → Smartlead → "Add Credential"
  5. Credential panel opens → Paste API key
  6. (Optional) Enter credential name
  7. Click "Create Credential"
  8. 🎯 Validation tool picker automatically opens!
  9. Select a validation tool (e.g., "List Campaigns")
  10. (Optional) Provide test arguments if needed
  11. Click "Validate Now"
  12. Success! Status changes to VERIFIED
  13. Smartlead tools are ready to use

Workflow 3: Fixing Expired OAuth Token​

  1. You see "Bundle Needs Attention" notification
  2. Go to Bundle → Providers
  3. See "Smartlead: EXPIRED"
  4. Click provider name
  5. Click "Re-authorize"
  6. Complete OAuth flow again
  7. New token stored
  8. Status returns to VERIFIED
  9. Bundle returns to "Ready - Credentials valid"

Workflow 4: Testing Public API (No Auth)​

  1. Dashboard → Providers → Find public API
  2. Click "Create Connection & Test"
  3. Empty credential is created (no auth needed)
  4. Choose validation tool
  5. Click "Run Validation"
  6. Tool connects to public API
  7. Success! Status: VERIFIED
  8. Tools using this provider are available

Troubleshooting​

"Credential verification failed"​

Causes:

  • Invalid API key
  • Wrong OAuth scopes
  • Provider is down
  • Network issues

Solutions:

  1. Double-check the API key is correct
  2. Re-authorize with correct scopes
  3. Wait and try again if provider is down
  4. Check error message for specifics

"Scope mismatch"​

Cause: Tool needs permissions you didn't grant.

Solution:

  1. Go to provider
  2. Click "Re-authorize"
  3. Grant additional scopes
  4. Tools will become available

"Token expired" (OAuth)​

Cause: Auto-refresh failed.

Solution:

  1. Click "Re-authorize"
  2. Complete OAuth flow
  3. New token is stored

"Provider inactive"​

Cause: Provider's API is down or deprecated.

Solution:

  • Wait for provider to come back online
  • Check provider's status page
  • Consider alternative providers

Next Steps​