How MCP Hive Works

MCP Hive is a marketplace that connects AI applications to paid MCP servers. This page explains how the components connect technically, from initial setup through discovery, invocation, and billing.

The Components

MCP Hive Backend Server

The Backend Server is the central gateway for all MCP Hive traffic. It:

  • Validates credentials - Confirms the consumer has a valid credential and an active subscription
  • Routes MCP calls - Forwards requests to the correct MCP server provider
  • Logs interactions - Records metadata for billing and quality analysis
  • Hosts discovery - Runs the built-in MCP Hive MCP service, which provides the discoverServers tool that AI agents use to explore available servers and their capabilities

MCP Hive Proxy

The Proxy connects AI applications to the Backend Server. It always runs in gateway mode, exposing all available servers through a single connection with namespaced tools (e.g., weather___getWeather). Discovery tools are automatically available through the gateway.

There are two deployment options:

  • Local proxy - Installed via npm (@mcp-hive-utils/proxy), runs as a local process using stdio transport. Ideal for desktop AI applications like Claude Desktop or Cursor.
  • Hosted proxy - Available at proxy.mcp-hive.com over HTTPS transport. No local installation required - connect directly from any MCP-compatible application.

Architecture

MCP Hive Architecture

The architecture follows a left-to-right flow: an End User initiates a task through an AI Agent, which connects to the MCP Hive Proxy (local or hosted). The proxy forwards requests over HTTPS to the MCP Hive Backend Server, which routes them to the appropriate MCP Providers. Providers may be containerized servers managed by MCP Hive or remote HTTPS-hosted servers operated by the provider themselves.

End-to-End Flow

The following sequence diagram illustrates the complete lifecycle of an MCP Hive interaction.

MCP Hive Sequence

Phase 1: Setup

  1. Start the proxy - The AI application starts the MCP Hive Proxy, passing the user's credential. The proxy connects to the Backend Server and retrieves the schemas for the gateway tools (discoverServers, callServer).
  2. Register tools - The proxy presents these tools to the AI agent as standard MCP tools, ready for use.

Phase 2: Discovery

  1. User makes a request - The user asks a question requiring external data (e.g., "Plan a sunny weekend in Montreal").
  2. AI agent discovers actions - The agent calls discoverServers describing the task in natural language (e.g., "plan outdoor activities for a weekend in Montreal"). The Backend Server returns a ranked list of ready-to-invoke actions, each with its tool schema, pricing and vital statistics.
  3. Agent selects a provider - Based on the discovery results - including quality metrics and pricing - the agent chooses the best provider for the task.

Phase 3: Invocation

  1. AI agent calls a tool - The agent calls callServer, specifying the server name, tool name, and arguments.
  2. Proxy forwards to server - The proxy packages the request with credentials and sends it to the Backend Server over HTTPS.
  3. Server routes to provider - The Backend Server validates the request, identifies the target provider, and forwards the MCP call.
  4. Provider responds - The provider executes the request and returns results. The response travels back through the server and proxy to the AI agent.

Phase 4: Billing

  1. Interaction logged - Every invocation is recorded with metadata including consumer, provider, tool, timestamp, latency, and response characteristics.
  2. Billing settled - At the end of each monthly billing period, consumers are charged and providers earn based on completed calls.

Discovery

Discovery is a key differentiator of MCP Hive. Rather than requiring clients to know which MCP servers exist ahead of time, AI agents can explore the marketplace dynamically.

The Backend Server's built-in MCP service implements discoverServers, which identifies the tools relevant to the AI agent's task from a natural-language description of that task. This search is fundamentally different from typical document search: it must understand the semantic intent behind the request and match against tool capabilities, not just text content. An agent planning a weekend outdoors should find forecast tools, climate data APIs, and atmospheric sensors - not just servers with "weather" in their name.

Ranking fuses three signals: a dense semantic arm, a lexical arm (which is why searching by a provider's name still works — just put the name in the prompt), and a task-vocabulary arm that can surface a tool whose relevance the prompt never named directly. When it does, the entry carries a bridgeReason explaining the connection.

Discovery returns the following for each ranked action:

FieldDescription
Server / ToolThe provider and tool to invoke — pass both straight to callServer
ArgsPre-bound arguments, where discovery already knows them (an article's URL, say)
Tool SchemaThe full tool definition, so the agent can fill in any remaining arguments
PricingCost per invocation, in USD
Vital StatisticsCall volume, p90 latency and error rate, where the tool has been measured
Bridge ReasonWhy a tool is relevant when the prompt did not name it directly

This allows AI agents to make informed decisions - choosing the most accurate provider, the fastest data source, or the most cost-effective option - all without human intervention.

Quality Assurance

MCP Hive maintains quality through a multi-stage process:

  1. Probation Period - Newly registered MCP servers undergo an initial testing period of at least 72 hours. During probation, the server is validated for correctness and robustness before being made available to consumers.
  2. Continuous Monitoring - After activation, every interaction is logged and periodically analyzed. The Analyzer computes vital statistics - latency, accuracy, coverage, and error rate - that reflect real-world performance.
  3. Transparency - Vital statistics are exposed through the discovery tools, so AI agents and users can compare providers and make quality-driven choices.

Billing

MCP Hive handles billing transparently:

  • Interactions are logged throughout the month - Every call between consumers and providers is recorded with full metadata.
  • Billing is settled at the end of each monthly billing period - Consumers are charged based on their subscription plan and any pay-per-use costs incurred. Providers earn based on the volume and value of calls they have completed.
  • Pricing is always visible - During discovery, each tool's cost is displayed so there are no surprises.

Getting Started

Ready to connect? See the setup guides: