mcphub

A self-hosted MCP platform. Backends are plugins; each configured backend gets its own OAuth-protected MCP endpoint; everything is configured in a web UI instead of environment variables.

Built to replace a setup with three specific problems: an MCP server exposed to the internet with no authentication at all, firewall write tools that reported "not found" for rules that plainly existed, and configuration that lived in env vars and a YAML file.

What it does

One endpoint per backend. A configured backend is mounted at /mcp/<slug> and added to Claude as its own connector. Backends are never merged into a single endpoint — the MikroTik plugin alone exposes 24 tools and the server this replaces exposed 182, so merging burns context before you ask anything and measurably degrades tool selection.

Real OAuth. A full OAuth 2.1 authorization server with dynamic client registration (RFC 7591), PKCE, refresh-token rotation, and protected resource metadata (RFC 9728). Each backend is a distinct RFC 8707 resource, so a token issued for your router is rejected if replayed against another backend on the same hub.

Configuration in a browser. Add a device, rotate a password, disable a backend — it takes effect immediately, with no restart and no YAML. Credentials are encrypted at rest and never sent back to the browser.

Related MCP server: MikroMCP

Running it

docker compose up -d

Set MCPHUB_PUBLIC_URL to the URL clients actually reach — your reverse proxy's, not the container's. OAuth discovery compares issuer strings exactly, so a mismatch here breaks connection rather than degrading it.

On first start the log prints a generated admin password, once:

====================================================================
First run: created the 'admin' account.
  username: admin
  password: ...
====================================================================

Sign in, change it, add a backend, then paste the endpoint URL shown on the dashboard into Claude as a custom connector. Claude registers itself, you sign in, and you approve the connection.

Deploying

Every push to main runs the test suite and, if it passes, builds a multi-arch image (amd64 + arm64) and pushes it to your container registry. Tags matching v* also publish semver tags. Pull requests build the image to prove the Dockerfile still works, but do not push.

Repository secrets drive it — the registry host included, so nothing about your infrastructure lives in the workflow:

gh secret set DOCKER_REGISTRY
gh secret set DOCKER_USERNAME
gh secret set DOCKER_PASSWORD

Two things the runner needs, both easy to miss:

• The registry must be reachable from the public internet. GitHub-hosted runners cannot see a LAN-only registry. If yours is internal, use a self-hosted runner on that network instead.

• Its TLS certificate must chain to a public CA. A private CA or a self-signed certificate will fail the login on a hosted runner.

On Unraid

Add a container with the published image and:

The container starts as root only long enough to align /data with PUID/PGID, then drops to that user before running anything. Without that step a bind mount owned by someone else fails as sqlite3.OperationalError: unable to open database file, which says nothing about ownership. Pass --user to skip it and manage the ownership yourself.

Then point a proxy host at it with a real certificate. The first-run admin password is printed once, in the container log.

Updating

Three separate things update, and they are not the same thing:

The hub itself, including the proxy plugin, updates with the image:

docker compose pull && docker compose up -d

A launched server's code. uvx and npx resolve their package again each time they start, so restarting the backend is what picks up a new release — press Update on its card. That relaunches it and re-reads what it offers, reporting what actually changed:

updated 1.29.0 -> 1.30.0; 1 new tool(s): convert_time

Per-account version pinning. Anyone granted a backend can choose which version they get, from the selector on its card. It is not a permission and it affects nobody else — which means the hub runs both versions at once, each started the first time someone on it connects, and a version nobody uses costs nothing.

Each version gets its own server rather than a swapped subprocess, because a version can offer a different set of tools: of one real server, 0.14.8.0 has 174 and 0.15.0.0 has 182. Offering an account a tool its own version lacks would fail only when it tried to call it.

A version is launched and read when it is first pinned, so one that cannot start is refused there and then, with the reason, rather than at the next connection. Only registry-added backends can be pinned — guessing which token of a hand-written command is the package would eventually rewrite the wrong one. For those, pin in the command itself:

uvx mikrotik-mcp==0.1.0
npx -y some-server@1.4.2

Knowing an update exists. A background check asks the registry hourly whether a newer version of each registry-backed backend has been published, and marks the card when one has. It changes nothing on its own. The registry serves repeats from its own cache and publishes no rate limit, so one small query per backend per hour is unremarkable; failures back off, and startup is staggered so restarted hubs do not arrive in lockstep.

