McpHub

[McpHub, one secure hub for all your MCP servers]

[Download for macOS]   [Install in one line]

[Latest release] [MCP 2026-07-28] [Rust] [macOS and Linux] [MIT]

McpHub sits between your AI editors and all your MCP servers.
Your agents see 3 tools instead of hundreds, every call goes through the same security guards,
and your servers run once, sandboxed, shared by Cursor, Claude, Windsurf and VS Code.

Install · Connect your editor · How it works · Code mode · Security · Dashboard · Library · Linux and sync · Configuration · FAQ

✨ At a glance

🚀 Install in one line

curl -fsSL https://raw.githubusercontent.com/Soflutionltd/McpHub/main/get.sh | bash

The script downloads the latest binary for your machine (signed universal binary on macOS, x64 or arm64 on Linux), verifies its SHA-256 checksum and installs it to ~/.local/bin/McpHub. Then:

McpHub dashboard  # Library tab: add servers from the official MCP Registry (or McpHub add)McpHub generate   # index every tool onceMcpHub install    # start the daemon at login (LaunchAgent on macOS, systemd --user on Linux)

git clone https://github.com/Soflutionltd/McpHub.gitcd McpHubmake install      # cargo build --release, install, sign

🔄 Updates

Once the daemon runs (McpHub install), McpHub keeps itself up to date. Editors connected by URL (Cursor, Claude Code, VS Code, Windsurf) need nothing: they talk to the updated daemon.

• Signed. Every release publishes latest.json (version and SHA-256 of each file) signed with minisign; the public key is compiled into McpHub. On macOS the new binary must also carry Soflution's Developer ID signature. Anything else is refused.
• Gradual. A new version reaches 10% of installations on day one, everyone after 24 hours. The daemon checks at start-up, then every 6 hours. The only request is the download from GitHub: no telemetry, the rollout bucket is drawn from a random local id that never leaves your machine.
• Never in the middle of a call. The new binary is installed next to the old one; each daemon switches over as soon as no request is in flight (editors reconnect by themselves). If the new version fails to start three times, the previous one is restored and that version is skipped.
• Your choice. "settings": { "autoUpdate": false } turns it off; McpHub update installs the latest release right away, McpHub update --check only reports it. Development builds and named instances never update themselves (the main instance updates the shared binary).
• Claude Desktop extension. mcphub.mcpb uses the installed McpHub when there is one, so it follows the same updates; otherwise it runs the binary it ships with.
• Windows. The binary is replaced in place and used from the next session start.

🔌 Connect your editor

The daemon listens on http://127.0.0.1:24680. Your token is in ~/.McpHub/auth-token.

{  "mcpServers": {    "McpHub": {      "url": "http://127.0.0.1:24680/mcp",      "headers": { "Authorization": "Bearer <your-token>" }    }  }}

claude mcp add --transport http mcphub http://127.0.0.1:24680/mcp \  --header "Authorization: Bearer $(cat ~/.McpHub/auth-token)"

{  "mcpServers": {    "McpHub": { "command": "/Users/you/.local/bin/McpHub", "args": ["stdio"] }  }}

{  "servers": {    "mcphub": {      "type": "http",      "url": "http://127.0.0.1:24680/mcp",      "headers": { "Authorization": "Bearer <your-token>" }    }  }}

One profile per client. Give each editor its own view: http://127.0.0.1:24680/mcp/cursor only shows what the cursor profile allows (see Profiles).

Project-aware client (optional)

client/ is a small Node MCP server that sits between your editor and the daemon. It talks to the running daemon (SSE, token from ~/.McpHub/auth-token) and falls back to McpHub stdio. It exposes six tools:

• mcphub_bootstrap: call once per conversation. Resolves the project from the workspace, returns its aliases and allowed servers, and recalls compact MemoryPilot context, also for folders without a project entry.
• mcphub_search, mcphub_call: same as the daemon, plus suggestions on a misspelled tool or server, and the input schema on argument errors.
• mcphub_batch: up to 20 independent calls in one round-trip.
• mcphub_status, mcphub_savings: server health and an honest context-size comparison.

Per-project policy lives in ~/.McpHub/projects.json (or the path in MCPHUB_PROJECTS), see client/projects.example.json. For a workspace listed there, only its allowedServers are reachable, and a call aimed at another Supabase project, App Store app or Cloudflare project is refused. Without the file there is no policy; an unreadable file is an error, never silently ignored.

