Server Management

Overview

MCPHub’s server management system allows you to centrally configure, monitor, and control multiple MCP (Model Context Protocol) servers from a single dashboard. All changes are applied in real-time without requiring server restarts.

Adding MCP Servers

MCPHub supports four upstream transports. Pick the one that matches your server before filling in the dashboard form (or the JSON body).

Transport (`type`)	Description	Key fields
`stdio` (default)	MCPHub launches a child process and talks MCP over stdio.	`command`, `args`, `env`
`sse`	Long-lived Server-Sent Events HTTP endpoint.	`url`, `headers`, `enableKeepAlive`, `keepAliveInterval`
`streamable-http`	MCP Streamable HTTP transport.	`url`, `headers`
`openapi`	Wraps an OpenAPI service so its operations appear as MCP tools.	`openapi.url` or `openapi.schema`, optional `headers`

Via Dashboard

Access the Dashboard: Navigate to http://localhost:3000 and log in.
Click “Add Server” and choose a transport.
Fill in the fields that apply to that transport. Common optional fields available on every transport: enabled, owner, description, passthroughHeaders, oauth, proxy. See MCP Settings for the full schema.

The server card menu also offers Duplicate, which opens the Add Server form prefilled with the source server’s configuration under the name <name>-copy; OAuth authorization state is not copied.

Via Configuration File

Edit your mcp_settings.json file. Examples for each transport:

{
  "mcpServers": {
    "fetch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": { "USER_AGENT": "MCPHub/1.0" }
    },
    "amap": {
      "type": "sse",
      "url": "https://mcp.amap.com/sse?key=${AMAP_API_KEY}"
    },
    "weather": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${WEATHER_TOKEN}" }
    },
    "stripe": {
      "type": "openapi",
      "openapi": { "url": "https://stripe.com/api/openapi.json" }
    }
  }
}

Via API

Use the REST API to add servers programmatically:

curl -X POST http://localhost:3000/api/servers \
  -H "Content-Type: application/json" \
  -H "x-auth-token: YOUR_JWT" \
  -d '{
    "name": "fetch-server",
    "config": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }'

Popular MCP Server Examples

Web Fetch Server

Provides web scraping and HTTP request capabilities:

{
  "fetch": {
    "command": "uvx",
    "args": ["mcp-server-fetch"]
  }
}

Available Tools:

fetch: Make HTTP requests
fetch_html: Scrape web pages
fetch_json: Get JSON data from APIs

Playwright Browser Automation

Browser automation for web interactions:

{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest", "--headless"]
  }
}

Available Tools:

playwright_navigate: Navigate to web pages
playwright_screenshot: Take screenshots
playwright_click: Click elements
playwright_fill: Fill forms

File System Operations

File and directory management:

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
  }
}

Available Tools:

read_file: Read file contents
write_file: Write to files
create_directory: Create directories
list_directory: List directory contents

SQLite Database

Database operations:

{
  "sqlite": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
  }
}

Available Tools:

execute_query: Execute SQL queries
describe_tables: Get table schemas
create_table: Create new tables

Slack Integration

Slack workspace integration:

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-your-bot-token",
      "SLACK_TEAM_ID": "T1234567890"
    }
  }
}

Available Tools:

send_slack_message: Send messages to channels
list_slack_channels: List available channels
get_slack_thread: Get thread messages

GitHub Integration

GitHub repository operations:

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
    }
  }
}

Available Tools:

create_or_update_file: Create/update repository files
search_repositories: Search GitHub repositories
create_issue: Create issues
create_pull_request: Create pull requests

Google Drive

Google Drive file operations:

{
  "gdrive": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-gdrive"],
    "env": {
      "GDRIVE_CLIENT_ID": "your-client-id",
      "GDRIVE_CLIENT_SECRET": "your-client-secret",
      "GDRIVE_REDIRECT_URI": "your-redirect-uri"
    }
  }
}

Available Tools:

gdrive_search: Search files and folders
gdrive_read: Read file contents
gdrive_create: Create new files

Amap Maps (China)

Chinese mapping and location services:

{
  "amap": {
    "command": "npx",
    "args": ["-y", "@amap/amap-maps-mcp-server"],
    "env": {
      "AMAP_MAPS_API_KEY": "your-api-key"
    }
  }
}

Available Tools:

search_location: Search for locations
get_directions: Get route directions
reverse_geocode: Convert coordinates to addresses

Copying a client configuration

Both server cards and group cards offer a copy action that opens a client preset dialog, so you can paste a ready-made configuration into your favorite MCP client:

Copy MCP config (group card menu): generates the configuration for the group’s aggregated endpoint (<baseUrl>/mcp/<group>), which multiplexes every server in the group behind one URL.
Copy (server card menu): wraps that server’s own stored configuration (its command/args/env for stdio servers, or its url/headers for HTTP/SSE servers) in the shape the selected client expects.

Servers backed by the openapi transport have no client-side transport of their own, so the dialog shows a “no transport” notice instead of presets; this is expected, not an error. Servers using the sse transport keep their "type": "sse" marker in the generated JSON (and the Claude Code command switches to --transport sse) so clients do not misdial them as streamable HTTP. The dialog provides presets for the following clients: Generic (mcpServers), Generic HTTP, Claude Code, Cursor, VS Code / Copilot, Codex, OpenCode, Windsurf, Cherry Studio, CodeBuddy Code, Qoder, TRAE, ZCode, and WorkBuddy. The Claude Code tab additionally offers a one-liner CLI command:

