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.

How you connect on MCPBundles:

  • Copy https://mcp.mcpbundles.com/bundle/your-bundle-slug and paste it into any MCP client, or use the one-click install links on the server page for supported clients.

Some MCP clients also accept .mcpb packaging files from other publishers; that is a separate install format, not the MCPBundles connection path.

You control MCP servers in your dashboard:

  • Create new MCP servers to organize tools
  • Add or remove tools
  • Connect or turn off MCP servers in your workspace
  • Publish MCP servers to share with others

Publication status (for MCP servers you create or publish):

  • Draft — Still editing; not listed for others
  • Published — Live listing or workspace-ready definition
  • Deprecated / Archived — Retired from active use

Workspace connection is separate: an MCP server must be connected in your workspace (via Connect or Add to workspace) before its tools appear in the Hub or your AI client. Turn off removes workspace access without deleting the server definition. Readiness Disabled means the server is not connected in this workspace — not that publication is still draft.

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

  • Go to MCP Servers and use Directory (or search) to find "Marketing Automation"
  • Open the server and click Connect (or follow the primary action on the row)

2. You connect providers

  • The server shows Needs setup until Smartlead is connected
  • Open the Connections section (or go to Settings → Credentials)
  • Connect Smartlead and validate
  • Status changes to Ready when connections are verified

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 a short label and message based on workspace access and provider connections (same contract everywhere: server page, MCP Servers list, Studio, Hub):

LabelMeaning
ReadyRequired connections are verified; tools can run (includes servers you have not run tools on yet)
Needs setupMissing connections, mixed missing and broken connections, or the server is not connected in your workspace yet — message often names counts, e.g. connect N providers or fix connections
Needs attentionEvery required provider has a connection, but at least one is expired, unverified, or missing required scopes — message prompts Reconnect for a named provider
DisabledNot connected in this workspace — use Add to workspace or Connect
Status unknownReadiness could not be evaluated (try refreshing the page)

The primary button on the row or server page matches the next step (Connect, Reconnect, Fix connections, Turn off, Open in …, and so on).

For connection UX, publication rules, and readiness detail, see Understanding MCP Servers.

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. Connect it in your workspace (MCP Servers → In workspace or Connect on the server page)
  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​