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
  • MCP servers show Needs setup or Needs attention
  • You can't test or use tools

With valid credentials:

  • All tools become immediately available
  • MCP servers show Ready when connections are verified
  • Your AI can perform real actions

Understanding Credential Types​

MCPBundles supports four authentication methods:

TypeDescriptionWhen It's Used
API CredentialsSimple API key (copy/paste)Resend, OpenAI, HubSpot
OAuth 2.0Secure login flow (popup)Google, Slack, GitHub
OAuth 1.0OAuth 1.0 authentication flowTwitter, some legacy APIs
No AuthenticationPublic APIs requiring no credentialsWeather services, public data APIs
Webhook ingestUpstream systems POST data to an ingest URLListings that expose export tools after delivery
CSV uploadYou drop portal exports on the source in the side panelListings such as CSV Analyzer — no ingest URL

For webhook ingest connections (ingest URL, optional HMAC signing, last delivery status), see Webhook data capture.

For manual CSV exports (source name, upload in the side panel, analysis in chat), see CSV upload for MCP servers.

Need several accounts on one MCP URL (for example five ChatGPT Ads keys on one server)? Skip ahead to Multiple accounts on one MCP server.

Quick Start: Adding Your First Credential​

You can add credentials from multiple entry points in MCPBundles:

Option A: From MCP server page (recommended)​

When to use: Setting up a specific MCP server's required providers

  1. Go to MCP Servers
  2. Open an MCP server that needs credentials
  3. Scroll down to the "Credentials" section
  4. Find the provider card marked "Not configured"
  5. Click Connect on the provider row
  6. Credential panel slides in from the right side of your screen

Option B: From Provider Page​

When to use: Adding credentials before choosing MCP servers

  1. Go to Settings → Credentials (or MCP Servers → Directory to pick a server first)
  2. Click on a provider card
  3. On the provider detail page, scroll to the "Credentials" section
  4. If no connection exists, click Connect
  5. Credential panel slides in from the right side

Option C: From Add Tool dialog​

When to use: While customizing an MCP server's tools

  1. In an MCP server, click "+ Add Tool"
  2. Select a provider
  3. Click "+ Add New" to create a credential
  4. Credential panel slides in from the right side

What happens next depends on the credential type:

  • API Key → Fill in fields and click "Create Credential"
  • OAuth → Click OAuth button, authorize in popup window
  • None → Connection created automatically (no auth needed)

Adding API Key Credentials​

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

Example: Single-Field Credential (Resend)​

When you add a Resend credential in the credential panel:

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. Credential panel opens on the right side
  2. Paste your API key from Resend dashboard
  3. (Optional) Enter a Credential Name (e.g., "Production", "Staging")
  4. (Optional) Click eye icon to verify it's correct
  5. Click "Create Connection" (or equivalent save action)

Result: Connection saved. MCPBundles may auto-validate on save; if status stays UNVERIFIED, choose a validation tool and click Validate Now.

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. The credential panel stays open throughout the entire process!

How OAuth Works (New Context-Aware Flow)​

  1. Credential panel opens on the right side
  2. (Optional) Enter a credential name (e.g., "Work GitHub", "Production Slack")
  3. Click "Connect with [Provider]" button
  4. OAuth window opens → Log in to provider
  5. Review permissions → See what access is requested
  6. Click "Allow" → Authorize MCPBundles
  7. OAuth window closes → You return to the MCP server or provider page
  8. Credential panel reopens after OAuth (resume flow)
  9. OAuth connections often save as VERIFIED immediately; otherwise use Validate Now

Key feature: The panel remembers where you were after OAuth — no need to navigate back manually.

Example: Connecting Google​

  1. Click Connect on the Google provider row
  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​

After creating a connection, MCPBundles may auto-validate on save. You can always open the connection and use Validate Now.

Step 1: Choose a Validation Tool​

Pick a validation tool from the list when you choose Validate Now.

Status Badge shows: "UNVERIFIED" (yellow/amber)

  1. Look for "Recommended" badges - These tools are safe and simple
  2. Select a simple, safe tool (usually a list/fetch operation)
  3. Click "Use as validator" on your chosen tool

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
  • analytics_links (Ayrshare) - Gets analytics data

Avoid validation tools that:

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

Step 2: Configure Validation Parameters (If Needed)​

Most validation tools don't need parameters, but some do:

Example: get_campaign needs campaign_id

  1. After selecting the tool, you'll see a "Validation Parameters" section
  2. Click "Configure" to open the parameter form
  3. Fill in required parameters (use test data or IDs you know exist)
  4. Click "Save"

Tip: Choose tools without parameters when possible - they're faster to validate!

Step 3: Run Validation​

After selecting a tool (and configuring parameters if needed):

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

Three possible outcomes:

VERIFIED — credential validated

  • Green badge with checkmark icon
  • Credential works perfectly
  • All tools are now available
  • Panel may close automatically

UNVERIFIED — needs validation

  • Yellow badge with warning icon
  • Haven't validated yet or validation tool not selected
  • Choose a validation tool and run it

ERROR — validation failed

  • Red badge with X icon
  • Something went wrong (wrong API key, insufficient permissions, etc.)
  • Check error message for details
  • See Troubleshooting for common fixes

Re-Validating Credentials​

Credentials should be re-validated when:

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

How to re-validate:

From MCP server page:

  1. Go to your MCP server
  2. Scroll to the "Credentials" section
  3. Find the provider card with the credential
  4. Click "Edit" button (pencil icon)
  5. Credential panel opens
  6. Click "Validate Now" button (or select a different validation tool first)
  7. System runs the validation tool again

