### Build and Start MCPHub for Production

Source: https://docs.mcphub.app/installation

Build the backend and frontend for production and then start the production server. Use these commands after cloning and installing dependencies.

```bash
# Build both backend and frontend
pnpm build

# Start production server
pnpm start
```

--------------------------------

### Set Up Development Environment

Source: https://docs.mcphub.app/development/contributing

Follow these bash commands to clone the repository, install dependencies, configure the environment, and start the development server and database.

```bash
# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/mcphub.git
cd mcphub

# 2. Add upstream remote
git remote add upstream https://github.com/samanhappy/mcphub.git

# 3. Install dependencies
pnpm install

# 4. Set up environment
cp .env.example .env.development

# 5. Start development environment
docker-compose -f docker-compose.dev.yml up -d
pnpm run migrate
pnpm run seed

# 6. Start development server
pnpm run dev
```

--------------------------------

### Pre-installation Scripts for Server Setup

Source: https://docs.mcphub.app/features/server-management

Define scripts to run before a server starts, ensuring all necessary setup is complete. Useful for installing project dependencies or running initial configurations.

```json
{
  "setup-server": {
    "preStart": ["npm install", "pip install -r requirements.txt"],
    "command": "python",
    "args": ["server.py"]
  }
}
```

--------------------------------

### Setup PostgreSQL Database Manually

Source: https://docs.mcphub.app/configuration/database-configuration

Commands to install PostgreSQL and create a new database and user for MCPHub. This is part of the manual setup process.

```bash
# Install PostgreSQL (if not already installed)
sudo apt-get install postgresql postgresql-contrib

# Create database and user
sudo -u postgres psql <<EOF
CREATE DATABASE mcphub;
CREATE USER mcphub WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE mcphub TO mcphub;
EOF
```

--------------------------------

### Install Server to File with mcphub install

Source: https://docs.mcphub.app/features/cli

Install a server directly into a client-side configuration file using `mcphub install --to file`. This method ensures atomic writes to prevent corruption.

```bash
# Install into a Claude Desktop / OpenClaw-style config file
mcphub install amap-maps --to file --out ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

--------------------------------

### Install Server into Active Hub with mcphub install

Source: https://docs.mcphub.app/features/cli

Install a server into the active hub using `mcphub install`. Environment variables can be provided using the `--env` flag. A dry run can be performed with `--dry-run` to preview the installation.

```bash
# Install into the active hub (POST /api/servers)
mcphub install amap-maps --env AMAP_MAPS_API_KEY=...
```

```bash
# Install from a different hub into the active one
mcphub install some-server --remote https://hub.example.com --yes
```

```bash
# Dry-run: just print the mcpServers snippet
mcphub install amap-maps --dry-run
```

--------------------------------

### Start MCPHub Manually

Source: https://docs.mcphub.app/configuration/database-configuration

Execute this command to start the MCPHub application after manual setup and configuration. It will use the environment variables defined.

```bash
mcphub
```

--------------------------------

### Start the MCPHub Server (Legacy)

Source: https://docs.mcphub.app/features/cli

Invoke mcphub with no arguments to start the server using its original behavior.

```bash
mcphub                            # legacy: start the server (unchanged)
```

--------------------------------

### Run MCPHub with Docker (Default)

Source: https://docs.mcphub.app/quickstart

Use this command to quickly start MCPHub with its default configuration using Docker. Ensure Docker is installed and running.

```bash
docker run -p 3000:3000 samanhappy/mcphub
```

--------------------------------

### Auto-install Server Dependencies

Source: https://docs.mcphub.app/features/server-management

Configure MCPHub to automatically install specified packages before starting a server. Use this when a dependency might not be present.

```json
{
  "auto-install-server": {
    "command": "npx",
    "args": ["-y", "package-that-might-not-exist"],
    "autoInstall": true
  }
}
```

--------------------------------

### Example MCP Settings Configuration

Source: https://docs.mcphub.app/configuration/mcp-settings

Provides example configurations for different MCP servers like fetch, playwright, and slack, including specific commands, arguments, and environment variables.

```json
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "USER_AGENT": "MCPHub/1.0"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}
```

--------------------------------

### Action-Oriented Query Example

Source: https://docs.mcphub.app/features/smart-routing

Use action-oriented queries to find tools that perform specific actions. This example searches for tools to create files and upload them to GitHub.

```bash
# Specific actions
curl -X POST http://localhost:3000/mcp/$smart \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/search",
    "params": {
      "query": "create file upload to github repository"
    }
  }'
```

--------------------------------

### Install MCPHub Globally

Source: https://docs.mcphub.app/configuration/database-configuration

Install the MCPHub package globally using npm. This command is used during the manual setup process.

```bash
npm install -g @samanhappy/mcphub
```

--------------------------------

### Install Project Dependencies

Source: https://docs.mcphub.app/development/getting-started

Install all necessary project dependencies using pnpm, the recommended package manager for this project.

```bash
pnpm install
```

--------------------------------

### Example stdio MCP Server Configuration

Source: https://docs.mcphub.app/quickstart

Configure an MCP server using the 'stdio' type, which runs the server as a local process. This example shows how to specify the command and arguments.

```json
{
  "name": "fetch",
  "config": { "type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"] }
}
```

--------------------------------

### Context-Aware Query Example

Source: https://docs.mcphub.app/features/smart-routing

Enhance tool searches by including context such as project details, technologies, and environment. This example searches for automated testing tools for a React/Node.js e-commerce website in staging.

```bash
# Include context for better results
curl -X POST http://localhost:3000/mcp/$smart \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/search",
    "params": {
      "query": "automated testing web application",
      "context": {
        "project": "e-commerce website",
        "technologies": ["React", "Node.js"],
        "environment": "staging"
      }
    }
  }'
