MCPHub Management MCP

Typed, profile-gated MCP tools for managing MCPHub instances through the REST Management API.

Quick Start · MCPHub · MCPHub Docs · Tools · Security · Contribute

@garvae/mcp-mcphub turns MCPHub's REST Management API into typed, profile-gated MCP tools, so agents and operators can inspect, operate, and maintain MCPHub without hand-written REST calls.

MCPHub is the upstream hub this package manages; see the MCPHub docs, API reference, and CLI docs.

Use it when you want Claude, Codex, CI, or internal automation to manage MCPHub through MCP-native tools while keeping dangerous operations behind profiles, confirmations, and feature flags.

It is an independent, unofficial, community-maintained package. It manages MCPHub itself. It does not replace MCPHub, and it does not replace MCPHub's downstream /mcp gateway endpoints.

At a Glance

Capability	What it means
Typed MCP tools	MCPHub management APIs exposed as structured mcphub_* tools
Profile-gated access	safe, ops, admin, all surfaces
Agent-friendly catalogs	generated Markdown and JSON tool catalogs
Route coverage	MCPHub API coverage matrix and drift checks
Safe defaults	redaction, confirmations, dangerous feature flags off
npm-first	local npx / stdio by default

Quick Start

This example shows the smallest local setup: one MCP client launches this package over stdio with the safe exposure profile.

For HTTP mode, Docker/self-build deployments, shared gateways, or MCP manager setups, see runtime modes, Streamable HTTP, and shared gateway integration.

1. Start with a running MCPHub instance

You need a running MCPHub instance first. This package manages MCPHub; it does not install or replace MCPHub.

Use your MCPHub base URL as MCPHUB_URL, for example https://mcphub-site.com. If you are still setting up MCPHub itself, start with the upstream docs or the upstream repository.

2. Create an MCPHub management credential

Create a management credential in MCPHub. For unattended local or CI usage, the recommended first credential is a system-level bearer key with management access.

Upstream MCPHub CLI example:

mcphub login --url https://mcphub-site.com --username admin
mcphub keys create --name mcp-mcphub --access-type all

Copy the generated token when MCPHub prints it. Use that token as MCPHUB_TOKEN.

If your deployment uses another auth flow, see auth modes, getting started, and the upstream CLI docs.

3. Put the variables where your client can read them

Set these values either:

• in your shell before running the CLI;
• in a local .env file;
• directly in your MCP client config;
• in your MCP manager or shared gateway environment.

The shell examples below are only one option. See minimal config, full configuration, and managed gateway integration.

Example shell setup:

Bash

export MCPHUB_URL="https://mcphub-site.com"
export MCPHUB_TOKEN="REPLACE_ME"

npx @garvae/mcp-mcphub doctor
npx @garvae/mcp-mcphub stdio --exposure=safe

PowerShell

$env:MCPHUB_URL = "https://mcphub-site.com"
$env:MCPHUB_TOKEN = "REPLACE_ME"

npx @garvae/mcp-mcphub doctor
npx @garvae/mcp-mcphub stdio --exposure=safe

Example local .env for stdio:

MCPHUB_URL=https://mcphub-site.com
MCPHUB_TOKEN=REPLACE_ME

4. Run doctor before connecting the client

Run doctor first to verify that config loads, MCPHub is reachable, and the management credential is accepted. Use doctor --json when you need machine-readable diagnostics or CI-friendly output.

The preview is illustrative. For troubleshooting details, see troubleshooting and getting started.

5. Connect one local MCP client over stdio

For one local client, stdio is the smallest setup: no HTTP listener, no reverse proxy, and no inbound MCP token.

Claude Desktop / Claude Code style example:

{
  "mcpServers": {
    "mcphub-safe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@garvae/mcp-mcphub", "stdio", "--exposure=safe"],
      "env": {
        "MCPHUB_URL": "https://mcphub-site.com",
        "MCPHUB_TOKEN": "REPLACE_ME"
      }
    }
  }
}

See stdio mode, getting started, and runtime modes.

Using HTTP instead of stdio? You will also need an inbound MCP token such as MCP_HTTP_AUTH_TOKEN. See Streamable HTTP.

HTTP-only addition:

MCP_HTTP_AUTH_TOKEN=REPLACE_ME_SAFE_TOKEN

MCP_HTTP_AUTH_TOKEN and MCP_HTTP_AUTH_TOKENS_JSON are only for HTTP mode. They are not required for normal local stdio.

What This Is

• Typed MCP tools for MCPHub management
• CLI-first runtime with stdio and Streamable HTTP transports
• Exposure-profile filtering for safer agent access
• Structured schemas, confirmations, and redaction defaults

What This Is Not

• Not official MCPHub
• Not MCPHub itself
• Not a replacement for downstream /mcp gateway endpoints
• Not a generic arbitrary HTTP proxy
• Not a replacement for MCPHub UI, CLI, or deployment tooling

How It Fits

