Skip to main content

How MCPBundles Works

MCPBundles connects your AI assistants to real-world APIs through a four-layer architecture. This page explains how everything fits together.

The Four Layers​

Your AI (ChatGPT, Claude, Cursor)
           ↓
      MCP Bundle
           ↓
        Tools
           ↓
      Providers (APIs)

1. Your AI Assistant​

This is the AI tool you use daily: ChatGPT, Claude Desktop, Cursor, VS Code Copilot, etc. These tools support the Model Context Protocol (MCP), which lets them discover and use external tools.

2. Bundles​

A bundle is a cloud-hosted collection of related tools grouped by purpose.

For example, a "Marketing Automation" bundle might contain:

  • List email campaigns
  • Check campaign replies
  • Generate email copy
  • Create new contacts
  • Send Slack notifications

Why bundles? Instead of adding 50 individual tools to your AI, you add one bundle URL and get access to all the tools inside it.

Two ways to add bundles:

  • MCP URL: Copy https://mcp.mcpbundles.com/bundle/your-bundle and paste into any MCP client
  • .mcpb File: Download the bundle as a .mcpb extension file for one-click installation in Claude Desktop

Both methods connect to the same cloud-hosted bundle—the .mcpb file is just a convenient installer wrapper.

You control bundles in your dashboard:

  • Create new bundles to organize tools
  • Add or remove tools from bundles
  • Enable/disable bundles on your account
  • Publish bundles to share with others

Bundle Status:

  • Draft: You're still editing it, not ready to use
  • Published: Ready to use in your AI tools
  • Enabled: You've added it to your account and can use its tools
  • Disabled: Bundle exists but tools won't appear in your AI

3. Tools​

A tool is a single action your AI can perform.

Examples:

  • list_campaigns - Fetch all your email campaigns from Smartlead
  • generate_email - Write marketing copy using OpenAI
  • create_contact - Add someone to your HubSpot CRM

Each tool:

  • Has a clear name and description
  • Defines what inputs it needs (campaign ID, email address, etc.)
  • Specifies which provider(s) it needs to work
  • Can belong to multiple bundles

Tool Visibility: Tools only appear in your AI when:

  1. The tool's status is ACTIVE
  2. All required providers are connected and verified
  3. The bundle containing the tool is enabled on your account

4. Providers​

A provider is an external API service that tools connect to.

Examples:

  • Smartlead - Email outreach platform
  • OpenAI - AI text generation
  • HubSpot - CRM and marketing automation
  • Slack - Team communication
  • GitHub - Code hosting

Provider Types:

  • API Providers: Traditional REST APIs (Smartlead, HubSpot, Slack)
  • MCP Providers: Other MCP servers you can connect to

Authentication Types:

  • OAuth2: You authorize via browser (most secure)
  • API Key: You paste an API key from the provider
  • Bearer Token: Similar to API key, used by some services
  • None: Public APIs that don't need authentication

How It All Connects​

Example: Marketing Automation Flow​

Let's say you want to use an AI tool to check your email campaigns. Here's what happens:

1. You Enable the Bundle

  • Go to your dashboard → Bundles
  • Find "Marketing Automation" bundle
  • Click "Add to My Account"
  • The bundle is now enabled

2. You Connect Providers

  • The bundle shows "Needs Credentials" because it requires Smartlead
  • Go to Providers → Connect Smartlead
  • Enter your Smartlead API key
  • System verifies the credential works
  • Provider status changes to "Connected & Verified"

3. Bundle Becomes Ready

  • Now that Smartlead is verified, the bundle status changes to "Operational"
  • All tools in the bundle that need Smartlead are now available

4. You Add Bundle to Your AI

  • Copy the bundle's MCP URL from your dashboard
  • Paste it into ChatGPT (or Cursor, Claude, etc.)
  • Your AI discovers all the tools in the bundle

5. You Use Tools in Your AI

  • Ask: "List my Smartlead campaigns"
  • Your AI sees the list_campaigns tool
  • It calls the tool with your credentials
  • Tool connects to Smartlead API
  • Results come back to your AI

Bundle Readiness​

Bundles show different readiness states based on provider credentials:

Operational (Green)​

All required providers are connected and verified. Every tool works.

Partial (Yellow)​

Some providers are connected, but not all. Some tools work, others don't.

Blocked (Red)​

Missing all required provider credentials. No tools will work.

Unknown (Gray)​

You haven't enabled this bundle yet, so we can't check its status.

Tool Dependencies​

Tools declare which providers they need to function:

Required Dependency​

The tool cannot work without this provider.

Example: list_campaigns requires Smartlead

  • If Smartlead isn't connected: tool is hidden from your AI
  • If Smartlead is connected but unverified: tool is hidden
  • If Smartlead is verified: tool appears and works

Optional Dependency​

The tool works without it but provides extra features with it.

Example: A search tool might optionally use OpenAI for AI summaries

  • Without OpenAI: returns basic search results
  • With OpenAI: adds AI-generated summaries

Multi-Provider Tools​

Some tools use multiple providers at once.

Example: "AI Email Responder" tool might:

  1. Fetch email thread from Smartlead (required)
  2. Generate reply using OpenAI (required)
  3. Post notification to Slack (optional)

This tool needs both Smartlead and OpenAI to work. Slack is optional—if you connect it, you get notifications; if not, the tool still generates replies.

Security & Credentials​

How Credentials Are Stored​

  • All API keys and tokens are encrypted at rest
  • OAuth tokens are refreshed automatically when they expire
  • Each user's credentials are completely isolated—you can't access anyone else's

Credential Verification​

When you add credentials, the system:

  1. Stores them securely (encrypted)
  2. Runs a validation tool to test the connection
  3. Marks the credential as "Verified" if successful
  4. Automatically refreshes OAuth tokens before they expire
  5. Re-validates periodically to catch revoked keys

Credential Status​

  • Verified (Green): Tested and working
  • Unverified (Yellow): Added but not tested yet
  • Error (Red): Validation failed, credential might be invalid
  • Expired (Orange): OAuth token expired and couldn't refresh

Real-World Example​

Here's a complete example showing all four layers:

Your Goal: Build an AI assistant that manages your marketing campaigns

Layer 1: Your AI

  • You're using ChatGPT with MCP connectors enabled

Layer 2: Bundle

  • You create a "Marketing Suite" bundle
  • Contains 12 tools for campaigns, contacts, and analytics

Layer 3: Tools

  • list_campaigns → shows all campaigns
  • count_replies → counts email replies
  • create_contact → adds people to CRM
  • generate_email → writes marketing copy
  • (8 more tools...)

Layer 4: Providers

  • Smartlead: Campaign and reply tools connect here (OAuth2)
  • HubSpot: Contact tools connect here (API Key)
  • OpenAI: Email generation tool connects here (API Key)

What You Do:

  1. Create the "Marketing Suite" bundle
  2. Add all 12 tools to it
  3. Connect your Smartlead account (OAuth)
  4. Connect your HubSpot account (API key)
  5. Connect your OpenAI account (API key)
  6. Publish the bundle
  7. Enable it on your account
  8. Copy the bundle URL
  9. Add URL to ChatGPT connectors
  10. Ask ChatGPT: "How many replies did my latest campaign get?"

What Happens Behind the Scenes:

  1. ChatGPT discovers your bundle's tools
  2. It sees the count_replies tool
  3. It calls the tool with the campaign name
  4. Tool uses your Smartlead credentials
  5. Connects to Smartlead API
  6. Fetches reply count
  7. Returns number to ChatGPT
  8. ChatGPT shows you the answer

Next Steps​