```

--------------------------------

### Install Dependencies for Local Development

Source: https://docs.mcphub.app/installation

Install project dependencies using pnpm, npm, or yarn. pnpm is recommended for local development.

```bash
# Install dependencies with pnpm (recommended)
pnpm install

# Or with npm
npm install

# Or with yarn
yarn install
```

--------------------------------

### Login Request Example

Source: https://docs.mcphub.app/api-reference/auth

Provides an example of the JSON payload required to authenticate a user. Use this to send username and password for login.

```json
{
  "username": "admin",
  "password": "your-admin-password"
}
```

--------------------------------

### Start MCPHub in Development Mode

Source: https://docs.mcphub.app/installation

Start both the backend and frontend of MCPHub in development mode using pnpm. The backend runs on port 3000 and the frontend on port 5173.

```bash
# Start both backend and frontend in development mode
pnpm dev

# This will start:
# - Backend on http://localhost:3000
# - Frontend on http://localhost:5173
# - Frontend proxies API calls to backend
```

--------------------------------

### Start Production Environment

Source: https://docs.mcphub.app/configuration/docker-setup

Commands to manage the production Docker environment. Use 'up -d' to start in detached mode, 'logs -f' to follow logs, and 'down' to stop.

```bash
# Start production environment
docker-compose up -d

# View logs
docker-compose logs -f mcphub

# Stop production environment
docker-compose down
```

--------------------------------

### Run Frontend Development Server

Source: https://docs.mcphub.app/development/getting-started

Starts only the frontend development server.

```bash
pnpm frontend:dev
```

--------------------------------

### Get Current User Success Response Example

Source: https://docs.mcphub.app/api-reference/auth

Example of the response when retrieving the current authenticated user's profile. Requires Bearer Token authentication.

```json
{
  "success": true,
  "user": {
    "username": "admin",
    "isAdmin": true,
    "permissions": { ... }
  }
}
```

--------------------------------

### Configure Environment Variables

Source: https://docs.mcphub.app/development/getting-started

Copy the example environment file and populate it with your specific configuration details for the server, database, JWT, and OpenAI API.

```bash
cp .env.example .env
```

```env
# Server Configuration
PORT=3000
NODE_ENV=development

# Database Configuration
DB_URL=postgresql://username:password@localhost:5432/mcphub

# JWT Configuration
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=24h

# OpenAI Configuration (for smart routing)
OPENAI_API_KEY=your-openai-api-key
```

--------------------------------

### Install MCPHub using npx or Fix npm Permissions

Source: https://docs.mcphub.app/installation

If you encounter permission errors during npm installation, use npx for a temporary execution or configure npm to install globally in a user-writable directory.

```bash
# Use npx instead of global install
npx @samanhappy/mcphub

# Or fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```

--------------------------------

### Start Development Environment

Source: https://docs.mcphub.app/configuration/docker-setup

Commands to manage the development Docker environment. Use 'up -d' to start in detached mode, 'logs -f' to follow logs, and 'down' to stop.

```bash
# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f mcphub-dev

# Stop development environment
docker-compose -f docker-compose.dev.yml down
```

--------------------------------

### Start Docker Compose Services

Source: https://docs.mcphub.app/configuration/database-configuration

Execute this command in the directory containing your docker-compose.yml file to start both the PostgreSQL and MCPHub services in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Install and Run MCPHub as an npm Package

Source: https://docs.mcphub.app/quickstart

Install MCPHub globally using npm to run it as a command-line application. This is a convenient way to use MCPHub without Docker.

```bash
npm install -g @samanhappy/mcphub

mcphub
```

--------------------------------

### Full Environment Variable Example for Local OIDC

Source: https://docs.mcphub.app/configuration/environment-variables

This example demonstrates how to configure Better Auth using only environment variables for a local OIDC provider. It includes settings for enabling Better Auth, specifying its URL and base path, defining trusted origins, and configuring the OIDC provider with discovery URL, scopes, PKCE, prompt, and client credentials.

```env
BETTER_AUTH_ENABLED=true
BETTER_AUTH_URL=https://mcphub.example.com
BETTER_AUTH_BASE_PATH=/api/auth/better
BETTER_AUTH_TRUSTED_ORIGINS=https://dashboard.example.com,https://admin.example.com

BETTER_AUTH_OIDC_ENABLED=true
BETTER_AUTH_OIDC_PROVIDER_ID=local-oidc
BETTER_AUTH_OIDC_DISCOVERY_URL=https://auth.example.com/.well-known/openid-configuration
BETTER_AUTH_OIDC_SCOPES=openid,profile,email
BETTER_AUTH_OIDC_PKCE=true
BETTER_AUTH_OIDC_PROMPT=login
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
```

