Hubstead
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Hubstead
A maintained fork of MetaMCP. MetaMCP was created by James Zhang and the metatool-ai contributors. The original repository (metatool-ai/metamcp) was archived on 12 Nov 2026. Hubstead picks up maintenance from that point. Not affiliated with metatool-ai.
Who maintains this
Hubstead is maintained by SKILLMERC (Pty) Ltd, a company registered in South Africa. The day-to-day work (triage, fixes, dependency updates, release notes) is done by AI agents. SKILLMERC (Pty) Ltd is accountable for every release. Changes are reviewed by a separate AI agent, not by a person.
Related MCP server: mcp_proxy
Status
Our first release is v2.6.0. It is MetaMCP as it stood when it was archived, including the security fixes of 3 Nov and 12 Nov 2026, plus two access-control fixes of our own (upstream issues 364 and 388) and our maintenance setup. See the release notes.
There is no Hubstead Docker image yet. The upstream instructions below and docker-compose.yml still use ghcr.io/metatool-ai/metamcp:latest. Upstream last built that image for v2.4.22 in December 2025, before those fixes. To run Hubstead, build it from source:
git clone --branch v2.6.0 https://github.com/skillmerc/hubstead.git, thencd hubstead.cp example.env .env, then setBETTER_AUTH_SECRETin.envto a new value fromopenssl rand -hex 32. Hubstead refuses to start in production with the example value.In docker-compose.yml, replace the two lines
image: ghcr.io/metatool-ai/metamcp:latestandpull_policy: alwayswithbuild: ..Run
docker compose up -d --build.
What we will do
Fix security problems first. A problem reported to us privately gets a GitHub security advisory when the fix is released.
Keep dependencies and the Docker base image up to date.
Fix bugs that have a clear way to reproduce them.
Review pull requests from the community, and credit authors when we port upstream work.
Keep the database schema and environment variables compatible with MetaMCP. Moving over is an image change, plus any setting the stricter security defaults need (see the release notes).
What we will not do
We never post, comment or open issues or pull requests on the upstream repository (metatool-ai/metamcp).
On other projects, the only thing we open is a listing pull request: at most one per directory, adding one entry for Hubstead and changing no one else's entry, and only where the directory's contribution rules take additions by pull request and do not bar AI agents. Each one says it was opened by an AI agent for SKILLMERC (Pty) Ltd. We comment only to answer the maintainers in that pull request.
We list Hubstead in directories and registries only through their own free submission forms or publishing tools. Where a form has a description, it says Hubstead is maintained by AI agents.
We do not promise new features on a schedule.
We do not run a hosted service from this repository.
Report a problem
Bugs and questions: open an issue in this repository with the steps to reproduce it.
Security problems: do not open a public issue. Use GitHub private vulnerability reporting on this repository, or email kyle@skillmerc.com. See SECURITY.md.
Credit and licence
MetaMCP is MIT licensed, Copyright 2024 MetaMCP, James Zhang. That licence and copyright notice are kept unchanged in LICENSE. The full upstream history and authorship are kept in this repository. Thank you to James Zhang and everyone who contributed to MetaMCP.
The original MetaMCP README follows.
๐ MetaMCP (MCP Aggregator, Orchestrator, Middleware, Gateway in one docker)
๐ข Latest Update: This ai-dev branch will be the forward onging dev branch which contains ai agent changes. Please test before you build the image based on this branch. There has been many PRs thanks to the community but merging and reviewing them has been a growing effort too. I decided to include ai changes. At least so far the core functionality works. There is also a community maintained fork (ty a lot!): https://github.com/Umbrella-IT-Group/metamcp
๐ข Update: [From the author: apologize for some recent maintainence delay, but will at least keep merging PRs, more background here]
MetaMCP is a MCP proxy that lets you dynamically aggregate MCP servers into a unified MCP server, and apply middlewares. MetaMCP itself is a MCP server so it can be easily plugged into ANY MCP clients.
For more details, consider visiting our documentation site: https://docs.metamcp.com
English | ็ฎไฝไธญๆ
๐ Table of Contents
๐ฏ Use Cases
๐ท๏ธ Group MCP servers into namespaces, host them as meta-MCPs, and assign public endpoints (SSE or Streamable HTTP), with auth. One-click to switch a namespace for an endpoint.
๐ฏ Pick tools you only need when remixing MCP servers. Apply other pluggable middleware around observability, security, etc. (coming soon)
๐ Use as enhanced MCP inspector with saved server configs, and inspect your MetaMCP endpoints in house to see if it works or not.
๐ Use as Elasticsearch for MCP tool selection (coming soon)
Generally developers can use MetaMCP as infrastructure to host dynamically composed MCP servers through a unified endpoint, and build agents on top of it.
Quick demo video: https://youtu.be/Cf6jVd2saAs