claude mcp add --transport http <name> <url> --header 'Authorization: Bearer <token>'

Values containing characters outside a safe CLI set are wrapped in single quotes (as the header above is), so the command can be pasted verbatim into a POSIX shell; on Windows shells that do not parse single quotes, re-quote the affected values. A few clients use their own key names in the generated configuration: Codex uses http_headers (there is no headers key), VS Code uses servers plus a type field, and Cherry Studio uses baseUrl with a type of streamableHttp — or sse when the upstream is an SSE endpoint.

Server Lifecycle Management

Starting Servers

Servers are automatically started when:

MCPHub boots up
A server is added via the dashboard or API
A server configuration is updated
A stopped server is manually restarted

Stopping Servers

You can stop servers:

Via Dashboard: Toggle the server status switch
Via API: Send a POST request to /api/servers/{name}/toggle
Automatically: Servers stop if they crash or encounter errors

Restarting Servers

Servers are automatically restarted:

When configuration changes are made
After environment variable updates
When manually triggered via dashboard or API

Server Status Monitoring

Status Indicators

Each server displays a status indicator:

🟢 Running: Server is active and responding
🟡 Starting: Server is initializing
🔴 Stopped: Server is not running
⚠️ Error: Server encountered an error

Real-time Logs

View server logs in real-time:

Dashboard Logs: Click on a server to view its logs
API Logs: Access logs via /api/logs endpoint
Streaming Logs: Subscribe to log streams via WebSocket

Health Checks

MCPHub automatically performs health checks:

Initialization Check: Verifies server starts successfully
Tool Discovery: Confirms available tools are detected
Response Check: Tests server responsiveness
Resource Monitoring: Tracks CPU and memory usage

Configuration Management

Environment Variables

Servers can use environment variables for configuration:

{
  "server-name": {
    "command": "python",
    "args": ["server.py"],
    "env": {
      "API_KEY": "${YOUR_API_KEY}",
      "DEBUG": "true",
      "MAX_CONNECTIONS": "10"
    }
  }
}

Environment Variable Expansion:

${VAR_NAME}: Expands to environment variable value
${VAR_NAME:-default}: Uses default if variable not set
${VAR_NAME:+value}: Uses value if variable is set

Command Variations

Different ways to specify server commands:

npm/npx
Python/uvx

{
  "npm-server": {
    "command": "npx",
    "args": ["-y", "package-name", "--option", "value"]
  }
}

{
  "python-server": {
    "command": "uvx",
    "args": ["package-name", "--config", "config.json"]
  }
}

Advanced Features

Hot Reloading

MCPHub supports hot reloading of server configurations:

Dashboard Updates: Immediately applies changes made through the web interface
API Updates: Real-time updates via REST API calls
Zero Downtime: Graceful server restarts without affecting other servers

Troubleshooting

Server Won't Start

Check the following:

Command is available in PATH
All required environment variables are set
Working directory exists and is accessible
Network ports are not blocked
Dependencies are installed

Debug steps:

Check server logs in the dashboard
Test command manually in terminal
Verify environment variable expansion
Check file permissions

Server Keeps Crashing

Common causes:

Invalid configuration parameters
Missing API keys or credentials
Resource limits exceeded
Dependency conflicts

Solutions:

Review server logs for error messages
Test with minimal configuration
Verify all credentials and API keys
Check system resource availability

Tools Not Appearing

Possible issues:

Server not fully initialized
Tool discovery timeout
Communication protocol mismatch
Server reporting errors

Debug steps:

Wait for server initialization to complete
Check server logs for tool registration messages
Test direct communication with server
Verify MCP protocol compatibility

Next Steps

Group Management

Organize servers into logical groups

Smart Routing

Set up AI-powered tool discovery

API Reference

Server management API documentation

Configuration Guide

Detailed configuration options

Get Started

Core Features

Configuration

Development

Overview

Adding MCP Servers

Via Dashboard

Via Configuration File

Via API

Popular MCP Server Examples

Copying a client configuration

Server Lifecycle Management

Starting Servers

Stopping Servers

Restarting Servers

Server Status Monitoring

Status Indicators

Real-time Logs

Health Checks

Configuration Management

Environment Variables

Command Variations

Advanced Features

Hot Reloading

Troubleshooting

Next Steps

Group Management

Smart Routing

API Reference

Configuration Guide

​Overview

​Adding MCP Servers

​Via Dashboard

​Via Configuration File

​Via API

​Popular MCP Server Examples

​Copying a client configuration

​Server Lifecycle Management

​Starting Servers

​Stopping Servers

​Restarting Servers

​Server Status Monitoring

​Status Indicators

​Real-time Logs

​Health Checks

​Configuration Management

​Environment Variables

​Command Variations

​Advanced Features

​Hot Reloading

​Troubleshooting

​Next Steps

Group Management

Smart Routing

API Reference

Configuration Guide

Overview

Adding MCP Servers

Via Dashboard

Via Configuration File

Via API

Popular MCP Server Examples

Copying a client configuration

Server Lifecycle Management

Starting Servers

Stopping Servers

Restarting Servers

Server Status Monitoring

Status Indicators

Real-time Logs

Health Checks

Configuration Management

Environment Variables

Command Variations

Advanced Features

Hot Reloading

Troubleshooting

Next Steps