--------------------------------

### Example SSE MCP Server Configuration

Source: https://docs.mcphub.app/quickstart

Configure an MCP server using the 'sse' type for servers reachable over HTTP/SSE. This example includes a placeholder for your API key.

```json
{
  "name": "amap",
  "config": { "type": "sse", "url": "https://mcp.amap.com/sse?key=YOUR_KEY" }
}
```

--------------------------------

### Development Dockerfile

Source: https://docs.mcphub.app/configuration/docker-setup

Builds the Docker image for the development environment. It installs pnpm, sets up the working directory, installs dependencies, copies source code, and exposes necessary ports.

```dockerfile
FROM node:20-alpine

# Install pnpm
RUN npm install -g pnpm

# Set working directory
WORKDIR /app

# Copy package files
COPY package.json pnpm-lock.yaml ./
COPY frontend/package.json ./frontend/

# Install dependencies
RUN pnpm install

# Copy source code
COPY . .

# Expose ports
EXPOSE 3000 5173 9229

# Start development server
CMD ["pnpm", "dev"]
```

--------------------------------

### Run Backend Development Server

Source: https://docs.mcphub.app/development/getting-started

Starts only the backend server in development mode.

```bash
pnpm backend:dev
```

--------------------------------

### Get All Groups Response

Source: https://docs.mcphub.app/api-reference/groups

Example of a successful response when retrieving a list of all server groups. It includes group IDs, names, descriptions, associated servers, and owner information.

```json
{
  "success": true,
  "data": [
    {
      "id": "group-1",
      "name": "My Group",
      "description": "A collection of servers.",
      "servers": ["server1", "server2"],
      "owner": "admin"
    }
  ]
}
```

--------------------------------

### Get All Logs Response

Source: https://docs.mcphub.app/api-reference/logs

Example of a successful response when retrieving all logs. This includes a list of log entries, each with a timestamp, level, message, and service.

```json
{
  "success": true,
  "data": [
    {
      "timestamp": "2023-10-27T10:00:00.000Z",
      "level": "info",
      "message": "Server started successfully.",
      "service": "system"
    }
  ]
}
```

--------------------------------

### Upload MCPB File Request Example

Source: https://docs.mcphub.app/api-reference/system

Example of uploading a MCPB bundle file using curl. Requires authentication.

```bash
curl -X POST "http://localhost:3000/api/mcpb/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "mcpbFile=@bundle.mcpb"
```

--------------------------------

### Run Development Server

Source: https://docs.mcphub.app/development/getting-started

Starts both the backend and frontend development servers simultaneously. The backend runs on http://localhost:3000 and the frontend on http://localhost:5173.

```bash
pnpm dev
```

--------------------------------

### Export MCP Settings Request Example

Source: https://docs.mcphub.app/api-reference/system

Example of exporting MCP settings as a JSON file using curl. Requires authentication.

```bash
curl "http://localhost:3000/api/mcp-settings/export" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o mcp_settings.json
```

--------------------------------

### Register Request Example

Source: https://docs.mcphub.app/api-reference/auth

Shows the JSON payload for registering a new user. Include username, password, and optionally isAdmin status.

```json
{
  "username": "newuser",
  "password": "password123",
  "isAdmin": false
}
```

--------------------------------

### Task-Based Query Example

Source: https://docs.mcphub.app/features/smart-routing

Use task-based queries to find tools based on a desired accomplishment. This example searches for tools related to sending a Slack message.

```bash
# What you want to accomplish
curl -X POST http://localhost:3000/mcp/$smart \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/search",
    "params": {
      "query": "send a message to a slack channel"
    }
  }'
```

--------------------------------

### Domain-Specific Query Example

Source: https://docs.mcphub.app/features/smart-routing

Use domain-specific queries to find tools related to a particular technology or area. This example searches for tools for database operations.

```bash
# Specific domain or technology
curl -X POST http://localhost:3000/mcp/$smart \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/search",
    "params": {
      "query": "database operations SQL queries"
    }
  }'
```

--------------------------------

### Example cURL Request to Call a Tool

Source: https://docs.mcphub.app/api-reference/tools

An example of how to use cURL to make a POST request to the /api/tools/call/:server endpoint. Ensure you replace YOUR_TOKEN with your actual authentication token.

```bash
curl -X POST "http://localhost:3000/api/tools/call/amap" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "toolName": "amap-maps_weather",
    "arguments": {
      "city": "Beijing"
    }
  }'
```

--------------------------------

### Get All Server Settings

Source: https://docs.mcphub.app/api-reference/servers

Retrieves all server settings, including server lists, groups, and system configurations. This endpoint is useful for getting a comprehensive overview of the system's current state.

```json
{
  "success": true,
  "data": {
    "servers": [...],
    "groups": [...],
    "systemConfig": {...}
  }
}
```

--------------------------------

### Run MCPHub with Docker

Source: https://docs.mcphub.app/

Starts an MCPHub instance using Docker, exposing port 3000. Access the dashboard at http://localhost:3000.