Clients connect to this package through stdio or Streamable HTTP, depending on whether they run locally or through a shared service. The package exposes typed mcphub_* tools instead of raw HTTP calls, so schemas, confirmations, and redaction rules stay consistent across clients. Exposure profiles decide which tools are actually available at runtime. Upstream operations are executed through the MCPHub REST Management API.

Why Use It

• Let Claude, Codex, CI, or trusted automation manage MCPHub through MCP tools
• Avoid ad-hoc REST calls and client-specific wrappers
• Work with typed schemas instead of free-form request payloads
• Start with safe, then raise exposure only when needed
• Keep destructive surfaces behind confirmations and feature flags
• Use generated tool catalogs and route coverage exports for static analysis

Common Use Cases

• Inspect MCPHub health, config, servers, groups, logs, and activity.
• Let an AI coding agent list available MCPHub servers and explain the current setup.
• Reload or toggle servers through an ops profile without exposing full admin tools.
• Manage groups, prompts, resources, and server definitions through trusted admin workflows.
• Compare MCPHub route coverage against upstream changes.
• Generate AI-readable tool catalogs for static planning and reviews.

Requirements

• Node.js 22.13+ (Node 22 LTS baseline; Node 24 also supported)
• A reachable MCPHub instance
• An MCPHub management credential
• Recommended first credential: a system-level bearer key with suitable management access
• pnpm is required for development, not for normal npx usage

Official MCPHub Links

• Official repository: samanhappy/mcphub
• Official documentation: docs.mcphub.app
• Official API reference: docs.mcphub.app/api-reference/introduction
• Official AI-readable docs index: docs.mcphub.app/llms.txt
• Official CLI and key-management examples: MCPHub CLI docs

Token Model

• MCPHUB_TOKEN authenticates this package to upstream MCPHub
• MCP_HTTP_AUTH_TOKEN or MCP_HTTP_AUTH_TOKENS_JSON authenticates inbound HTTP MCP clients to this package
• MCP_HTTP_* auth tokens are local to this package and are needed only for HTTP mode

For manual upstream bearer validation, prefer a normal management endpoint such as GET /api/servers. Do not use GET /api/auth/keys as the first bearer smoke check on older MCPHub versions.

Client Examples

Claude Desktop / Claude Code style stdio

{
  "mcpServers": {
    "mcphub-safe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@garvae/mcp-mcphub", "stdio", "--exposure=safe"],
      "env": {
        "MCPHUB_URL": "https://mcphub-site.com",
        "MCPHUB_TOKEN": "REPLACE_ME"
      }
    }
  }
}

Codex TOML

[mcp_servers.mcphub_safe]
command = "npx"
args = ["-y", "@garvae/mcp-mcphub", "stdio", "--exposure=safe"]
env_vars = ["MCPHUB_URL", "MCPHUB_TOKEN"]
startup_timeout_sec = 20
tool_timeout_sec = 90
enabled = true

Short HTTP example

export MCPHUB_URL="https://mcphub-site.com"
export MCPHUB_TOKEN="REPLACE_ME"
export MCP_HTTP_AUTH_TOKEN="REPLACE_ME_SAFE_TOKEN"

npx @garvae/mcp-mcphub http

See Streamable HTTP for full HTTP configuration, reverse-proxy guidance, and client auth mapping.

Runtime Modes

• stdio: best default for local MCP clients
• Streamable HTTP: for shared internal services, CI, reverse proxies, and long-running deployments
• Docker: optional self-build only

Docker is optional. The official distribution channel is npm; Docker examples are provided for users who want to build and run their own container image.

Exposure Profiles

Profile	Intended use	Notes
safe	read-only diagnostics and inventory	start here
ops	reversible operational changes	includes safe
admin	administrative CRUD	includes ops
all	maximum supported management surface	includes admin

Use the smallest profile that works. Dangerous feature-flagged surfaces stay disabled by default. Runtime tools/list is the final source of truth for what a client can actually access.

Supported Areas

Area	Coverage examples
Platform and health	health checks, public config, runtime config
Inventory and diagnostics	servers, groups, discovery, logs, activity
Servers	server CRUD, reloads, toggles, descriptions
Groups	group CRUD and membership
Logs and activity	operational visibility and summaries
Auth and identity	current user, bearer keys, OAuth clients, user management
Templates and config	settings snapshots, templates, system config
Market, cloud, registry, OpenAPI	where upstream management routes are supported and classified

Tool Catalogs and API Coverage

• Curated overview: docs/tools.md
• Generated catalog index: docs/generated/README.md
• safe catalog: docs/generated/tools.safe.md
• ops catalog: docs/generated/tools.ops.md
• admin catalog: docs/generated/tools.admin.md
• all catalog: docs/generated/tools.all.md
• Generated JSON catalogs:
  • docs/generated/tools.safe.json
  • docs/generated/tools.ops.json
  • docs/generated/tools.admin.json
  • docs/generated/tools.all.json
• Route coverage matrix: docs/api-coverage.md
• Machine-readable coverage export: docs/generated/api-coverage.json

Generated JSON catalogs are useful for AI agents, static planning, and automated analysis.

Built for Safe Agent Operations

