MCPHub v1.2.0

MCPHub v1.2.0

MCPHub v1.2.0 adds an opt-in, loopback-only administration platform for persisted configuration and exposes HTTP-backed tools through MCP. The v1.1.0 protocol and deployment boundaries remain in place; tool groups are managed in the local admin API and SQLite, not in YAML.

Repository: SamuelSupe/mcphub · module: github.com/SamuelSupe/mcphub · license: Apache License 2.0

English

Highlights

• Adds an embedded administration UI and JSON API on a numeric loopback listener. The admin surface is local-only, checks the remote address, Host, and Origin, and does not provide a remote login boundary.
• The embedded admin UI is available in Chinese and English, with the selected language persisted for subsequent visits.
• Adds SQLite persistence for managed configuration. Existing YAML backends can be bootstrapped on the first managed start; after that, SQLite is the source of truth. Static headers and OAuth client secrets are encrypted with AES-256-GCM and API responses expose configuration markers rather than secret values.
• Adds HTTP tool groups with a shared HTTPS Base URL, static headers or OAuth client-credentials settings, required scopes, optional tool rules, request timeout, and response-size limit. A group-level probe records the latest connectivity result.
• Adds manually defined HTTP API tools with a name, description, method, relative path, parameters, JSON request-body schema, and JSON output schema. They use the group’s shared connection and policy settings.
• Adds OpenAPI 3.0.x and 3.1.x imports from an uploaded document or an HTTPS URL. The inspect endpoint previews eligible operations; selected operations are persisted as generated HTTP tools and remain managed through their import source.
• Adds scheduled URL refresh and an explicit refresh endpoint. URL imports default to a 15-minute interval and accept 1 minute through 24 hours. A failed refresh records status, backs off, and keeps the last-known-good document and generated tools active.
• Exposes both manual and imported HTTP tools only as MCP tools under /mcp (public names use the <groupID>.<toolName> form). This release does not add a raw HTTP proxy or an arbitrary method/path endpoint.
• Applies bounded outbound behavior: HTTP tool responses default to 1 MiB and can be configured from 64 KiB through 16 MiB; OpenAPI documents are limited to 5 MiB and admin JSON requests carrying a document to 6 MiB. Base/spec fetches require HTTPS and do not follow redirects; cross-origin OpenAPI fetches do not send the group’s headers or OAuth credentials.
• Carries forward the v1.1.0 MCP aggregation, OIDC/JWKS, resource/subscription, streaming, and deployment boundaries; see the v1.1.0 release notes.

Administration API

The local admin API is rooted at /api/v1 and exposes these stable resource families. Request and response bodies use the user-level configuration concepts above; this release note does not define a complete wire schema.

Resource	Endpoints
Tool groups	GET/POST /api/v1/tool-groups; GET/PUT/DELETE /api/v1/tool-groups/{groupID}; POST /api/v1/tool-groups/{groupID}/probe
Manual HTTP tools	GET/POST /api/v1/tool-groups/{groupID}/tools; GET/PUT/DELETE /api/v1/tool-groups/{groupID}/tools/{toolName}
OpenAPI imports	POST /api/v1/tool-groups/{groupID}/imports/inspect; GET/POST /api/v1/tool-groups/{groupID}/imports; GET/PUT/DELETE /api/v1/tool-groups/{groupID}/imports/{importID}; POST /api/v1/tool-groups/{groupID}/imports/{importID}/refresh

Individual group, manual-tool, and import resources return an ETag. Their PUT and DELETE operations require the matching If-Match revision; import refresh also requires If-Match. Stale revisions fail with a conflict so an administrator can reread before applying a change. Imported tools cannot be edited or deleted as manual tools; update the owning import instead.

Security and operational boundaries

• Keep the admin listener numeric loopback-only and do not publish it through a reverse proxy. It is intentionally a local administration surface, not a remotely authenticated control plane.
• Protect the SQLite database, its WAL/SHM files, and MCPHUB_CONFIG_KEY (a Base64-encoded 32-byte key). The admin API never returns header values or OAuth client secrets.
• Group Base URLs and OpenAPI source URLs must be HTTPS without credentials, query strings, or fragments. Source requests never follow redirects. A same-origin OpenAPI source may use the group’s configured outbound credentials; a cross-origin source is fetched without those secrets.
• MCP access remains the public /mcp boundary and uses the existing bearer-token policy. HTTP tools do not create a second public HTTP surface.