Each release ships the client as a single file, mcphub-client.mjs, which the daemon keeps up to date in ~/.McpHub/client/ (Node 20 or later, no npm install). Editors pick up a new version the next time they start the server:

{  "mcpServers": {    "McpHub": { "command": "node", "args": ["/Users/you/.McpHub/client/mcphub-client.mjs"] }  }}

From a clone instead: cd client && npm ci, then point args at /path/to/McpHub/client/index.js.

npm test runs smoke tests against the local daemon (MemoryPilot and supabase configured), with a throwaway project file.

Working on client accounts

Connecting to a client's Stripe (or Supabase, Cloudflare…) should not log you out of your own, and your own agent should never reach theirs by mistake. Two levels, from light to strict:

1. Client-owned servers (same McpHub). Add the client's server under its own name (stripe-acme, with its own OAuth token or restricted key, since tokens are stored per server name) and list it in the client project's ownedServers:

"acme": {  "workspaces": ["/Users/you/Clients/Acme"],  "aliases": { "product": "Acme" },  "allowedServers": ["MemoryPilot", "context7"],  "ownedServers": ["stripe-acme"]}

An owned server only answers, appears in mcphub_search and in mcphub_status when working_dir is inside that client's workspace; the project argument alone is not enough. A server owned by two projects is a start-up error. This guard lives in the Node client: an editor connected straight to the daemon still sees every server, so give it a profile with "excludeServers": ["*-acme"].

2. A separate instance (nothing shared). For clients who require it, run a second McpHub with its own folder, port, Keychain service, auth token and LaunchAgent:

export MCPHUB_INSTANCE=acme MCPHUB_PORT=24690McpHub add                 # writes ~/.McpHub-acme/config.jsonMcpHub oauth login stripe  # token stored under Keychain service McpHub-acmeMcpHub install             # LaunchAgent com.soflution.mcphub.acme

A named instance never imports the servers declared in your editors, refuses the main port (24680), and its token is rejected by the main daemon (and the other way round). Point the editor of that client's workspace at it with the same variables:

"McpHub": {  "command": "node",  "args": ["/path/to/McpHub/client/index.js"],  "env": { "MCPHUB_INSTANCE": "acme", "MCPHUB_PORT": "24690" }}

MCPHUB_HOME and MCPHUB_VAULT_SERVICE override the folder and the Keychain service. Sandboxed servers of every instance are denied all ~/.McpHub* folders. Automatic start of a named instance is supported on macOS and Linux.

🧭 How it works

[Architecture: AI clients, the McpHub pipeline, local and remote servers]

1. Your editor connects once to the McpHub daemon (Streamable HTTP, SSE or stdio).
2. The agent sees three tools: mcphub_search (BM25 search over every tool), mcphub_call (run one tool) and mcphub_run (code mode).
3. Each call is authenticated, filtered by the client profile, checked against the tool pins and permissions, then routed to the right server, which is started on demand and stopped when idle.
4. Local servers run under the macOS sandbox with a minimal environment; remote servers are reached directly over HTTP with OAuth tokens kept in the Keychain.
5. Every call lands in the audit log.

Token savings

[Tool definitions: 1,054,593 tokens directly, 918 tokens through McpHub]

Wiring dozens of MCP servers straight into an editor loads every tool schema into every conversation. On the setup above (35 servers, 928 tools) that is over a million tokens, more than any context window. McpHub replaces it with three small tools and loads a schema only when the agent actually needs it.

🧠 Code mode

[Without code mode: 25 round trips. With mcphub_run: one call]

For multi-step or bulk work, the agent sends a short JavaScript program with mcphub_run:

const projects = await mcp.call("supabase", "list_projects", {});const unhealthy = projects.filter(p => p.status !== "ACTIVE_HEALTHY");return unhealthy.map(p => p.name);

• mcp.call(server, tool, args) returns the tool result, mcp.search(query) finds tools, console.log is captured.
• The program runs in a separate Node.js process (22.13 or newer) started with --permission: no files, no network, no subprocesses, inside a macOS sandbox.
• Its only way out is mcp.call, which goes through every McpHub guard (permissions, quarantine, profiles, audit).
• Limits: settings.codeMode → { "timeoutSecs": 60, "maxCalls": 100 }, output capped at 1 MB.

🛡️ Security

[Eight layers of security]

MCP servers are third-party programs, often fetched on the fly with npx -y package@latest, running with your permissions. McpHub treats them accordingly.

