For MCP Clients

This guide explains how to use MCP Hive to access MCP servers through your AI applications.

What You'll Get

As an MCP Hive client, you can:

• Access multiple MCP servers through a single connection
• Discover new MCP tools and capabilities
• Pay only for what you use (per-call pricing) or pay a single monthly subscription

Quick Start

Getting started takes just three steps:

1. Obtain Credentials - Generate an API credential from the MCP Hive portal
2. Install mcpProxy - Install the proxy package from npm
3. Connect - Configure your AI application to use mcpProxy

Step 1: Obtain Credentials

Create an Account

1. Navigate to the MCP Hive portal
2. Click Get Started to create an account
3. Enter your email and password
4. Verify your email address

Generate a Credential

1. Log in to your MCP Hive account
2. Click Credentials in the sidebar
3. Click New Credential
4. Enter a name for your credential (e.g., "Claude Desktop", "Development")
5. Click Generate

Step 2: Install mcpProxy

mcpProxy is a local proxy that connects your AI applications to MCP Hive. Install it via npm:

npm install -g @mcp-hive-utils/proxy

Or run it directly with npx (no installation needed):

npx @mcp-hive-utils/proxy --help

Step 3: Choose Your Proxy Mode

mcpProxy supports two modes of operation:

Gateway Mode (Recommended)

Gateway mode gives you access to all MCP servers in MCP Hive through a single connection.

npx @mcp-hive-utils/proxy --gateway --credentials YOUR_CREDENTIAL_ID

Features:

• Automatic discovery of all available servers
• Tools are namespaced as serverName___toolName
• Built-in discovery tools to explore available capabilities
• One connection for everything

Discovery Tools in Gateway Mode:

Example Tool Names in Gateway Mode:

• weather___getWeather - The getWeather tool from the weather server
• code-analyzer___analyzeCode - The analyzeCode tool from code-analyzer
• discoverServers - Built-in tool (not namespaced)

Server Mode

Server mode connects to a specific MCP server only.

npx @mcp-hive-utils/proxy --server SERVER_NAME --credentials YOUR_CREDENTIAL_ID

Features:

• Direct access to a single server
• Tools use their original names (no namespacing)
• Simpler for single-server integrations
• Slightly lower latency

Example Tool Names in Server Mode:

• getWeather - Direct tool name
• analyzeCode - Direct tool name

CLI Options Reference

Note: If neither --gateway nor --server is specified, gateway mode is used by default.

Integration Examples

Claude Desktop

Add mcpProxy to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Gateway Mode Configuration

{
  "mcpServers": {
    "mcp-hive": {
      "command": "npx",
      "args": [
        "@mcp-hive-utils/proxy",
        "--gateway",
        "--credentials",
        "YOUR_CREDENTIAL_ID"
      ]
    }
  }
}

Server Mode Configuration

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "@mcp-hive-utils/proxy",
        "--server",
        "weather",
        "--credentials",
        "YOUR_CREDENTIAL_ID"
      ]
    }
  }
}

VSCode with Continue Extension

Configure mcpProxy in your Continue settings:

{
  "models": [...],
  "mcpServers": [
    {
      "name": "mcp-hive",
      "command": "npx",
      "args": [
        "@mcp-hive-utils/proxy",
        "--gateway",
        "--credentials",
        "YOUR_CREDENTIAL_ID"
      ]
    }
  ]
}

Exploring Available MCPs

Using the Portal

1. Log in to your MCP Hive account
2. Click Explore the Hive in the sidebar
3. Browse available MCP servers
4. View tools, pricing, and usage statistics

Using Discovery Tools (Gateway Mode)

In gateway mode, use the discoverServers tool to find what can help with the task at hand. Describe the task in natural language rather than guessing at keywords — the ranking reads the whole description:

Tool: discoverServers
Arguments: { "prompt": "research a private semiconductor startup: funding, hiring, patents" }

This returns rankedActions, most relevant first. Each entry is ready to hand straight to callServer:

• server, tool and args — the three arguments callServer takes
• toolSchema — the full tool definition, so you can fill in any missing args
• pricePerCall — cost to invoke, in USD
• verified — whether the provider has been verified
• stats — observed calls, latencyP90Usec and errors, when the tool has been measured
• bridgeReason — present when a tool is relevant for a reason the prompt did not name directly

Searching by name still works: put the name in the prompt.

Troubleshooting

"Credential not found" Error

• Verify you copied the credential ID correctly
• Check that the credential hasn't been revoked
• Ensure you're using the correct credential for your environment

"Server not found" Error (Server Mode)

• Check that the server name is spelled correctly
• Use discoverServers in gateway mode to see available server names
• The server may have been suspended or removed

Connection Issues

• Ensure you have an internet connection
• Check if a firewall is blocking outgoing connections
• Try running with --verbose for detailed logs

Tool Not Found

In gateway mode, remember that tools are namespaced:

• Wrong: getWeather
• Correct: weather___getWeather

Pricing and Usage

• Pricing is set per-call by each MCP provider, or set to a monthly subscription charge
• View per-call pricing on the Explore MCPs page
• Track your usage in the dashboard

Getting Help

If you need assistance:

• Check the Provider Documentation to understand how MCPs work
• Contact support through your MCP Hive dashboard
• Review the mcpProxy npm page