The tool list this hub serves. Cached when the backend is saved, so that an endpoint still mounts when its upstream is down. Update re-reads it. Until you do, a server that gained tools keeps being advertised with the old list — so if an upstream released something and you cannot see it, that button is why. Tools the upstream no longer has are dropped from the allowlist at the same time, rather than lingering and quietly reappearing if it ever brings them back.

Accounts

The first run creates one administrator. Further accounts are added under Accounts, each carrying two toggles and a set of grants:

Backends are shared rather than per-account: configured once, then granted out, so a router's password lives in one place and there is one page showing who can reach it.

The grant is checked on every request, not when the token was issued, so removing access cuts off an existing connector at once rather than whenever its token happens to expire. Authorising a connector for a backend an account has not been granted is refused at sign-in, with the reason, instead of succeeding and then failing on use.

Configuration

Only these are environment variables. Everything else lives in the database.

The MCP transport enforces DNS-rebinding protection, accepting only Host headers matching MCPHUB_PUBLIC_URL (plus loopback). Get that variable wrong and requests fail with 421 Misdirected Request after a completely successful sign-in, which looks like an authentication fault and is not one.

Back up /data. Losing master.key makes every stored backend credential permanently unreadable.

MikroTik

MikroTik lives in its own package now: mikrotik-mcp. It is a standalone MCP server, so it works with any client, not only this hub.

Add it here as a launched server — a proxy backend with the command:

uvx mikrotik-mcp

and MIKROTIK_HOST, MIKROTIK_USERNAME, MIKROTIK_PASSWORD in the Environment field, where they are encrypted at rest. It then runs in its own process and cannot read credentials held for other backends.

That package also ships an mcphub.plugins entry point, so it can be loaded in-process with typed settings fields instead, if you install it into the hub's environment and accept that an in-process plugin sees everything the hub holds.

Upgrading from a build where MikroTik was bundled: an existing mikrotik backend will report its plugin as missing and stay unmounted. Re-create it as a launched server with the command above; nothing else changes.

The proxy plugin

Wraps an MCP server — one you already run, or one the hub launches for you. Either way it inherits the hub's authentication without a line of its own code changing.

Installing servers from npm and PyPI

Give the backend a command instead of a URL and the hub runs the server itself:

npx -y @modelcontextprotocol/server-filesystem /data
uvx mcp-server-time --local-timezone=Europe/Amsterdam

npm and PyPI are the plugin registry, so there is nothing to host and nothing to install by hand. The image ships Node and uv for exactly this; downloads are cached on the data volume, so a restart does not refetch them. Servers that need an API key take one through the Environment field (KEY=VALUE per line), which is encrypted at rest like any other secret.

A launched server runs in its own process. It cannot read the credentials stored for other backends, cannot reach the OAuth tables, and cannot touch the encryption key — none of which is true of a plugin loaded into the hub. That is the reason to prefer this route for third-party code, and the reason the hub does not install Python plugins from PyPI at runtime.

New proxy backends are created disabled. Adding one installs and introspects the server but mounts nothing, so you see its tool list and choose what to expose before anything attaches to your account.

That is how Unraid is handled: the Unraid Management Agent already speaks MCP on http://<server>:8043/mcp, so there is nothing to reimplement — it just needs fronting.

Wrapping buys three things the upstream cannot do for itself:

Authentication. The agent answers initialize with no credentials at all and sends Access-Control-Allow-Origin: *. Behind the hub it gets OAuth, dynamic client registration and a token scoped to that backend alone.

A tool allowlist. The agent exposes 126 tools — about 10,000 tokens just to list them, spent before you ask anything. The settings page fetches the live tool list and lets you tick the ones you want; the rest are not registered, so they are genuinely uncallable rather than merely hidden.

Several views of one server. Point two backends at the same upstream with different selections — a read-only unraid-status and an unraid-admin — and each is its own connector with its own token.

Upstream tool schemas are preserved: the plugin synthesises a Python signature that reproduces the upstream JSON Schema, so descriptions, enums, required fields and destructiveHint all survive the hop. That round trip is exact for flat object schemas, which is every tool the Unraid agent exposes. Anything it cannot represent is named in the tool's own description rather than dropped quietly.

Tool schemas are cached when you save, so the endpoint still mounts when the upstream is down — its tools then report the failure themselves.

Once an upstream is wrapped, firewall its own port to the hub. Otherwise the authentication is decorative: the original open port is still there.

Adding servers from the registry

The dashboard can search the official MCP registry. A published server ships a server.json declaring how it runs and what it needs, so both the command line and a correctly typed settings form are generated rather than typed — a value the server marked secret gets a password field, and everything it declares is encrypted at rest whether or not it was flagged.