```bash
docker run -p 3000:3000 samanhappy/mcphub

```

--------------------------------

### Run MCPHub with Docker and Custom Configuration

Source: https://docs.mcphub.app/

Starts an MCPHub instance with Docker, mounting a custom configuration file and exposing port 3000. Access the dashboard at http://localhost:3000.

```bash
docker run -p 3000:3000 -v $(pwd)/mcp_settings.json:/app/mcp_settings.json samanhappy/mcphub

```

--------------------------------

### Unit Tests for MCPService

Source: https://docs.mcphub.app/development/contributing

Example unit tests for the MCPService, covering successful server startup and failure scenarios.

```typescript
// src/services/__tests__/mcpService.test.ts
import { MCPService } from '../mcpService';
import { mockLogger, mockDatabase } from '../../__mocks__';

describe('MCPService', () => {
  let service: MCPService;

  beforeEach(() => {
    service = new MCPService(mockLogger, mockDatabase);
  });

  describe('startServer', () => {
    it('should start a server successfully', async () => {
      const config = {
        name: 'test-server',
        command: 'node',
        args: ['server.js'],
      };

      await service.startServer(config);

      expect(service.getServerStatus('test-server')).toBe('running');
    });

    it('should handle server startup failures', async () => {
      const invalidConfig = {
        name: 'invalid-server',
        command: 'invalid-command',
        args: [],
      };

      await expect(service.startServer(invalidConfig)).rejects.toThrow(
        'Failed to start server: Command not found',
      );
    });
  });
});

```

--------------------------------

### Get a Server

Source: https://docs.mcphub.app/api-reference/servers

Returns the configuration of a single server, including upstream tools/prompts/resources when connected.

```APIDOC
## GET /api/servers/:name

### Description
Returns the configuration of a single server, including upstream tools/prompts/resources when connected.

### Method
GET

### Endpoint
/api/servers/:name

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the server to retrieve.
```

--------------------------------

### Get Settings

Source: https://docs.mcphub.app/api-reference/servers

Retrieves all server settings and configurations, including server lists, group information, and system configuration details.

```APIDOC
## GET /api/settings

### Description
Retrieves all server settings and configurations.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the retrieved settings.
  - **servers** (array) - List of servers.
  - **groups** (array) - List of groups.
  - **systemConfig** (object) - System configuration details.

#### Response Example
```json
{
  "success": true,
  "data": {
    "servers": [...],
    "groups": [...],
    "systemConfig": {...}
  }
}
```

**Note**: For prompt and resource management not tied to an upstream server, see the [Prompts API](/api-reference/prompts) documentation.
```

--------------------------------

### Execute Tool via GET Request

Source: https://docs.mcphub.app/api-reference/openapi

Execute an MCP tool using a GET request. Parameters are passed as query parameters. Ensure the tool and server names are correctly specified in the path.

```bash
curl "http://localhost:3000/api/tools/amap/amap-maps_weather?city=Beijing"
```

--------------------------------

### Migrate Existing Settings to Database

Source: https://docs.mcphub.app/configuration/database-configuration

Run this command to migrate your existing mcp_settings.json file to the PostgreSQL database. This is an optional step before starting MCPHub.

```bash
# Run migration script
npx tsx src/scripts/migrate-to-database.ts
```

--------------------------------

### Check System Performance

Source: https://docs.mcphub.app/features/smart-routing

Retrieve system performance metrics by making a GET request to the performance endpoint.

```bash
# Check system performance
curl http://localhost:3000/api/smart-routing/performance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Pull and Run MCPHub Docker Image

Source: https://docs.mcphub.app/installation

Pull the latest MCPHub Docker image and run it with default settings. This is the basic Docker installation.

```bash
docker pull samanhappy/mcphub:latest

docker run -d \
  --name mcphub \
  -p 3000:3000 \
  samanhappy/mcphub:latest
```

--------------------------------

### Deploy MCPHub with Nginx Configuration

Source: https://docs.mcphub.app/configuration/nginx

A sequence of bash commands to deploy a production-ready Nginx configuration for MCPHub. This involves copying an example file, editing it, enabling the site, and testing/reloading Nginx.

```bash
# Copy the example configuration
cp nginx.conf.example /etc/nginx/sites-available/mcphub

# Update the configuration with your domain and paths
sudo nano /etc/nginx/sites-available/mcphub

# Enable the site
sudo ln -s /etc/nginx/sites-available/mcphub /etc/nginx/sites-enabled/

# Test and reload
sudo nginx -t && sudo systemctl reload nginx
```

--------------------------------

### Build Project

Source: https://docs.mcphub.app/development/getting-started

Compiles and bundles both the backend and frontend applications for production.

```bash
pnpm build
```

--------------------------------

### Build MCPHub from Source and Run

Source: https://docs.mcphub.app/configuration/docker-setup

Clones the MCPHub repository, builds a local Docker image, and then runs the container, mapping port 3000 and mounting a settings file.

```bash
git clone https://github.com/your-username/mcphub.git
cd mcphub

docker build -t mcphub:local .

docker run -d \
  --name mcphub \
  -p 3000:3000 \
  -v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
  mcphub:local
