DOCSEARCHbyAlgolia
Submit Docs

MCPHub Documentation

repository·main·Indexed 25 days ago

https://github.com/samanhappy/mcphub

A unified management hub for Model Context Protocol (MCP) servers. MCPHub allows developers to organize multiple MCP servers into groups and expose them via HTTP/SSE endpoints for AI clients like Claude and Cursor. Key features include a management dashboard, a CLI for server and tool administration, and Smart Routing using vector semantic search (via PostgreSQL and pgvector) to reduce token consumption by utilizing meta-tools like search_tools and call_tool.

Tokens
72.8K
Snippets
184
Records
386
Agent score
80%

What's inside MCPHub

  1. Understand the MCPHub source code layout

    main

    When navigating the codebase, keep the following entry points and locations in mind:

    • Process Entrypoint: src/server.ts is the main entrypoint for the server process.
    • HTTP Routes: All API and service routes are defined in src/routes/index.ts.
    • Frontend Configuration: Proxy settings for the development environment are located in frontend/vite.config.ts.
    • Storage Modes: MCPHub supports two storage modes: file (default, uses mcp_settings.json) or PostgreSQL.

  2. Manage local MCPHub users

    main

    MCPHub provides an API to manage local username/password accounts. These users are stored in mcp_settings.json or the mcphub_user table if a database backend is enabled.

    Important Constraints:

    • Authentication: All user management endpoints require an authenticated admin (isAdmin: true).
    • Scope: This API manages local users only. OAuth/social accounts managed via Better Auth are stored in a separate table and must be accessed via /api/better-auth/*.
    • Identity: The username is the primary key. To rename a user, you must delete and recreate them.
    • Permissions: Server visibility is not managed within the user model itself; it is governed by the owner field on servers and group membership.

  3. Understand the MCPHub API structure

    main

    The MCPHub API is organized into two primary functional categories, all accessible under the /api base path.

    1. MCP Endpoints: Used for interacting with your MCP servers. These provide a unified interface for real-time request/response communication with your servers.
    2. Management API: Used for administrative tasks, such as managing servers, groups, users, and system settings.

    Note: Most Management API endpoints require authentication.

  4. What is Progressive Disclosure in MCPHub?

    main

    Progressive Disclosure is a global Smart Routing mode designed to optimize context usage.

    It works by adding the describe_tool Meta-tool to the client's scope and keeping full tool schemas out of initial search results, fetching them only on demand.

    Trade-off:

    • Upfront Cost: Increases the initial Smart Routing Footprint by one Meta-tool (describe_tool).
    • Runtime Benefit: Shrinks the size of individual search responses by deferring schema loading.

  5. How the shared embedding queue and pacing work

    main

    To prevent rate limiting and manage throughput, all embedding provider requests (whether for tool indexing or user queries) are processed through a shared queue.

    Key characteristics include:

    • Serialization: Parallel syncs do not bypass rate limits because they share the same queue.
    • Adaptive Pacing: The system applies an adaptive pacing delay to requests within the queue.
    • Retry Policy: Requests are executed with a built-in retry policy.
    • Error Handling: If a request fails after retries, curated error details are logged and the failure is propagated.

    Note: The Fallback Embedding Path is the only path that bypasses this shared queue.

  6. How MCP Apps proxying works in MCPHub

    main

    MCPHub acts as a transparent proxy for MCP Apps. It forwards UI-linked tool metadata, app-only tools, ui:// resources, and upstream list-change notifications.

    Note: MCPHub does not render the actual app UIs in its dashboard; it only handles the protocol-level proxying.

    Support is enabled automatically when a downstream host advertises the io.modelcontextprotocol/ui extension with the text/html;profile=mcp-app MIME type. No manual configuration switch is required.

  7. How tool indexing builds searchable text

    main

    When indexing tools, MCPHub constructs a searchable text payload for each tool to be embedded. The payload is built by combining the following elements:

    • Tool name
    • Tool description
    • Top-level schema property names
    • Nested input schema property names

    This combined text is then sent to the embedding provider or the fallback generator.

  8. Configure database vector dimensions and indexing strategy

    main

    MCPHub automatically manages database schema and indexing based on the dimensions of the generated embeddings. If dimensions change during a server sync, a full resynchronization is scheduled.

    Indexing Strategy by Dimension Count

    DimensionsTypeIndex Strategy
    Up to 2000vectorHNSW (fallback to IVFFlat)
    2001 to 4000halfvecHNSW (if supported by pgvector)
    More than 4000N/ANo optimized vector index created

    Schema Management Logic

    When a sync detects a dimension mismatch:

    1. If the database has no dimensions yet, it prepares a fresh schema.
    2. If incompatible rows exist, they are deleted.
    3. The existing vector index is dropped.
    4. The column type is altered to either vector or halfvec with the target dimensions.
    5. A new best-available vector index is created.

  9. Use Bearer Keys for long-lived access

    main

    Bearer keys are long-lived static tokens managed at /api/auth/keys. They are ideal for automated tools or MCP transport credentials.

    • Header: Use Authorization: Bearer <token> (the header name can be customized via systemConfig.routing.bearerAuthHeaderName, defaulting to Authorization).
    • Kinds:
      • system: Operator-managed scoped keys. If accessType is all, they can access the dashboard/management API. If restricted, they are enforced at the MCP transport layer.
      • user: Inherit the owner's visibility. These are MCP transport credentials only and cannot be used for the dashboard/management API.
    • Access Types: all (dashboard + MCP) or a scoped value for MCP-only access.

    To globally disable bearer authentication on MCP endpoints, set systemConfig.routing.enableBearerAuth to false.

  10. Accessing UI Resources in MCP Apps

    main

    MCP Apps servers may omit UI-only resources from their standard resources/list response.

    On an eligible MCP Apps route, MCPHub will forward direct resources/read calls for unlisted ui:// URIs to the single upstream server.

    Outside of eligible Apps routes, Apps-specific metadata is removed, though ordinary listed resources remain readable.

  11. Understand the tool indexing and database persistence flow

    main

    Tool indexing follows a Two-Phase Memory-First Sync to prevent database connection timeouts and improve UI responsiveness:

    Phase 1: In-Memory Generation

    • MCPHub sequentially generates embeddings for all tools for a specific server and model.
    • Results are kept in memory.
    • Progress: Emits incremental in_progress updates for each tool so the UI can update.

    Phase 2: Database Persistence

    • After all embeddings are generated, MCPHub probes the DB connection and performs a dimension compatibility check.
    • Embeddings are written to the database in a tight loop.
    • Progress: Emits a single completed event after all embeddings are saved.

    Skip-Check Optimization

    To avoid unnecessary re-generation, MCPHub performs a check before Phase 1. It skips regeneration only if:

    1. The number of existing embeddings matches the current tool count.
    2. The set of content IDs matches exactly.
    3. The toolSetHash (derived from name, description, and input schema) in the stored metadata matches the current tool list hash.

  12. How per-session client isolation works

    main

    By default, MCPHub maintains a single upstream connection per server and shares it across all downstream MCP sessions. This is efficient for stateless servers but problematic for stateful servers (like Playwright) where sessions might interfere with each other.

    To isolate sessions, set perSessionClient: true. This instructs MCPHub to open a dedicated upstream client per downstream session.

    • For stdio servers, this creates a new child process per session.
    • For remote servers, this creates a new connection per session.
    • Connections are created lazily on the first tool call and torn down when the session ends.

    Note: This setting is MCPHub-side and controls connection multiplexing. It is distinct from server-side isolation flags (e.g., Playwright's --isolated flag).

    {
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
      "perSessionClient": true
    }
  }
}