MCPHub management is powerful: it can affect servers, groups, users, keys, logs, templates, and system config. This package exposes that power through profiles, confirmations, feature flags, and generated catalogs so agents can start read-only and only receive broader capabilities when explicitly configured.

For AI Agents

Start with docs/for-ai-agents.md. Use generated JSON catalogs for static planning. Use runtime tools/list as the final source of truth for exact schemas available to a selected profile. Do not assume admin or all tools are exposed unless the profile and feature flags allow them.

Security at a Glance

Control	Current behavior
Exposure profiles	server-side profile filtering
Secret redaction	enabled by default
Destructive actions	structured confirmations
Dangerous surfaces	feature-flagged and off by default
HTTP auth	required in HTTP mode
Host and origin validation	enforced in HTTP mode
Request limits and rate limiting	enforced in HTTP mode
Audit logging	optional and off unless configured
SSRF protection	recursive URL-field checks, HTTP/HTTPS-only validation, localhost/private-network blocking; DNS-based SSRF protection is not implemented
Security reporting	follow SECURITY.md

Read-only endpoints may still expose operationally sensitive information even after redaction. Review docs/security.md before exposing anything beyond local trusted use.

Community

This project is useful only if it stays aligned with real MCPHub deployments and real MCP client workflows.

Contributions are welcome in areas such as:

• adding and improving tests, especially around auth, exposure profiles, redaction, SSRF validation, HTTP transport, and package install behavior
• responsible security research, threat-model review, and hardening PRs
• testing against new MCPHub versions
• improving Claude, Codex, and other client setup examples
• expanding route coverage when upstream MCPHub adds APIs
• improving generated tool descriptions
• adding examples for real-world shared and remote MCPHub deployments
• improving troubleshooting and diagnostics
• reporting API drift or compatibility issues

If you run MCPHub in a different environment, use a different MCP client, or hit upstream API drift, your reports and examples are especially valuable.

Good First Contributions

• Improve docs for a client you use.
• Add a troubleshooting note for a setup failure you hit.
• Improve examples with safer placeholders.
• Report upstream MCPHub compatibility drift.
• Improve generated tool descriptions or risk notes.
• Add regression tests around a small tool group, redaction rule, or exposure-profile boundary.

Help Wanted

The most valuable help is:

• compatibility reports for MCPHub versions not yet covered
• real-world MCP client config examples
• security research for SSRF, token leakage, prompt or description injection, HTTP auth edge cases, and profile-boundary bypasses
• route coverage updates when upstream MCPHub changes
• tests for stdio, Streamable HTTP, and package install behavior

Recommended maintainer labels for public triage:

• good first issue
• help wanted
• documentation
• compatibility
• upstream-drift
• security
• client-config
• tool-catalog
• testing

Support the Project

If @garvae/mcp-mcphub saves you time managing MCPHub, consider supporting ongoing maintenance through GitHub Sponsors or Ko-fi.

Sponsorship helps fund compatibility testing, documentation, security hardening, and support for new MCPHub releases.

Code, docs, bug reports, compatibility reports, and security feedback are just as valuable as financial support.

Troubleshooting First Run

• Run npx @garvae/mcp-mcphub doctor
• Run npx @garvae/mcp-mcphub doctor --json for machine-readable diagnostics
• Unauthorized usually means the wrong upstream credential, auth header, or credential scope
• Connection failures usually mean the wrong MCPHUB_URL or an unreachable MCPHub instance
• HTTP 401 usually means the wrong local inbound HTTP token

See docs/troubleshooting.md.

Documentation Map

Need	Document
First run	docs/getting-started.md
Minimal config	docs/minimal-config.md
Full config	docs/configuration.md
stdio mode	docs/stdio.md
Streamable HTTP	docs/streamable-http.md
Runtime mode selection	docs/runtime-modes.md
Docker and deployment	docs/deployment.md
Tools overview	docs/tools.md
Generated catalogs	docs/generated/README.md
API coverage	docs/api-coverage.md
Security	docs/security.md
Testing	docs/testing.md
Compatibility	docs/compatibility.md
Upstream relationship	docs/upstream-mcphub.md
Shared gateway integration	docs/managed-gateway-integration.md
AI agents	docs/for-ai-agents.md
Troubleshooting	docs/troubleshooting.md
Roadmap direction	ROADMAP.md
Release and contribution	docs/release-process.md, CONTRIBUTING.md

Support and Contribution

• Questions and setup help: see SUPPORT.md and use GitHub Discussions
• Reproducible bugs: use the bug report issue template
• Feature proposals: use the feature request template
• Upstream route or compatibility drift: use the compatibility template
• Security issues: follow SECURITY.md and avoid public disclosures with sensitive details
• Pull requests: read CONTRIBUTING.md
• Contributor and agent notes: AGENTS.md

Do not post tokens, cookies, client secrets, private URLs, or sensitive production logs publicly.

Installation

No-install local run:

npx @garvae/mcp-mcphub doctor
npx @garvae/mcp-mcphub stdio --exposure=safe

Optional global install:

pnpm add -g @garvae/mcp-mcphub

License

Apache-2.0. See LICENSE.