```

--------------------------------

### Get Runtime Config

Source: https://docs.mcphub.app/api-reference/config

Get public runtime configuration for the frontend.

```APIDOC
## GET /config

### Description
Get public runtime configuration for the frontend.

### Method
GET

### Endpoint
/config
```

--------------------------------

### Basic Proxy Configuration for MCPHub Servers

Source: https://docs.mcphub.app/configuration/mcp-settings

Enables routing network traffic through a SOCKS5 proxy for a specified MCPHub server. Requires proxychains4 to be installed.

```json
{
  "mcpServers": {
    "fetch-via-proxy": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "proxy": {
        "enabled": true,
        "type": "socks5",
        "host": "127.0.0.1",
        "port": 1080
      }
    }
  }
}
```

--------------------------------

### Get Public Config

Source: https://docs.mcphub.app/api-reference/config

Get public configuration to check for auth skip.

```APIDOC
## GET /public-config

### Description
Get public configuration to check for auth skip.

### Method
GET

### Endpoint
/public-config
```

--------------------------------

### Get All Settings

Source: https://docs.mcphub.app/api-reference/config

Retrieves the entire settings object for the instance, including all server configurations, groups, and system settings. This is a comprehensive dump of the `mcp_settings.json` file.

```APIDOC
## GET /api/settings

### Description
Retrieves the entire settings object for the instance, including all server configurations, groups, and system settings. This is a comprehensive dump of the `mcp_settings.json` file.

### Method
GET

### Endpoint
/api/settings
```

--------------------------------

### Run MCPHub from npm Package

Source: https://docs.mcphub.app/installation

Execute the MCPHub command after installing it as a global npm package. Allows specifying a custom port.

```bash
# Run with default settings
mcphub

# Run with custom port
PORT=8080 mcphub
```

--------------------------------

### GET /api/users/:username

Source: https://docs.mcphub.app/api-reference/users

Get a single user by username. Returns `404` if the user does not exist.

```APIDOC
## GET /api/users/:username

### Description
Get a single user by username. Returns `404` if the user does not exist.

### Method
GET

### Endpoint
/api/users/:username

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the user to retrieve.

### Authentication
Required (admin only)

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object) - User object with `username` and `isAdmin` fields.

### Response Example
```json
{
  "success": true,
  "data": { "username": "alice", "isAdmin": false }
}
```
```

--------------------------------

### Register Success Response Example

Source: https://docs.mcphub.app/api-reference/auth

Details the response received after successfully registering a new user. It contains a JWT token and user information.

```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "username": "newuser",
    "isAdmin": false,
    "permissions": { ... }
  }
}
```

--------------------------------

### Health Check Response Example

Source: https://docs.mcphub.app/api-reference/system

Example of a successful response from the /health endpoint, indicating server status.

```json
{
  "status": "ok",
  "timestamp": "2024-11-12T01:30:00.000Z",
  "uptime": 12345
}
```

--------------------------------

### System Configuration

Source: https://docs.mcphub.app/api-reference/servers

Manages system-wide configuration settings including routing, installation, smart routing, MCP router, name separator, session rebuild, and OAuth server.

```APIDOC
## PUT /api/system-config

### Description
Manages system-wide configuration settings. This endpoint allows for the update of various system parameters.

### Method
PUT

### Endpoint
/api/system-config

### Request Body
Refer to the [System Config API](/api-reference/config) documentation for the full request schema and accepted top-level keys (`routing`, `install`, `smartRouting`, `mcpRouter`, `nameSeparator`, `enableSessionRebuild`, `oauthServer`).

**Note**: The legacy `openaiApiKey`, `modelName`, `temperature`, and `maxTokens` are no longer accepted. Smart-routing model selection is now nested under the `smartRouting` object.
```

--------------------------------

### Docker Compose Setup for MCPHub and PostgreSQL

Source: https://docs.mcphub.app/configuration/database-configuration

Define a docker-compose.yml file to run PostgreSQL as a separate service alongside MCPHub. This configuration manages both services and their dependencies.

```yaml
version: '3.8' 

services:
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_DB: mcphub
      POSTGRES_USER: mcphub
      POSTGRES_PASSWORD: your_secure_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  mcphub:
    image: samanhappy/mcphub:latest
    environment:
      USE_DB: "true"
      DB_URL: "postgresql://mcphub:your_secure_password@postgres:5432/mcphub"
      PORT: 3000
    ports:
      - "3000:3000"
    depends_on:
      - postgres 

volumes:
  pgdata:
```

--------------------------------

### List, Get, Add, Remove, Toggle, and Reload Servers

Source: https://docs.mcphub.app/features/cli

Commands for managing server configurations, including listing, retrieving details, adding new servers from files or inline arguments, removing them, toggling their status, and reloading their configurations.

```bash
mcphub servers list
mcphub servers get <name>

# Add from a JSON file:
mcphub servers add fetch --from-file ./fetch.json

# Or inline (--arg / --env can repeat):
mcphub servers add fetch \
  --type stdio --command uvx \
  --arg mcp-server-fetch \
  --env USER_AGENT=mcphub