Search, pick, fill in the settings, and it is added disabled; you land on its settings page to review its tools and choose which to expose.

Servers not in the registry are still added by hand, with a command or a URL.

Verified servers

A result can carry one of two badges, and the difference matters.

Launches means the server started, completed a handshake and listed its tools. That is a liveness check and nothing more. The MikroTik server this project was built to replace passes it comfortably — it starts fine and lists 182 tools fine, and every one of its write tools is broken. A badge that stopped here would be measuring the wrong thing confidently.

✓ Verified means that, plus every behavioural probe the entry declares ran and returned what it should. A probe is a read-only tool call with an expected outcome, declared in verified.json:

{"tool": "update_firewall_rule", "arguments": {"rule_id": "3"},
 "expectError": "position",
 "why": "a positional index is refused before it can reach the device"}

That one exercises the exact logic the replaced server got wrong, and needs no router to do it: probes run against TEST-NET addresses, so anything that would reach a real device simply fails to connect.

Neither badge is a claim by the server's author, and neither says every tool works or that a server is safe to run. A probe says the behaviour it names is the behaviour observed. Everything without a badge is unchecked, not suspect.

src/mcphub/data/verified.json holds the results and ships with the hub, so the badge reflects the build you are running. .github/workflows/verify-servers.yml re-runs the checks weekly and opens a pull request when what it observes changes; a server that quietly stops launching turns the build red rather than keeping its badge. The script self-tests its own harness first, so "everything failed" is distinguishable from "the harness is broken".

Writing a plugin

A plugin is any object with id, name, description, fields, build() and check(), advertised on the mcphub.plugins entry point group. The built-in MikroTik plugin uses exactly this path — there is no privileged route into the registry.

from mcphub.plugins.base import BackendInstance, CheckResult, ConfigField
from mcp.server.mcpserver import MCPServer

class UnraidPlugin:
    id = "unraid"
    name = "Unraid"
    description = "Manage an Unraid server."
    fields = (
        ConfigField("host", "Host", placeholder="192.168.1.50"),
        ConfigField("api_key", "API key", type="password", secret=True),
    )

    def build(self, instance: BackendInstance) -> MCPServer:
        mcp = MCPServer(name=f"unraid-{instance.slug}", title=instance.title)

        @mcp.tool(name="list_containers")
        async def list_containers(ctx) -> str:
            ...
        return mcp

    async def check(self, instance: BackendInstance) -> CheckResult:
        return CheckResult(True, "Connected")

PLUGIN = UnraidPlugin()

[project.entry-points."mcphub.plugins"]
unraid = "your_package:PLUGIN"

build() must not do network I/O — a backend that is merely unreachable still has to mount, so its own tools can report the failure. fields marked secret are encrypted at rest and never rendered back into a form. A plugin that fails to import is logged and skipped rather than taking the hub down with it.

Two rules worth keeping in your own tools:

• Raise mcp.server.mcpserver.exceptions.ToolError for anticipated failures. Any other exception is treated as a crash and the model sees only Error executing tool <name> — your message is discarded.

• Never accept a positional index as a write handle. It is the bug this project was built to stop repeating.

Development

uv sync --extra dev
uv run pytest
MCPHUB_DEV=1 MCPHUB_DATA_DIR=./data MCPHUB_PUBLIC_URL=http://127.0.0.1:8080 uv run python -m mcphub

Status

Built and tested end to end: the hub, the OAuth server, the config UI and the proxy plugin, over both transports. Per-backend token isolation and the tool allowlist are verified by test, not assumed — including that a filtered-out tool cannot be called.

The proxy is exercised against a real Unraid Management Agent over HTTP (126 tools discovered, narrowed to 5, schemas preserved, live calls forwarded) and against a published PyPI server launched over stdio.

The hub ships one backend of its own, the proxy. Everything else is a package: see mikrotik-mcp.

Tools and resources are proxied, including each tool's _meta, so an upstream using MCP Apps keeps its interface through the hop: the ui:// resource its tool points at is exposed and read through on demand, with its text/html;profile=mcp-app type and _meta.ui sandbox policy intact.

Prompts are proxied too, keeping the names, descriptions and required flags they were published with.

Known limits:

• Non-text tool results (images, embedded resources) are described rather than passed through.

• Schema synthesis is exact for flat object schemas. A deeply nested upstream schema would degrade, and the tool says so in its description when it does.