Upgrade notes

• Existing v1.1.0 YAML-only deployments continue to use their YAML backend configuration while admin.enabled is false (the default). No HTTP tool-group YAML schema is introduced.
• To enable managed administration, configure a writable SQLite path, keep the listener on numeric loopback, and provide MCPHUB_CONFIG_KEY. On the first managed start, YAML backends are imported into SQLite in one transaction; later backend changes are made through the admin API and SQLite becomes authoritative.
• Create tool groups, manual HTTP tools, and OpenAPI imports through the local admin API. Review Base URL, OAuth/header scope, response limits, and OpenAPI selections before enabling them; never place their secrets in a committed YAML file.
• Before upgrading a deployment that exposes an admin listener through a proxy, remove that exposure or keep the listener disabled. Verify downloaded archives with SHA256SUMS before replacing the running binary.

Release assets

The tag-triggered GitHub Actions workflow .github/workflows/release.yml builds and publishes the following archives and checksum file. Each archive contains the binary, example configuration, license, and English/Chinese READMEs. Verify every downloaded archive against SHA256SUMS.

Platform	Download
macOS amd64	mcphub_v1.2.0_darwin_amd64.tar.gz
macOS arm64	mcphub_v1.2.0_darwin_arm64.tar.gz
Linux amd64	mcphub_v1.2.0_linux_amd64.tar.gz
Linux arm64	mcphub_v1.2.0_linux_arm64.tar.gz
Checksums	SHA256SUMS

中文

MCPHub v1.2.0 增加可选的、仅限回环地址的内嵌管理平台，用于持久化配置，并将 HTTP 后端能力以 MCP tool 形式暴露。v1.1.0 的协议和部署边界保持不变；工具组只通过本地管理 API 和 SQLite 管理，不加入 YAML schema。

仓库：SamuelSupe/mcphub · module：github.com/SamuelSupe/mcphub · 许可证：Apache License 2.0

主要变化

• 增加绑定数字回环地址的内嵌管理 UI 和 JSON API。管理面检查远端地址、Host、Origin，仅供本机使用，不提供远程登录边界。
• 内嵌管理 UI 支持中文和 English，并会持久保存所选语言，后续访问继续使用该语言。
• 增加 SQLite 托管配置持久化。首次启用托管模式时可将已有 YAML backend 一次性导入；之后 SQLite 成为唯一事实源。静态 Header 和 OAuth client secret 使用 AES-256-GCM 加密，API 响应只返回已配置标记，不返回 secret 值。
• 增加 HTTP 工具组：组内共享 HTTPS Base URL、静态 Header 或 OAuth client-credentials、required scopes、可选 tool rules、请求超时和响应大小上限；可通过 group-level probe 记录最近连通性结果。
• 增加手工 HTTP API tools：配置 name、description、method、相对 path、参数、JSON 请求 body schema 和 JSON 输出 schema，并复用工具组的连接与策略配置。
• 支持从上传文档或 HTTPS URL 导入 OpenAPI 3.0.x/3.1.x。inspect 接口可预览可转换 operation；选中的 operation 持久化为生成的 HTTP tools，并由所属 import 统一管理。
• 增加 URL 定时刷新和显式 refresh 接口。URL import 默认每 15 分钟刷新，可配置范围为 1 分钟到 24 小时。刷新失败会记录状态并退避，继续使用 last-known-good 文档及其生成 tools。
• 手工和导入的 HTTP tools 仅作为 /mcp 下的 MCP tools 暴露（公开名称为 <groupID>.<toolName>），不增加 raw HTTP proxy 或任意 method/path 接口。
• 限制出站大小和来源：HTTP tool 响应默认 1 MiB，可配置范围 64 KiB–16 MiB；OpenAPI 文档上限 5 MiB，携带文档的管理 JSON 请求上限 6 MiB。Base/spec fetch 必须使用 HTTPS 且不跟随重定向；跨源 OpenAPI fetch 不发送工具组 Header 或 OAuth 凭据。
• 延续 v1.1.0 的 MCP 聚合、OIDC/JWKS、资源/订阅、streaming 和部署边界；详见 v1.1.0 发行说明。