McpHub vault set GITHUB_TOKEN      # masked prompt, stored in the KeychainMcpHub vault migrate               # move an existing secrets.env into the Keychain

McpHub pins status                  # what is quarantined and whyMcpHub pins approve SERVER [TOOL]   # accept the new definitionMcpHub pins scan                    # scan every cached tool, read-only

"settings": { "toolSecurity": { "pinning": "block", "scan": "block", "newTools": "block" } }

"settings": { "toolSecurity": { "pinning": "off", "scan": "block", "newTools": "auto", "requireSignedCommits": true } }

"settings": { "sandbox": "shield" }

McpHub sandbox                 # effective isolation of every serverMcpHub sandbox show supabase   # the generated profile

"permissions": {  "default": "allow",  "rules": [    { "server": "supabase", "tool": "delete_*", "action": "deny", "reason": "production" },    { "server": "stripe", "tool": "*", "action": "confirm" }  ]}

🌐 Remote servers and shared OAuth

"sentry":  { "url": "https://mcp.sentry.dev/mcp" },"aqara":   { "url": "https://agent.aqara.com/open/mcp", "headers": { "Authorization": "Bearer ${AQARA_API_KEY}" } }

Remote servers are reached directly over Streamable HTTP, without an mcp-remote process per server. McpHub implements the MCP authorization spec: discovery (RFC 9728 and 8414), dynamic client registration, PKCE, resource indicators, automatic refresh, HTTPS only, tokens bound to the server URL and stored in the Keychain.

McpHub oauth status            # connection state of every remote serverMcpHub oauth login sentry      # sign in through the browser, onceMcpHub oauth logout sentryMcpHub oauth migrate --apply   # convert "npx mcp-remote URL" entries, keeping their tokens

📊 Dashboard

Run McpHub dashboard (a one-time link opens your browser).

📚 Library

The Library tab of the dashboard is the official MCP Registry inside McpHub: search thousands of servers, read a trust score, click Add.

• Search runs locally. The first time you open the Library, McpHub downloads the catalog once in the background (the popular servers from the GitHub MCP Registry come first, in a few seconds; the full official catalog follows) into ~/.McpHub/registry-cache/. After that, it only fetches what changed, at most once a day. Search is instant and works offline.
• Zero weight for your agent. The catalog lives in the dashboard and on disk. It adds no tool definition to the agent's context and nothing stays in memory between searches.
• Trust score before you install (0 to 100), with the detail of every point:
  • verified publisher: the registry checks the namespace (a GitHub account or a DNS domain), McpHub checks that it publishes its own code;
  • popularity and activity: GitHub stars, last update, archived repositories;
  • permission scan: secrets requested, plain HTTP endpoints, privileged Docker options, bundle integrity hash, unpinned versions, and what the server can do (run commands, touch files, a browser, payments...).
• One-click add for every kind of server: remote (Streamable HTTP), npm (npx), Python (uvx), Docker, .NET (dnx) and .mcpb bundles (downloaded, SHA-256 checked, extracted outside ~/.McpHub).
• Secrets go to the Keychain, never to config.json. A secret you already have (GITHUB_TOKEN...) is reused.
• Remote servers sign in with McpHub's native OAuth (one click on Sign in), tokens in the Keychain.
• New servers inherit every guard: shield sandbox for local code (Docker keeps its container), tool pinning and description scan on first contact, quarantine on change, audit log, permissions and profiles.

From the terminal: McpHub registry search postgres, McpHub registry info NAME, McpHub registry install NAME, McpHub registry sync.

Your agent installs what it needs

No new tool is added for this (about 30 tokens in total). When mcphub_search finds nothing, the agent can call:

mcphub_call  server=mcphub  tool=registry_search   arguments={"query": "postgres"}mcphub_call  server=mcphub  tool=registry_install  arguments={"name": "io.github.acme/postgres-mcp"}

The server is installed with the same guards, its tools are indexed right away, and the call is audited. An agent never handles secrets: when a server needs one, the agent asks you to finish in the dashboard. Control it in settings.registry:

"registry": { "agentInstall": "trusted", "minTrust": 60 }

agentInstall: "trusted" (default, only servers whose trust score reaches minTrust), "any" or "off".

🐧 Linux servers and sync

McpHub runs the same way on a Linux server, for example next to an agent running on a VPS:

