MCP Hero

Quick Overview

Connect your MCPHero servers to Claude Desktop (GUI) or Claude Code (CLI). Claude has native MCP support with OAuth 2.1 authentication, making it one of the most seamless MCP integrations available.

Claude Desktop supports full OAuth 2.1 authentication with PKCE, eliminating manual token management. Claude Code uses Bearer token authentication via command-line flags.

Prerequisites

Claude Desktop: Download from claude.ai/download (macOS, Windows, Linux)
Claude Code: Install via npm install -g @anthropic-ai/claude-code
An MCPHero server. Create one now.

Option 1: Claude Desktop (OAuth)

Claude Desktop supports OAuth 2.1 with PKCE, providing the most secure and user-friendly authentication experience.

Step 1: Get Your MCP Server URL

Navigate to your MCPHero dashboard and copy your server URL:

https://api.mcphero.app/mcp/{server_id}/mcp

Step 2: Open Claude Desktop Settings

Launch Claude Desktop
Click on the Claude menu (macOS) or File menu (Windows)
Select Settings → Developer → Edit Config

This opens your claude_desktop_config.json file.

Step 3: Add Your MCP Server

Add your MCPHero server to the configuration:

{
  "mcpServers": {
    "mcphero": {
      "url": "https://api.mcphero.app/mcp/{server_id}/mcp"
    }
  }
}

Save the file and restart Claude Desktop.

Step 4: Authorize the Connection

When Claude Desktop connects to your server:

A browser window opens to MCPHero's authorization page
Review the requested permissions
Click Authorize
Claude automatically receives and manages tokens

You'll see your MCP tools appear in Claude's tool picker (hammer icon).

Option 2: Claude Code (CLI)

Claude Code is Anthropic's official CLI for agentic coding. It supports MCP servers via the mcp add command.

Step 1: Get Your Server URL and API Key

From your MCPHero dashboard:

Copy the server URL
Generate or copy your API key from the Keys tab

Step 2: Add the MCP Server

Run this command, replacing the placeholders:

claude mcp add --transport http mcphero \
  https://api.mcphero.app/mcp/{server_id}/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

The server name (mcphero in this example) can be any identifier you choose.

Step 3: Verify the Connection

List your configured MCP servers:

claude mcp list

You should see your MCPHero server listed with its available tools.

Step 4: Use Your Tools

Start a Claude Code session and your MCP tools will be available:

claude

Claude Code will automatically discover and use your MCP tools when relevant to your task.

Option 3: Manual JSON Configuration

For Claude Desktop users who prefer direct config file editing.

Config File Locations

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

With OAuth (Recommended)

{
  "mcpServers": {
    "mcphero": {
      "url": "https://api.mcphero.app/mcp/{server_id}/mcp"
    }
  }
}

With Bearer Token

Use this if OAuth isn't working or you prefer explicit token management:

{
  "mcpServers": {
    "mcphero": {
      "url": "https://api.mcphero.app/mcp/{server_id}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Troubleshooting

Server Not Appearing

Restart Claude Desktop after config changes
Check JSON syntax - use a validator like jsonlint.com
Verify the URL - ensure it ends with /mcp

OAuth Flow Fails

Check your browser isn't blocking popups
Clear Claude Desktop's auth cache: Settings → Developer → Clear OAuth Tokens
Try Bearer token auth as a fallback

Tools Not Loading

Open Claude Desktop's developer console: View → Developer → Developer Tools
Check the Console tab for MCP connection errors
Verify your server is running on the MCPHero dashboard

Claude Code Connection Issues

# View detailed logs
claude mcp list --verbose

# Remove and re-add the server
claude mcp remove mcphero
claude mcp add --transport http mcphero https://api.mcphero.app/mcp/{server_id}/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Advanced: Multiple Servers

You can connect multiple MCP servers:

{
  "mcpServers": {
    "production": {
      "url": "https://api.mcphero.app/mcp/{prod_server_id}/mcp"
    },
    "staging": {
      "url": "https://api.mcphero.app/mcp/{staging_server_id}/mcp"
    },
    "local-dev": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

Claude will aggregate tools from all connected servers.

If you need to call MCP tools from a Python script rather than a desktop app, you can use the mcphero package with the native OpenAI or Google Gemini client libraries. See How to use MCP servers with openai python library for a full guide.

Claude