管理 API

本地管理 API 根路径为 /api/v1，提供以下稳定资源族。请求和响应使用上文用户级配置概念；本发行说明不定义完整 wire schema。

资源	接口
工具组	GET/POST /api/v1/tool-groups；GET/PUT/DELETE /api/v1/tool-groups/{groupID}；POST /api/v1/tool-groups/{groupID}/probe
手工 HTTP tools	GET/POST /api/v1/tool-groups/{groupID}/tools；GET/PUT/DELETE /api/v1/tool-groups/{groupID}/tools/{toolName}
OpenAPI imports	POST /api/v1/tool-groups/{groupID}/imports/inspect；GET/POST /api/v1/tool-groups/{groupID}/imports；GET/PUT/DELETE /api/v1/tool-groups/{groupID}/imports/{importID}；POST /api/v1/tool-groups/{groupID}/imports/{importID}/refresh

单个工具组、手工 tool 和 import 资源会返回 ETag。它们的 PUT、DELETE 必须携带匹配的 If-Match revision；import 的 refresh 同样需要 If-Match。revision 过期时返回冲突，管理端应重新读取后再提交。OpenAPI 生成的 tool 不能按手工 tool 修改或删除，应通过所属 import 管理。

安全和运行边界

• 管理 listener 必须保持数字回环地址，不要通过反向代理发布。这是刻意设计的本地管理面，不是远程认证控制面。
• 保护 SQLite 数据库、WAL/SHM 文件以及 MCPHUB_CONFIG_KEY（Base64 编码的 32 字节 key）。管理 API 永不返回 Header 值或 OAuth client secret。
• 工具组 Base URL 和 OpenAPI source URL 必须为不含凭据、query、fragment 的 HTTPS URL；source 请求不跟随重定向。同源 OpenAPI source 可使用工具组出站凭据，跨源 source fetch 不携带这些 secret。
• MCP 的公开边界仍是 /mcp，沿用现有 bearer token 策略；HTTP tools 不会形成第二个公开 HTTP 面。

升级注意事项