curl -fsSL https://raw.githubusercontent.com/Soflutionltd/McpHub/main/get.sh | bashsudo apt install bubblewrap   # sandboxMcpHub install                # systemd --user service

• Sandbox with bubblewrap: same policy as on macOS. Every secret folder (~/.ssh, ~/.aws, ~/.McpHub...) is replaced by an empty folder in memory, every secret file by an empty file; strict mode makes the whole system read-only except temporary folders, caches and allowWrite.
• Secrets in ~/.McpHub/secrets.env, mode 600, hidden from sandboxed servers. McpHub vault set NAME works the same.

Move your setup from one machine to another without any plaintext secret:

McpHub sync export mcphub.sync.json --secrets   # on the MacMcpHub sync import mcphub.sync.json --secrets   # on the server

The export is a portable config.json: every secret is a ${NAME} reference (plain values that look like tokens are taken out of the copy), and home paths become ${HOME}/.... With --secrets, the values travel too, encrypted with a passphrase (scrypt, then ChaCha20-Poly1305). Without the passphrase the file only reveals secret names. On import, servers whose program is missing on that machine are imported disabled, and decrypted secrets go to the Keychain (macOS) or secrets.env (Linux). For scripts, set MCPHUB_SYNC_PASSPHRASE.

⚙️ Configuration

Everything lives in ~/.McpHub/config.json and is hot-reloaded while the daemon runs.

{  "servers": {    "supabase": {      "command": "npx",      "args": ["-y", "@supabase/mcp-server-supabase"],      "env": { "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}" },      "tools": { "exclude": ["delete_*", "pause_project"] },      "toolDescriptions": { "list_projects": "List my Supabase projects" }    },    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "readOnly": true },    "sentry": { "url": "https://mcp.sentry.dev/mcp" }  },  "settings": {    "mode": "discover",    "sandbox": "shield",    "toolSecurity": { "pinning": "block", "scan": "block", "newTools": "block" },    "permissions": { "default": "allow", "rules": [] },    "profiles": {      "cursor": { "servers": ["supabase", "git*"], "excludeTools": ["supabase/execute_sql"] },      "review": { "readOnly": true }    },    "codeMode": { "timeoutSecs": 60, "maxCalls": 100 },    "idleTimeout": 300  }}

Per-server options

Profiles per client

Profiles decide what each client may see and call: servers and excludeServers (globs), excludeTools ("server/tool" globs) and readOnly. Select one with http://127.0.0.1:24680/mcp/<profile>, /sse?profile=<profile>, or MCPHUB_PROFILE=<profile> in stdio mode.

Modes

• discover (default): the agent sees mcphub_search, mcphub_call and mcphub_run.
• passthrough: every tool is exposed directly as server__tool (full visibility, higher token cost).

🧰 CLI

McpHub serve              # HTTP daemon (Streamable HTTP /mcp, SSE /sse, dashboard)McpHub stdio              # stdio mode for editors that spawn the processMcpHub install            # start at login · McpHub uninstallMcpHub generate           # start every server and index its toolsMcpHub status | doctor    # configuration, cache and health diagnosticsMcpHub search "send email"McpHub dashboard          # open the dashboard (one-time link)McpHub logs               # follow the daemon logMcpHub add                # interactive server wizardMcpHub vault ...          # Keychain secrets: status, list, set, get, rm, migrateMcpHub registry ...       # Library: search, info, install, uninstall, syncMcpHub sync ...           # export / import to another machine, secrets encryptedMcpHub oauth ...          # remote servers: status, login, logout, migrateMcpHub pins ...           # tool pinning: status, approve, reset, scanMcpHub sandbox [show S]   # server isolationMcpHub policy test S T    # which permission appliesMcpHub audit --tail 50    # recent callsMcpHub update [--check]   # install the latest signed release now (automatic otherwise)McpHub version | help

gh workflow run release.yml --ref vX.Y.Z -f action=pause    # nobody else receives itgh workflow run release.yml --ref vX.Y.Z -f action=resume   # back to the gradual rolloutgh workflow run release.yml --ref vX.Y.Z -f action=full     # everyone now (urgent fix)

Files: ~/.McpHub/ (config, cache, pins, audit log, token; ~/.McpHub-<name>/ for a named instance) and ~/Library/Logs/McpHub/<server>.stderr.log (each server's error output).

❓ FAQ

McpHub uninstallrm ~/.local/bin/McpHubrm -rf ~/.McpHub

[McpHub logo]
_{MIT License · Made by SOFLUTION LTD}