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 "Connect Provider"
• Authorize in the popup
• 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 → Providers → Connect Provider
5. Paste the key
6. Click "Save & Verify"

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

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 "Partial" or "Blocked"
• You can't use any tools that need this provider

Verified credentials:

• All tools become available
• Bundles show as "Operational"
• Tools work in your AI immediately

Verification Statuses

Status	Icon	Meaning	What to Do
Verified	🟢	Tested and working	Nothing - ready to use
Unverified	🟡	Not tested yet	Run validation
Error	🔴	Validation failed	Check credentials, try again
Expired	🟠	OAuth token expired	Re-authorize (auto-refresh failed)
Pending	⚪	Validation in progress	Wait 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 connected it yet
• Tools needing this provider won't work
• Click "Connect Provider" 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 operational 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. Dashboard → Providers → Find provider (e.g., Slack)
2. Click "Connect Provider"
3. Click "Authorize with OAuth"
4. Browser opens Slack's authorization page
5. Review requested scopes
6. Click "Allow"
7. Redirected back to MCPBundles
8. Credential saved with status UNVERIFIED
9. Click "Choose Validation Tool"
10. Select a test tool (e.g., "List Channels")
11. Click "Run Validation"
12. Success! Status changes to VERIFIED
13. All Slack 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 → Providers → Smartlead
5. Click "Connect Provider"
6. Paste API key
7. Click "Save & Verify"
8. System saves key (encrypted)
9. Choose validation tool
10. Provide test arguments (if needed)
11. Click "Run Validation"
12. Success! Smartlead tools are ready

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

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

• Quick Start Guide - Step 2 covers connecting credentials
• Troubleshooting Connectivity - Credential errors and fixes
• Understanding Bundles - How bundles use providers