๐ Concepts
๐ฅ๏ธ MCP Server
A MCP server configuration that tells MetaMCP how to start a MCP server.
"HackerNews": {
"type": "STDIO",
"command": "uvx",
"args": ["mcp-hn"]
}๐ Environment Variables & Secrets (STDIO MCP Servers)
For STDIO MCP servers, MetaMCP supports three ways to handle environment variables and secrets:
1. Raw Values - Direct string values (not recommended for secrets):
API_KEY=your-actual-api-key-here
DEBUG=true2. Environment Variable References - Use ${ENV_VAR_NAME} syntax:
API_KEY=${OPENAI_API_KEY}
DATABASE_URL=${DB_CONNECTION_STRING}3. Auto-matching - If the expected environment variable name in your tool matches the container's environment variable, you can omit it entirely. MetaMCP will automatically pass through matching environment variables.
๐ Security Note: Environment variable references (
${VAR_NAME}) are resolved from the MetaMCP container's environment at runtime. This keeps actual secret values out of your configuration and git repository.
โ๏ธ Development Note: For local development with
pnpm run dev:docker, ensure your environment variables are listed inturbo.jsonunderglobalEnvto be passed to the development processes. This is not required for production Docker deployments.
๐ท๏ธ MetaMCP Namespace
Group one or more MCP servers into a namespace
Enable/disable MCP servers or at tool level
Apply middlewares to MCP requests and responses
Override tool names/titles/descriptions per namespace and attach custom MCP annotations (e.g.
{ "annotations": { "readOnlyHint": false } })
๐ MetaMCP Endpoint
Create endpoints and assign namespace to endpoints
Multiple MCP servers in the namespace will be aggregated and emitted as a MetaMCP endpoint
Choose between API-Key Auth (in header or query param) or standard OAuth in MCP Spec 2025-06-18
Host through SSE or Streamable HTTP transports in MCP and OpenAPI endpoints for clients like Open WebUI
โ๏ธ Middleware
Intercepts and transforms MCP requests and responses at namespace level
Built-in example: "Filter inactive tools" - optimizes tool context for LLMs
Future ideas: tool logging, error traces, validation, scanning
๐ Inspector
Similar to the official MCP inspector, but with saved server configs - MetaMCP automatically creates configurations so you can debug MetaMCP endpoints immediately.
โ๏ธ Tool Overrides & Annotations
Open a namespace โ Tools tab to see every tool coming from connected MCP servers.
Each saved tool can be expanded and edited inline: update the display name/title/description or provide a JSON blob with namespace-specific annotations (for example
{ "annotations": { "readOnlyHint": false } }).Badges in the table ("Overridden", "Annotations") show which tools currently have custom metadata. Hover them to read a tooltip describing what was overridden.
Annotation overrides are merged with whatever the upstream MCP server returns, so you can safely add custom UI hints without losing provider metadata.
๐ Quick Start
๐ณ Run with Docker Compose (Recommended)
Clone repo, prepare .env, and start with docker compose:
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
cp example.env .env
docker compose up -dIf you modify APP_URL env vars, make sure you only access from the APP_URL, because MetaMCP enforces CORS policy on the URL, so no other URL is accessible.
Note that the pg volume name may collide with your other pg dockers, which is global, consider rename it in docker-compose.yml:
volumes:
metamcp_postgres_data:
driver: local๐ฆ Build development environment with Dev Containers (VSCode/Cursor)
You can use the VSCode/Cursor extension to build the development environment in a container.
It only requires that you have an environment running Docker or a similar alternative (the docker/docker compose command is required), and no other dependent components need to be installed on your host machine.
First, clone the MetaMCP source code, open project in Visual Studio Code.
git clone https://github.com/metatool-ai/metamcp.git
cd metamcp
code .Switch to Dev Containers. Open the VSCode Command Palette, and execute
Dev Containers: Reopen in Container.
VSCode will open the Dev Containers project in a new window, where it will build the runtime and install the toolchain according to the Dockerfile before starting the connection and finally installing the MetaMCP dependencies.
note This process requires a reliable network connection, and it will access Docker Hub, GitHub, and some other sites. You will need to ensure the network connection yourself, otherwise the container build may fail.
Wait some minutes, depending on the internet connection or computer performance, it may take from a few minutes to tens of minutes, you can click on the Progress Bar in the bottom right corner to view a live log where you will be able to check unusual stuck.
After finished, you can run pnpm dev to start the development server.
๐ป Local Development
Still recommend running postgres through docker for easy setup:
pnpm install
pnpm dev๐ MCP Protocol Compatibility
โ Tools, Resources, and Prompts supported
โ OAuth-enabled MCP servers tested for 03-26 version
If you have questions, feel free to leave GitHub issues or PRs.
๐ Connect to MetaMCP
๐ E.g., Cursor via mcp.json
Example mcp.json
{
"mcpServers": {
"MetaMCP": {
"url": "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
}
}
}๐ฅ๏ธ Connecting Claude Desktop and Other STDIO-only Clients
Since MetaMCP endpoints are remote only (SSE, Streamable HTTP, OpenAPI), clients that only support stdio servers (like Claude Desktop) need a local proxy to connect.
Note: While mcp-remote is sometimes suggested for this purpose, it's designed for OAuth-based authentication and doesn't work with MetaMCP's API key authentication. Based on testing, mcp-proxy is the recommended solution.
Here's a working configuration for Claude Desktop using mcp-proxy:
Using Streamable HTTP
{
"mcpServers": {
"MetaMCP": {
"command": "uvx",
"args": [
"mcp-proxy",
"--transport",
"streamablehttp",
"http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/mcp"
],
"env": {
"API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
}
}
}
}Using SSE
{
"mcpServers": {
"ehn": {
"command": "uvx",
"args": [
"mcp-proxy",
"http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
],
"env": {
"API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
}
}
}
}Important notes:
Replace
<YOUR_ENDPOINT_NAME>with your actual endpoint nameReplace
<YOUR_API_KEY_HERE>with your MetaMCP API key (format:sk_mt_...)
For more details and alternative approaches, see issue #76.
๐ง API Key Auth Troubleshooting
?api_key=param api key auth doesn't work for SSE. It only works for Streamable HTTP and OpenAPI.Best practice is to use the API key in
Authorization: Bearer <API_KEY>header.Try disable auth temporarily when you face connection issues to see if it is an auth issue.
โ๏ธ Cold Start Problem and Custom Dockerfile
MetaMCP pre-allocate idle sessions for each configured MCP servers and MetaMCPs. The default idle session for each is 1 and that can help reduce cold start time.
If your MCP requires dependencies other than
uvxornpx, you need to customize the Dockerfile to install dependencies on your own.Check invalidation.md for a seq diagram about how idle session invalidates during updates.
๐ ๏ธ Solution: Customize the Dockerfile to add dependencies or pre-install packages to reduce cold start time.
๐งพ Log Levels
MetaMCPโs backend writes logs to files and optionally mirrors selected levels to the console. Control console mirroring with the LOG_LEVEL environment variable.
Files
app.log: receivesDEBUG,INFO, andWARNerror.log: receivesERROR
Console mirroring (
LOG_LEVEL)all: mirrorDEBUG,INFO,WARN,ERRORto consoleinfo: mirror onlyINFOto consoleerrors-only: mirrorWARNandERRORto consolenone: no console output
Defaults and examples
Default (when unset or invalid):
errors-only.envexample:LOG_LEVEL='errors-only' # 'all', 'info', 'errors-only', 'none'docker-compose.dev.ymluses:LOG_LEVEL: ${LOG_LEVEL:-all}
๐ Authentication
๐ก๏ธ Better Auth for frontend & backend (TRPC procedures)
๐ช Session cookies enforce secure internal MCP proxy connections
๐ API key authentication for external access via
Authorization: Bearer <api-key>header๐ชช MCP OAuth: Exposed endpoints have options to use standard OAuth in MCP Spec 2025-06-18, easy to connect.
๐ข Multi-tenancy: Designed for organizations to deploy on their own machines. Supports both private and public access scopes. Users can create MCPs, namespaces, endpoints, and API keys for themselves or for everyone. Public API keys cannot access private MetaMCPs.
โ๏ธ Separate Registration Controls: Administrators can independently control UI registration and SSO/OAuth registration through the settings page, allowing for flexible enterprise deployment scenarios.
๐ฆ Traffic Management
๐ง MCP Rate Limit
The MCP Rate Limit feature allows you to set the maximum requests a MCP tool (a endpoint) will accept in a given time window. There are two different strategies to set limits that you can use separately or together:
Endpoint rate-limiting (Rate Limiting): applies simultaneously to all clients using the endpoint, sharing a unique counter.User rate-limiting (Client Rate Limiting): sets a counter to each individual user.
Both types can coexist and they complement each other, and store the counters in-memory. On a cluster, each machine sees and counts only its passing traffic.
Endpoint rate-limiting
The endpoint rate limit acts on the number of simultaneous transactions an endpoint can process. This type of limit protects the service for all customers.
When the users connected to an endpoint together exceed the rate-limiting, MetaMCP starts to reject connections with a status code 503 Service Unavailable.
Endpoint rate-limiting options
Max Rate: Defines how many requests will you accept from all users together at any given instant. When the gateway starts, the bucket is full. As requests from users come, the remaining tokens in the bucket decrease. At the same time, the rate-limiting refills the bucket at the desired rate until its maximum capacity is reached.Max Rate Seconds: Time period in which the maximum rates operate in seconds. For instance, if you set an max rate seconds of 60s and a rate-limiting of 5, you are allowing 5 requests every sixty seconds.
User rate-limiting
The client or user rate limit applies one counter to each individual user and endpoint. When a single user connected to an endpoint exceeds their client-max-rate, MetaMCP starts rejecting connections with a status code 429 Too Many Requests
User rate-limiting options
Client Max Rate: Number of tokens you add to the Token Bucket for each individual user (user quota) in the time interval you want (Client Max Rate Seconds). The remaining tokens in the bucket are the requests a specific user can do.Client Max Rate Seconds: Time period in which the maximum rates operate in seconds. For instance, if you set an every of 60s and a rate of 5, you are allowing 5 requests every sixty seconds.Client Max Rate Strategy: Sets the strategy you will use to set client counters. Choose ip when the restrictions apply to the clientโs IP address, or set it to header when there is a header that identifies a user uniquely. That header must be defined with the key entry.Client Max Rate Strategy Key: It is the header name containing the user identification (e.g., Authorization on tokens, or X-Original-Forwarded-For for IPs).
๐ OpenID Connect (OIDC) Provider Support
MetaMCP supports OpenID Connect authentication for enterprise SSO integration. This allows organizations to use their existing identity providers (Auth0, Keycloak, Azure AD, etc.) for authentication.
๐ ๏ธ Configuration
Add the following environment variables to your .env file:
# Required
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration
# Optional customization
OIDC_PROVIDER_ID=oidc
OIDC_SCOPES=openid email profile
OIDC_PKCE=true๐ข Supported Providers
MetaMCP has been tested with popular OIDC providers:
Auth0:
https://your-domain.auth0.com/.well-known/openid-configurationKeycloak:
https://your-keycloak.com/realms/your-realm/.well-known/openid-configurationAzure AD:
https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configurationGoogle:
https://accounts.google.com/.well-known/openid-configurationOkta:
https://your-domain.okta.com/.well-known/openid-configuration
๐ Security Features
๐ PKCE (Proof Key for Code Exchange) enabled by default
๐ก๏ธ Authorization Code Flow with automatic user creation
๐ Auto-discovery of OIDC endpoints
๐ช Seamless session management with existing auth system
๐ฑ Usage
Once configured, users will see a "Sign in with OIDC" button on the login page alongside the email/password form. The authentication flow automatically creates new users on first login.
For more detailed configuration examples and troubleshooting, see CONTRIBUTING.md.
โ๏ธ Registration Controls
MetaMCP provides separate controls for different registration methods, allowing administrators to fine-tune user access policies for enterprise deployments.
๐๏ธ Available Controls
UI Registration: Controls whether users can create accounts via the registration form
SSO Registration: Controls whether users can create accounts via SSO/OAuth providers (OIDC, etc.)
๐ข Enterprise Use Cases
This separation enables common enterprise scenarios:
Block UI registration, allow SSO: Prevent manual signups while allowing corporate SSO users
Block SSO registration, allow UI: Allow manual signups while restricting SSO access
Block both: Completely disable new user registration
Allow both: Default behavior for open deployments
๐ ๏ธ Configuration
Access the Settings page in the MetaMCP admin interface to configure these controls:
Navigate to Settings โ Authentication Settings
Toggle "Disable UI Registration" to control form-based signups
Toggle "Disable SSO Registration" to control OAuth/OIDC signups
Both controls work independently, giving you full flexibility over your registration policy.
๐ Custom Deployment and SSE conf for Nginx
If you want to deploy it to a online service or a VPS, a instance of at least 2GB-4GB of memory is required. And the larger size, the better performance.
Since MCP leverages SSE for long connection, if you are using reverse proxy like nginx, please refer to an example setup nginx.conf.example
๐๏ธ Architecture
Frontend: Next.js
Backend: Express.js with tRPC, hosting MCPs through TS SDK and internal proxy
Auth: Better Auth
Structure: Standalone monorepo with Turborepo and Docker publishing
๐ Sequence Diagram
Note: Prompts and resources follow similar patterns to tools.
sequenceDiagram
participant MCPClient as MCP Client (e.g., Claude Desktop)
participant MetaMCP as MetaMCP Server
participant MCPServers as Installed MCP Servers
MCPClient ->> MetaMCP: Request list tools
loop For each listed MCP Server
MetaMCP ->> MCPServers: Request list_tools
MCPServers ->> MetaMCP: Return list of tools
end
MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
MetaMCP ->> MCPClient: Return aggregated list of tools
MCPClient ->> MetaMCP: Call tool
MetaMCP ->> MCPServers: call_tool to target MCP Server
MCPServers ->> MetaMCP: Return tool response
MetaMCP ->> MCPClient: Return tool response๐บ๏ธ Roadmap
Potential next steps:
๐ Headless Admin API access
๐ Dynamically apply search rules on MetaMCP endpoints
๐ ๏ธ More middlewares
๐ฌ Chat/Agent Playground
๐งช Testing & Evaluation for MCP tool selection optimization
โก Dynamically generate MCP servers
๐ i18n
See README-i18n.md
Currently en and zh locale are supported, but welcome contributions.
๐ค Contributing
We welcome contributions! See details at CONTRIBUTING.md
๐ License
MIT
Would appreciate if you mentioned with back links if your projects use the code.
๐ Credits
Some code inspired by:
Not directly used the code by took ideas from
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
This server cannot be deployed
Maintenance
Related MCP Connectors
Streamable HTTP MCP gateway for NV oOS fleets โ one API key, namespaced tools, quotas and policy.
MCP federation gateway: route, govern and observe agent tools across clouds and MCP servers.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Related MCP Servers
- AlicenseBqualityBmaintenanceA flexible proxy server that aggregates multiple backend MCP servers into a single interface using STDIO or SSE transports. It supports dynamic server management via an HTTP API and utilizes namespacing to prevent tool conflicts across connected services.31MIT
- FlicenseNot gradedqualityCmaintenanceEnables centralized routing, discovery, namespacing, and execution of tools from multiple remote MCP servers over HTTP/SSE, aggregating them behind a unified MCP gateway with dynamic server management.-
- AlicenseNot gradedqualityAmaintenanceAggregates and routes requests across multiple backend MCP servers, exposing their combined tools and resources through unified SSE, Streamable HTTP, or Stdio endpoints. Supports optional Web UI management, granular tool control, and endpoint authentication.120 npmMIT
- AlicenseNot gradedqualityAmaintenanceAggregates multiple backend MCP resource servers (Stdio, SSE, and Streamable HTTP) into a single unified endpoint exposed over SSE, Streamable HTTP, or Stdio. Enables routing of tool calls, resource access, and per-tool enable/disable or rename overrides through an optional web admin UI with configurable API key or bearer-token authentication.120 npmMIT