From Provider Page:

  1. Go to Settings → Credentials → Select provider
  2. Scroll to the "Credentials" section
  3. Find your credential card
  4. Click "Edit" button (pencil icon)
  5. Credential panel opens
  6. Click "Validate Now" button
  7. 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​

From MCP server page:

  1. Go to your MCP server
  2. Scroll to the "Credentials" section
  3. Find the provider card with the credential
  4. Click the "Edit" button (pencil icon) on the credential card
  5. Credential panel slides in showing masked values
  6. Make your changes
  7. Click "Update Credential"
  8. Re-validate to confirm changes work

From Provider Page:

  1. Go to Settings → Credentials → Select provider
  2. Scroll to the "Credentials" section
  3. Find your credential card
  4. Click the "Edit" button (pencil icon)
  5. Credential panel opens showing:
    • Masked values - Sensitive data shown as ●●●●●●●●last4
    • Show button - Click eye icon to reveal full value
    • Form fields - Edit any field
  6. Make changes
  7. Click "Update Credential"
  8. Re-validate to confirm changes work

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. Open the credential (Edit button)
  2. Click "Connect with [Provider]" again → Reauthorize with new account
  3. Credential panel reopens automatically after OAuth
  4. Validate the new credential to confirm it works

Changing Validation Tool​

You can change which tool validates your credential:

  1. Open the credential (Edit button)
  2. Click "Select Validation Tool" or "Change Tool"
  3. Validation tool picker opens
  4. Select a new tool from the list
  5. (Optional) Configure parameters if needed
  6. Click Validate Now to test 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

Multiple accounts on one MCP server​

Use this when you want one MCP URL in Claude, Cursor, or another client, but more than one login or API key for the same service on that server — multiple QuickBooks companies, several ChatGPT Ads ad accounts, work and personal mail on one Gmail server, and similar setups.

You do not need a separate MCP server per account. Attach each saved connection under Accounts on this server and keep the same URL in your AI client.

If you instead want one URL that only ever talks to one account (for example a URL you share with a single client), create a dedicated server on the parent MCP server. Dedicated servers do not share accounts with the parent.

Set up (a few minutes)​

  1. Open the MCP server in your workspace (for example ChatGPT Ads or QuickBooks).
  2. Scroll to Connection → Accounts on this server.
  3. Connect the first account if nothing is attached yet (sign in, paste a key, or finish the form — same as a single-account server).
  4. Click Connect a different … account (wording matches the service) and add the next account. Give each connection a name you will say in chat when you mean that account.
  5. Repeat for every account you need on this server.
  6. Leave your MCP URL unchanged in your AI client. Refresh MCP tools in the client only if it caches aggressively and does not show new accounts after attach.

Already saved a connection elsewhere? On the same Connection section, use Attach an account to this server and Attach on the row you want instead of signing in again.

Use from chat​

  • One account on the server: ask normally. Every tool call uses that account.
  • Two or more accounts: name the account in plain language in your prompt (for Acme's QuickBooks…, on the HDR ChatGPT Ads connection…). Your AI should pick the matching label. If it is unsure, ask it to list which accounts are connected on this server, then continue.
  • Wrong account is worse than no answer: if the model does not specify an account when several are attached, MCPBundles blocks the call and returns the list of names it can see so nothing runs on the wrong books or ad account.

More examples (bookkeeping, Stripe, mail): Multiple accounts, one MCP URL.

Example: several ChatGPT Ads accounts​

ChatGPT Ads uses one API key per ad account. To manage five properties from one MCP URL:

  1. Open ChatGPT Ads in your workspace and connect the MCP server once in your AI client.
  2. Under Accounts on this server, add five connections — one key per ad account.
  3. Name each connection after the property or label you use internally.
  4. In chat, name the connection when you ask for spend, campaigns, or reports for that property.

View credentials in the workspace​

On the MCP server page: Connection lists each service on the server. Accounts on this server lists every attached account with Edit, Remove from server, and Delete.

Settings → Credentials: pick a service to see all saved connections in the workspace (verified, unverified, or error), whether or not they are attached to a server.

How MCPBundles picks an account​

  • One account attached: every call uses that account. Nothing else to choose.
  • Two or more accounts attached: your AI must say which account each call is for, using the connection name you saved. If it does not, MCPBundles returns an error that lists the accounts it can see, so the call never runs on the wrong one.
  • At any time, ask your AI which accounts are connected on this MCP server before you run multi-step work across clients or properties.

Remove an account from a server​

Click Remove from server on the account row. The MCP server stops using that account. The saved connection stays in your workspace so you can attach it again or use it on another server. When only one account remains, calls use that account automatically with no extra naming step.

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​

From MCP server page:

  1. Go to your MCP server
  2. Scroll to the "Credentials" section
  3. Find the provider card with the bound credential
  4. Click Remove from server on that account row (keeps the saved connection in your account)
  5. Or go to the provider page and delete the credential entirely

From Provider Page:

  1. Go to Settings → Credentials → Select provider
  2. Scroll to the "Credentials" section
  3. Find the credential card
  4. Click the "Delete" button (trash icon)
  5. Confirm deletion in the dialog
danger

Deletion is immediate and irreversible!

Deleting a credential:

  • Removes it from database permanently
  • Invalidates all MCP servers 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:

  • In a personal workspace, credentials are private to you
  • In a team workspace, credentials are shared with all workspace members
  • Credentials are always isolated between workspaces — one workspace can never access another's
  • See Understanding Workspaces for details

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 with [Provider]" 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?​