mcphub servers remove fetch
mcphub servers toggle fetch --on
mcphub servers reload fetch
```

--------------------------------

### Test Database Connection and pgvector Extension

Source: https://docs.mcphub.app/installation

Verify your database connection and ensure the pgvector extension is installed. These commands are useful for troubleshooting Smart Routing issues.

```bash
# Test database connection
psql $DB_URL -c "SELECT 1;"

# Check if pgvector is installed
psql $DB_URL -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

--------------------------------

### Login Success Response Example

Source: https://docs.mcphub.app/api-reference/auth

Illustrates the structure of a successful login response, including the JWT token and user details. This response is returned after successful authentication.

```json
{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "username": "admin",
    "isAdmin": true,
    "permissions": { ... }
  }
}
```

--------------------------------

### Test Nginx Configuration Syntax

Source: https://docs.mcphub.app/configuration/nginx

Tests the Nginx configuration files for syntax errors before applying changes. This is a crucial step to prevent Nginx from failing to start.

```bash
sudo nginx -t
```

--------------------------------

### List All CLI Subcommands

Source: https://docs.mcphub.app/features/cli

Use the --help flag to list all available subcommands for the mcphub CLI.

```bash
mcphub --help                    # list every subcommand
```

--------------------------------

### Docker Compose Performance Optimization

Source: https://docs.mcphub.app/configuration/docker-setup

Configure resource limits and reservations for your services in Docker Compose to optimize performance. This example sets memory and CPU constraints for the mcphub service.

```yaml
services:
  mcphub:
    # ... other config
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 256M
          cpus: '0.25'
```

--------------------------------

### MCP Server Configurations

Source: https://docs.mcphub.app/features/server-management

Examples of different MCP server configurations using various upstream transports (stdio, sse, streamable-http, openapi) within a JSON settings file.

```json
{
  "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" }
    }
  }
}
```

--------------------------------

### Test Server Command Manually

Source: https://docs.mcphub.app/configuration/mcp-settings

Use this command to manually test your server's startup command and arguments during troubleshooting. It helps verify that the server executable and its parameters are correct.

```bash
# Test command manually
uvx mcp-server-fetch
```

--------------------------------

### Environment Variable Substitution in MCPHub Configuration

Source: https://docs.mcphub.app/configuration/mcp-settings

Demonstrates how to use environment variables for dynamic configuration values like API keys and URLs.

```json
{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_URL": "${API_BASE_URL}/v1"
      }
    }
  }
}
```

--------------------------------

### Browse Marketplace with mcphub discover

Source: https://docs.mcphub.app/features/cli

Use `mcphub discover` to search for servers, view details, and list categories or tags available in the marketplace. The `--search` flag filters results, and `--limit` controls the number of items returned.

```bash
# Browse the active profile's hub
mcphub discover --search github --limit 10
mcphub discover info amap-maps
mcphub discover categories
mcphub discover tags
```

--------------------------------

### Conventional Commits Examples

Source: https://docs.mcphub.app/development/contributing

Examples of commit messages following the Conventional Commits specification for various types of changes like features, bug fixes, documentation, and refactoring.

```bash
# Format: <type>[optional scope]: <description>

# Features
git commit -m "feat(auth): add JWT token refresh functionality"
git commit -m "feat(ui): implement server status dashboard"

# Bug fixes
git commit -m "fix(api): resolve memory leak in server manager"
git commit -m "fix(db): handle connection timeout gracefully"

# Documentation
git commit -m "docs(api): add examples for server endpoints"
git commit -m "docs(readme): update installation instructions"

# Refactoring
git commit -m "refactor(services): extract auth logic into separate module"

# Tests
git commit -m "test(api): add integration tests for server management"

# Chores
git commit -m "chore(deps): update dependencies to latest versions"
```

--------------------------------

### Server Configuration with Environment Variables

Source: https://docs.mcphub.app/features/server-management

Defines a server configuration including its command, arguments, and environment variables. Useful for setting up server-specific configurations.

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

--------------------------------

### Discover and Inspect Tools

Source: https://docs.mcphub.app/features/cli

Commands to discover available tools, their parameters, and the servers that host them. Includes options to list all tools, filter by server or enabled status, and get detailed information including schemas and sample commands.

```bash
# Flat list of every tool across every connected server.
mcphub tools list
mcphub tools list --json                       # machine-readable, no schemas
mcphub tools list --schema --json              # include each tool's inputSchema
mcphub tools list --server fetch               # scope to one server
mcphub tools list --enabled-only

# Inspect one tool: description, parameter table, full input schema, sample command.
mcphub tools get fetch_url
mcphub tools get fetch_url --server fetch      # disambiguate when two servers expose the same name
mcphub tools schema fetch_url                  # alias for `get`
```

--------------------------------

### Example Generated OpenAPI Operation

Source: https://docs.mcphub.app/api-reference/openapi

This YAML snippet shows an example of a generated OpenAPI operation for a weather tool, including its summary, operation ID, tags, parameters, and responses.

