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 server
           ↓
        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. MCP servers​

An MCP server is a cloud-hosted collection of related tools grouped by purpose.

For example, a "Marketing Automation" MCP server might contain:

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

Why MCP servers? Instead of adding 50 individual tools to your AI, you add one MCP URL (for example https://mcp.mcpbundles.com/bundle/your-bundle-slug) and get access to all the tools inside it.

Two ways to connect:

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

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

You control MCP servers in your dashboard:

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

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: It 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 MCP servers

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 MCP server 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 MCP server

  • Go to MCP Servers → Discover
  • Find "Marketing Automation"
  • Click Enable on the server page

2. You connect providers

  • The server shows Setup Required because it needs Smartlead
  • Open the Connections section (or go to Settings → Credentials)
  • Connect Smartlead and validate
  • Status changes to Ready with Credentials valid

3. You add the MCP URL to your AI

  • Copy the MCP URL from your dashboard (path includes /bundle/... and your slug)
  • Paste it into ChatGPT (or Cursor, Claude, etc.)
  • Your AI discovers all the tools

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

Readiness​

MCP servers show different readiness states based on provider credentials:

Ready (Green, with "Credentials valid" subtext)​

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

Setup Required (Yellow, with "Connect provider accounts" subtext)​

Missing some or all required provider credentials. You need to add and verify credentials before tools can function.

Connection Error - Credentials expired (Red)​

Provider credentials exist but are invalid (e.g., expired OAuth tokens, revoked API keys). Tools cannot function until you re-authenticate or update credentials.

Unknown (Gray)​

You haven't enabled this MCP server 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
  • Credentials are scoped to your workspace—in a team workspace, all members can use workspace credentials but only the owner can view or edit values. In a personal workspace, credentials are private to you
  • Credentials are always isolated between workspaces—one workspace can never access another'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 apps enabled

Layer 2: MCP server

  • You create a "Marketing Suite" MCP server
  • 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" MCP server
  2. Add all 12 tools
  3. Connect your Smartlead account (OAuth)
  4. Connect your HubSpot account (API key)
  5. Connect your OpenAI account (API key)
  6. Publish
  7. Enable it on your account
  8. Copy the MCP URL
  9. Add URL to ChatGPT Apps (Settings → Apps → Create app)
  10. Ask ChatGPT: "How many replies did my latest campaign get?"

What Happens Behind the Scenes:

  1. ChatGPT discovers your 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

A2A agents: coworkers above tools​

MCP servers give your AI tools — discrete actions like "list campaigns" or "create a contact." A2A agents give other software coworkers: assistants that follow markdown instructions, run on a schedule or from webhooks, and speak the open Agent-to-Agent (A2A) protocol.

External orchestrator, webhook, or other agent
           ↓
      A2A SendMessage (task lifecycle)
           ↓
      A2A agent (instructions + heartbeat checklist)
           ↓
      MCP tools (same Hub or bundle the agent is bound to)
           ↓
      Providers (APIs)

Each agent publishes an Agent Card at a stable slug so SDKs and registries can discover it before sending work. The same underlying configuration powers Studio chat (interactive, streaming) and A2A execution (programmatic tasks) — different transports, one agent.

See What Are A2A Agents? for visibility, triggers, and how SendMessage maps to run history.

Next Steps​