• 当 admin.enabled 为 false（默认）时，已有 v1.1.0 YAML-only 部署继续使用 YAML backend 配置；本版本不引入 HTTP 工具组 YAML schema。
• 启用托管管理前，配置可写的 SQLite 路径、保持数字回环 listener，并提供 `...

MCPHub v1.1.0

MCPHub v1.1.0

MCPHub v1.1.0 adds backend-local tool scope policies while preserving the v1.0.0 protocol and deployment boundaries. The previous v1.0.0 release remains available as historical reference.

Repository: SamuelSupe/mcphub · module: github.com/SamuelSupe/mcphub · license: Apache License 2.0

English

Highlights

• Adds backend-local tool_rules. Each rule has a match glob and required_scopes.
• Evaluates match with Go path.Match against the original backend tool name before the backend ID is added; matching is full-string and case-sensitive.
• Expands existing ${ENV} placeholders in match and rule scope strings. Validation requires every match to be non-empty and a valid Go path.Match pattern, every rule to declare non-empty required_scopes entries with no whitespace or duplicates, and rejects duplicate match entries within one backend.
• Unions and deduplicates scopes from every matching rule, then requires all distinct rule scopes together with the backend-level required_scopes.
• Hides unauthorized tools from tools/list. A known direct call without the required scopes returns 403 with WWW-Authenticate: Bearer error="insufficient_scope", resource_metadata="<path-aware metadata URL>", scope="<space-delimited missing scopes>".
• Keeps unmatched rules valid and emits one warning per catalog generation; a later catalog refresh can make the same rule match.
• Reloads backend-local tool_rules through SIGHUP with the backend policy. Rule changes do not change catalog-source identity, so they remain compatible with the existing optional-backend catalog reuse boundary.
• Carries forward the v1.0.0 MCP aggregation, OIDC/JWKS, resource/subscription, streaming, and deployment boundaries; see the v1.0.0 historical release notes.

Release assets

The tag-triggered GitHub Actions workflow .github/workflows/release.yml builds and publishes the following archives and checksum file. Each archive contains the binary, example configuration, license, and English/Chinese READMEs. Verify every downloaded archive against SHA256SUMS.

Platform	Download
macOS amd64	mcphub_v1.1.0_darwin_amd64.tar.gz
macOS arm64	mcphub_v1.1.0_darwin_arm64.tar.gz
Linux amd64	mcphub_v1.1.0_linux_amd64.tar.gz
Linux arm64	mcphub_v1.1.0_linux_arm64.tar.gz
Checksums	SHA256SUMS

中文

MCPHub v1.1.0 在保持 v1.0.0 协议与部署边界的同时，增加了后端本地的工具级 scope 策略。上一版 v1.0.0 仍作为历史版本保留。

仓库：SamuelSupe/mcphub · module：github.com/SamuelSupe/mcphub · 许可证：Apache License 2.0

主要变化

• 增加 backend-local tool_rules。每条规则包含 match glob 和 required_scopes。
• 在添加 backend ID 形成公开名称之前，使用 Go path.Match 针对原始 backend tool name 匹配；匹配为整串且区分大小写。
• match 和规则 scope 字符串支持现有 ${ENV} 展开。配置校验要求每个 match 非空且为有效的 Go path.Match 模式，每条规则声明非空的 required_scopes，其项不能含空白或重复，并拒绝同一 backend 内重复的 match。
• 合并并去重所有匹配规则的 scope，再要求这些不同的规则 scope 与 backend 级 required_scopes 一起全部满足。
• 未授权 tool 从 tools/list 中隐藏。已知 tool 在缺少所需 scope 时被直接调用，返回 403，并带有 WWW-Authenticate: Bearer error="insufficient_scope", resource_metadata="<path-aware metadata URL>", scope="<space-delimited missing scopes>"。
• 规则当前目录 generation 没有匹配项时仍保持有效，并且每个目录 generation 只 warning 一次；后续目录刷新出现匹配 tool 后即可生效。
• backend-local tool_rules 支持通过 SIGHUP 随 backend policy 热重载。规则变化不改变目录来源身份，因此仍符合现有 optional backend 目录复用边界。
• 延续 v1.0.0 的 MCP 聚合、OIDC/JWKS、资源/订阅、streaming 和部署边界；详见 v1.0.0 历史发行说明。

发布资产

由 tag 触发的 GitHub Actions workflow .github/workflows/release.yml 构建并发布以下归档和校验文件。每个归档包含二进制、示例配置、许可证及中英文 README；下载后请使用 SHA256SUMS 校验。

平台	下载
macOS amd64	mcphub_v1.1.0_darwin_amd64.tar.gz
macOS arm64	mcphub_v1.1.0_darwin_arm64.tar.gz
Linux amd64	mcphub_v1.1.0_linux_amd64.tar.gz
Linux arm64	mcphub_v1.1.0_linux_arm64.tar.gz
校验和	SHA256SUMS

MCPHub v1.0.0

MCPHub v1.0.0

This is the initial release. / 这是初始版本。

Repository: SamuelSupe/mcphub · module: github.com/SamuelSupe/mcphub · license: Apache License 2.0 · GitHub release

English

Included

• A Go 1.26 MCP aggregation gateway with serve and validate commands.
• Streamable HTTP connections to multiple MCP backends, paginated catalogs with parallel tools/prompts/resources/resource-template discovery, refresh, reconnect handling, last-known-good catalogs, and required/optional backend readiness.
• Aggregated tools, prompts, resources, resource templates, completion, resource subscriptions, resource updates, and streaming progress forwarding. Backend SSE is passed through unchanged; progress inspection buffers at most 1 MiB per event, and an oversized event is forwarded without progress inspection.
• ResourceLink, EmbeddedResource, and ResourceContents URIs in backend tool, prompt, or resource results are rewritten and recorded as issued resources rather than added individually to the public resources catalog. Each backend retains at most 16,384 distinct issued-URI SHA-256 digests; eviction of the oldest digest may make a new read or subscription fail, while existing subscription cancellation/session cleanup still follows the session map. Resource-updated notifications do not create entries. Subscriptions are tracked/deduplicated per upstream MCP session, use shared backend reference counts, ignore unpaired unsubscribe, and restore after reconnect, waiting for notifications/subscriptions/acknowledged when the backend protocol supports that acknowledgement before readiness. An acknowledged subscription ID maps updates back to its original subscription URI(s), including when the update event URI differs; timeout, cancellation, and session/reconnect cleanup remove the mapping. A canceled or disconnected modern subscriptions/listen stream detaches cleanup from its canceled upstream context but remains bounded by the backend timeout and session lifecycle, so legacy backends still receive resources/unsubscribe.
• Compatibility normalization adds missing 2026-07-28 metadata on notifications/cancelled for official Go MCP SDK v1.7.0 messages on both Hub ingress and backend egress, keeping the same logical MCP session reusable after cancellation or unsubscribe without advertising a custom extension.
• Backend namespaced routing and deterministic resource/resource-template URI rewriting. Backend IDs may contain uppercase letters but are unique case-insensitively; tool/prompt names retain the configured ID, while resource/template URI authorities use lowercase.
• OIDC discovery/JWKS Bearer JWT verification with exact issuer checks and aud validation requiring server.public_url as the string value or as an element of the audience array, initial readiness requiring successful discovery, an absolute HTTPS jwks_uri, and a reachable JWKS containing at least one parseable, valid, asymmetric public verification key (symmetric oct keys and invalid or empty keys are rejected), required sub/exp, optional nbf, 30-second clock skew, and merged claims (scope is a space-delimited string; scp is a string or string array). OIDC discovery and JWKS responses are each capped at 1 MiB; later refresh failures retain the last-known-good verifier.
• OIDC readiness accepts a JWKS when at least one public asymmetric verification key is usable: use is empty or sig, any key_ops includes verify, and an explicit alg matches a supported RSA, EC, or Ed25519 JWS algorithm declared by id_token_signing_alg_values_supported; if discovery omits that list, RS256 is assumed. Malformed or unsupported keys in the same JWKS do not hide another usable key.
• Per-backend all-of required_scopes filtering and insufficient_scope challenges.
• Static backend headers or OAuth 2.0 client_credentials with separate token-endpoint transport, RFC 8414/OIDC issuer/token-endpoint discovery (without interactive PKCE metadata), 1 MiB metadata caps, token reuse, and redirect refusal.
• Strict YAML validation, string-only ${NAME} environment expansion, HTTPS-by-default URL policy, loopback-only explicit HTTP, exact CORS origins and header allowlist with preflight method POST (OPTIONS response), request-timeout read deadlines for unconsumed bodies on every HTTP route (including unauthenticated/rejected slow bodies), ordinary body/read/write/request timeouts, and the newer subscriptions/listen POST long-lived exception, plus rejection of transport-managed headers including Proxy-Authorization and Proxy-Authenticate and SIGHUP reload with restart-only invariants.
• /healthz, /readyz, and both RFC 9728 Protected Resource Metadata paths.
• A nonroot distroless Docker image.

Security and operational notes

• Require server.public_url to appear in JWT aud, including the MCP path: a string aud equals public_url, while an audience array contains public_url.
• server.public_url rejects percent-encoded path characters and reserves /healthz, /readyz, and /.well-known/oauth-protected-resource.
• Use HTTPS for public, issuer, and remote backend URLs. Use allow_insecure_http: true only for loopback development backends.
• Keep secrets in the environment or an external secret store; do not commit config.yaml or .env.
• Route both metadata paths through the trusted reverse proxy and restrict unauthenticated health/readiness/metadata visibility as appropriate.
• The stateless /mcp entry accepts POST only; modern clients may use request-scoped SSE in the POST response, while MCPHub provides no standalone GET SSE or DELETE session endpoint. Compatibility clients use the same /mcp POST semantics.
• A required backend can make /readyz return 503 while the process continues reconnecting. SIGHUP rejects changes to server.listen, server.public_url, and auth.issuer.
• Backend-authored JSON-RPC errors are preserved unchanged; network or transport failures expose only backend <id> unavailable, avoiding leakage of internal backend URLs, query strings, or credentials.
• SIGINT/SIGTERM stop new requests, keep the current runtime and backend context during the drain_timeout HTTP drain, force-close remaining HTTP connections if that drain times out, and then cancel request contexts bound to the retiring generation before closing its backend state. Runtime cancellation after the drain, or client cancellation at any time, expires the underlying write deadline and interrupts slow or unread subscription writes; ordinary requests retain request_timeout.
• All tracked resource subscriptions must restore successfully before a reconnecting backend becomes ready; on protocol versions that support it, each restore also waits for notifications/subscriptions/acknowledged; a restore or acknowledgement failure keeps the backend unavailable and triggers another reconnect attempt.
• SIGHUP candidate startup uses a cancelable context; shutdown cancels a candidate that is still connecting. Required backends must connect successfully before the candidate replaces the current generation, and each candidate or retired generation closes its own backend sessions and connections.
• Every HTTP route keeps the request_timeout request-body read deadline until the body is consumed or closed, including unauthenticated and rejected requests with slow bodies. A subscriptions/listen POST is exempt from ordinary response-write and request-context timeouts only after its body has been read, but runtime/client cancellation can still expire its underlying write deadline.
• On SIGHUP, an unavailable optional backend reuses its previous in-memory catalog only when backend ID/URL, allow_insecure_http, every fixed header, and the complete OAuth configuration (including presence, type, issuer, client_id, client_secret, and scopes) are unchanged. Credential, OAuth, or tenant-selection-header changes block reuse; required, required_scopes, and timeout changes do not, and reuse never marks the new backend ready.
• Overlong or invalid request IDs are regenerated; capability and resource-URI log fields are validated/sanitized, and request failures record only external error types.

Explicit limits

This release does not provide stdio, a standalone legacy GET SSE endpoint, native TLS, a database, dynamic tenants or per-user backend credentials, opaque-token introspection, Tasks, MCP Apps, or custom MCP extensions. TLS termination and external rate limiting remain deployment responsibilities.

中文

仓库：SamuelSupe/mcphub · module：github.com/SamuelSupe/mcphub · 许可证：Apache License 2.0 · GitHub release

已包含

• Go 1.26 MCP 聚合网关，以及 serve 和 validate 命令。
• 连接多个 MCP 后端的 Streamable HTTP、目录分页及 tools/prompts/resources/资源模板并行发现、刷新、重连、last-known-good 目录，以及 required/optional 后端就绪语义。
• 聚合 tools、prompts、resources、资源模板、completion、资源订阅、资源更新和 streaming progress 转发。后端 SSE 原样透传；progress 检查每个 event 最多缓存 1 MiB，超大 event 原样转发但跳过 progress 检查。
• 后端 tool、prompt 或 resource 结果中的 ResourceLink、EmbeddedResource、ResourceContents URI 会被改写并记录为已签发资源，不会逐项加入公开 resources 目录。每个 backend 最多保留 16,384 个不同的已签发 URI SHA-256 摘要；淘汰最旧摘要后，新 read 或 subscription 可能失败，但已有订阅的取消/session 清理仍按 session 映射处理。resource-updated 通知不会创建目录项。订阅按 upstream MCP session 跟踪/去重，后端引用共享计数，未配对取消订阅会忽略，重连后恢复；backend protocol 支持时还要等待 notifications/subscriptions/acknowledged，再允许 ready。确认中的 subscription ID 会把更新映射回原订阅 URI，包括 update event URI 不同的情况；timeout、取消订阅和 session/重连清理会删除映射。现代 subscriptions/listen stream 取消或断连时，清理会脱离已取消的 upstream context，但仍受 backend timeout 和 session lifecycle 约束，因此旧协议 backend 仍会收到 resources/unsubscribe。
• 针对官方 Go MCP SDK v1.7.0 的 notifications/cancelled 消息缺少 2026-07-28 metadata，Hub 入站和后端出站都会做兼容规范化，使取消或取消订阅后的同一逻辑 MCP se...