```yaml
/tools/amap/amap-maps_weather:
  get:
    summary: "根据城市名称或者标准adcode查询指定城市的天气"
    operationId: "amap_amap-maps_weather"
    tags: ["amap"]
    parameters:
      - name: city
        in: query
        required: true
        description: "城市名称或者adcode"
        schema:
          type: string
    responses:
      '200':
        description: "Successful tool execution"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolResponse'
```

--------------------------------

### Set Appropriate Timeouts and Restarts

Source: https://docs.mcphub.app/configuration/mcp-settings

Configure server timeouts and restart policies to manage server responsiveness and resilience. This example sets a timeout of 30 seconds and allows up to 3 restarts with a 5-second delay between them.

```json
{
  "timeout": 30000,
  "maxRestarts": 3,
  "restartDelay": 5000
}
```

--------------------------------

### Build MCPHub with Extended Features

Source: https://docs.mcphub.app/configuration/docker-setup

Builds a Docker image with extended features (Rust, Docker Engine, browsers) enabled using the INSTALL_EXT=true build argument.

```bash
docker build --build-arg INSTALL_EXT=true -t mcphub:extended .
```

--------------------------------

### Stream Logs Example Event

Source: https://docs.mcphub.app/api-reference/logs

An example of a log event received from the real-time log streaming endpoint. This format is used for individual log entries sent after the initial connection.

```text
data: {"type":"log","log":{"timestamp":"2023-10-27T10:00:05.000Z","level":"debug","message":"Processing request for /api/some-endpoint","service":"mcp-server"}}
```

--------------------------------

### Create PostgreSQL Database

Source: https://docs.mcphub.app/development/getting-started

If you are using PostgreSQL, create the MCPHub database using the `createdb` command.

```bash
createdb mcphub
```

--------------------------------

### GET /api/logs

Source: https://docs.mcphub.app/api-reference/logs

Retrieves all stored logs.

```APIDOC
## GET /api/logs

### Description
Retrieves all stored logs.

### Method
GET

### Endpoint
/api/logs

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (array) - Array of log objects, each containing:
  - **timestamp** (string)
  - **level** (string)
  - **message** (string)
  - **service** (string)

### Response Example
```json
{
  "success": true,
  "data": [
    {
      "timestamp": "2023-10-27T10:00:00.000Z",
      "level": "info",
      "message": "Server started successfully.",
      "service": "system"
    }
  ]
}
```
```

--------------------------------

### MCP settings export

Source: https://docs.mcphub.app/api-reference/servers

Download the live settings as JSON.

```APIDOC
## GET /api/mcp-settings/export

### Description
Downloads the live MCP settings as a JSON file.

### Method
GET

### Endpoint
/api/mcp-settings/export
```

--------------------------------

### GET /api/groups

Source: https://docs.mcphub.app/api-reference/groups

Retrieves a list of all server groups.

```APIDOC
## GET /api/groups

### Description
Retrieves a list of all server groups.

### Method
GET

### Endpoint
/api/groups

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (array)
  - **id** (string)
  - **name** (string)
  - **description** (string)
  - **servers** (array of strings)
  - **owner** (string)

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "group-1",
      "name": "My Group",
      "description": "A collection of servers.",
      "servers": ["server1", "server2"],
      "owner": "admin"
    }
  ]
}
```
```

--------------------------------

### Run Backend and Frontend Separately on Windows

Source: https://docs.mcphub.app/installation

On Windows, you may need to run the backend and frontend development servers in separate terminals. Use `pnpm backend:dev` and `pnpm frontend:dev`.

```bash
# Terminal 1: Backend
pnpm backend:dev

# Terminal 2: Frontend
pnpm frontend:dev
```

--------------------------------

### GET /api/auth/user

Source: https://docs.mcphub.app/api-reference/auth

Retrieves the profile of the currently authenticated user.

```APIDOC
## GET /api/auth/user

### Description
Retrieves the profile of the currently authenticated user.

### Method
GET

### Endpoint
/api/auth/user

### Authentication
Bearer Token required.

### Response
#### Success Response (200)
- **success** (boolean) - Description
- **user** (object) - Description

#### Response Example
{
  "success": true,
  "user": {
    "username": "admin",
    "isAdmin": true,
    "permissions": { ... }
  }
}
```

--------------------------------

### GET /api/users-stats

Source: https://docs.mcphub.app/api-reference/users

Aggregate user counts. Requires administrator authentication.

```APIDOC
## GET /api/users-stats

### Description
Aggregate user counts. Requires administrator authentication.

### Method
GET

### Endpoint
/api/users-stats

### Authentication
Required (admin only)

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object) - Object containing user statistics.
  - **totalUsers** (integer)
  - **adminUsers** (integer)
  - **regularUsers** (integer)

### Response Example
```json
{
  "success": true,
  "data": {
    "totalUsers": 5,
    "adminUsers": 1,
    "regularUsers": 4
  }
}
```
```

--------------------------------

### Basic Docker Compose Configuration

Source: https://docs.mcphub.app/configuration/docker-setup

This configuration sets up the Mcphub service and a PostgreSQL database. It's suitable for basic local development and testing.

```yaml
version: '3.8'

services:
  mcphub:
    image: samanhappy/mcphub:latest
    # For local development, use:
    # build: .
    container_name: mcphub
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - PORT=3000
      - TRUST_PROXY=1
      - JWT_SECRET=${JWT_SECRET:-your-jwt-secret}
      - DB_URL=postgresql://mcphub:password@postgres:5432/mcphub
    volumes:
      - ./mcp_settings.json:/app/mcp_settings.json:ro
      - ./servers.json:/app/servers.json:ro
      - mcphub_data:/app/data
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - mcphub-network

  postgres:
    image: pgvector/pgvector:pg17
    container_name: mcphub-postgres
    environment:
      - POSTGRES_DB=mcphub
      - POSTGRES_USER=mcphub
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init-db.sql:ro
    ports:
      - '5432:5432'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U mcphub -d mcphub']
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - mcphub-network

volumes:
  postgres_data:
  mcphub_data:

networks:
  mcphub-network:
    driver: bridge
```

--------------------------------

### GET /api/groups/:id

Source: https://docs.mcphub.app/api-reference/groups

Retrieves details for a specific group by its ID or name.

```APIDOC
## GET /api/groups/:id

### Description
Retrieves details for a specific group by its ID or name.

### Method
GET

### Endpoint
/api/groups/:id

### Parameters
#### Path Parameters
- **:id** (string) - Required - The ID or name of the group.
```

--------------------------------

### Configure MCPHub Environment Variables

Source: https://docs.mcphub.app/configuration/database-configuration

Create a .env file to set environment variables for MCPHub, including the database connection URL and port. The USE_DB variable is automatically detected from DB_URL.

```bash
# Simply set DB_URL to enable database mode (USE_DB is auto-detected)
DB_URL=postgresql://mcphub:your_password@localhost:5432/mcphub
PORT=3000
```

--------------------------------

### GET /api/users

Source: https://docs.mcphub.app/api-reference/users

List all users. The `password` field is stripped from every record.

```APIDOC
## GET /api/users

### Description
List all users. The `password` field is stripped from every record.

### Method
GET

### Endpoint
/api/users

### Authentication
Required (admin only)

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (array) - Array of user objects, each with `username` and `isAdmin` fields.

### Response Example
```json
{
  "success": true,
  "data": [
    { "username": "admin", "isAdmin": true },
    { "username": "alice", "isAdmin": false }
  ]
}
```
```

--------------------------------

### Get All Users

Source: https://docs.mcphub.app/api-reference/users

Retrieves a list of all users. The 'password' field is excluded from the response.

```json
{
  "success": true,
  "data": [
    { "username": "admin", "isAdmin": true },
    { "username": "alice", "isAdmin": false }
  ]
}
```

--------------------------------

### Set up pgvector on Existing PostgreSQL

Source: https://docs.mcphub.app/installation

These SQL commands enable the pgvector extension for an existing PostgreSQL instance. Connect to your instance and execute these commands.

```sql
-- Connect to your PostgreSQL instance
-- Create database
CREATE DATABASE mcphub;

-- Connect to the mcphub database
\c mcphub;

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;
```

--------------------------------

### GET /api/logs/stream

Source: https://docs.mcphub.app/api-reference/logs

Streams logs in real-time using Server-Sent Events (SSE).

```APIDOC
## GET /api/logs/stream

### Description
Streams logs in real-time using Server-Sent Events (SSE). The connection will remain open, and new log entries will be sent as they occur.

### Method
GET

### Endpoint
/api/logs/stream

### Response Format
The stream sends events with a `data` field containing a JSON object. The first event has `type: 'initial'` and contains all historical logs. Subsequent events have `type: 'log'` and contain a single new log entry.

### Example Event
```
data: {"type":"log","log":{"timestamp":"2023-10-27T10:00:05.000Z","level":"debug","message":"Processing request for /api/some-endpoint","service":"mcp-server"}}
```
```

--------------------------------

### Configure Server Description Mode

Source: https://docs.mcphub.app/features/smart-routing

Set SMART_ROUTING_SERVER_DESCRIPTION_MODE to 'full' to include server descriptions in `search_tools` results. The default 'names' mode only lists server names.

```Shell
SMART_ROUTING_SERVER_DESCRIPTION_MODE=full
```

--------------------------------

### Fetch Server Configuration

Source: https://docs.mcphub.app/configuration/mcp-settings

Configure a fetch server to download resources. Specify the command, arguments, and environment variables like USER_AGENT and MAX_REDIRECTS.

```json
{
  "fetch": {
    "command": "uvx",
    "args": ["mcp-server-fetch"],
    "env": {
      "USER_AGENT": "MCPHub/1.0",
      "MAX_REDIRECTS": "10"
    }
  }
}
```

--------------------------------

### Reset Database

Source: https://docs.mcphub.app/development/contributing

This command resets the database to its initial state, useful for starting fresh.

```bash
pnpm run db:reset
```

--------------------------------

### Health Check Request Example

Source: https://docs.mcphub.app/api-reference/system

How to check the health status of the MCPHub server using curl.

```bash
curl "http://localhost:3000/health"
```

--------------------------------

### Run Database Migrations

Source: https://docs.mcphub.app/development/contributing

Execute this command to apply any pending database schema changes.

```bash
pnpm run migrate
```