MCP Hub

MCP Knot

English | 中文版

Knot —— 纽带、交织点。多个 MCP server 像散落的线，MCP Knot 把它们打成一个结，成为所有工具交汇的轻量枢纽。

Tie your MCP servers together.

A centralized hub server engineered to consolidate multiple MCP servers into dedicated Streamable HTTP or SSE endpoints, each tailored to specific use scenarios — lightweight, zero-config, and leading on the 2026-07-28 stateless MCP protocol.

Features

• Multi-server MCP Integration: Support for multiple MCP servers with centralized management
• Group-based Routing: Access MCP services through group-specific endpoints (/:group/mcp)
• Versioned Skills Distribution: Import selected skills from local directories, public Git repositories or the skills CLI, then publish fixed snapshots alongside tools through a Group endpoint. See the Skills guide.
• CLI MCP Server: Standalone command-line MCP server for tool aggregation
• Streamable Endpoints: Support for both HTTP and SSE endpoints
• Tool Filtering: Groups support tool filtering and screening capabilities
• Validation Support: Groups can set separate validation keys for security
• Modular Architecture: Clean separation between core logic, API, and CLI packages

Architecture

MCP Knot follows a modular monorepo architecture with the following packages:

Core Packages

• @mcp-core/mcp-knot-core - Core MCP service management, connection handling, and tool execution
• @mcp-core/mcp-knot-api - Web API server with group-based routing and HTTP endpoints
• @mcp-core/mcp-knot-cli - Command-line MCP server for standalone tool aggregation
• @mcp-core/mcp-knot-protocol - Protocol compatibility layer: dual-era (modern/legacy) translation, normalized models, unified errors
• @mcp-core/mcp-knot-share - Shared types and utilities across packages
• @mcp-core/mcp-knot-web - Vue.js frontend interface (optional)

Package Structure

├── backend/              # API server (@mcp-core/mcp-knot-api)
├── frontend/             # Vue.js web interface
├── packages/
│   ├── core/            # Core MCP logic (@mcp-core/mcp-knot-core)
│   ├── cli/             # CLI package (@mcp-core/mcp-knot-cli)
│   ├── protocol/        # Protocol compatibility layer (@mcp-core/mcp-knot-protocol)
│   └── share/           # Shared types (@mcp-core/mcp-knot-share)
└── docs/                # Documentation

Installation

Prerequisites

• Node.js 22.20+ (Node 24 recommended)
• pnpm package manager

Install Dependencies

# Install all dependencies
pnpm install

# Build all packages
pnpm build

Quick Start

1. API Server (Web Interface)

Start the API server for web-based MCP hub functionality:

# Development mode
pnpm dev:api

# Production build and start
pnpm build
cd backend && pnpm start

The API server will be available at http://localhost:8181 with the following endpoints:

• /mcp - Global MCP endpoint (legacy, for management)
• /:group/mcp - Group-specific MCP endpoints
• /api/groups - Group management API
• /api/skills - Administrator APIs for skill sources, synchronization and market search
• /api/config - System configuration management API
• /api/servers - MCP server management API
• /api/tools - Tool management and execution API
• /api/debug - Debugging and monitoring API

2. CLI MCP Server

Use the CLI package as a standalone MCP server:

# Install CLI globally (optional)
npm install -g @mcp-core/mcp-knot-cli

# Or run directly from workspace
cd packages/cli
pnpm build
node dist/cli.js

# Or use the executable
./bin/mcp-knot.js

Quick Configuration Initialization

MCP Knot CLI provides quick configuration initialization to help you get started quickly:

# View all available commands
mcp-knot --help

# Initialize default configuration (includes common server examples)
mcp-knot --init

# Initialize all configurations (includes group configuration)
mcp-knot --init-all

# List all available server presets
mcp-knot --list-presets

# Overwrite existing configuration files
mcp-knot --init-all --overwrite

The default configuration includes these commonly used MCP servers:

• fetch: Web fetching and HTTP requests
• time: Time and date functionality
• sequential-thinking: Sequential thinking capabilities

More available server presets:

• filesystem: File system operations
• memory: Persistent memory storage
• brave-search: Brave search engine
• github: GitHub repository management

The CLI server communicates via stdin/stdout using the MCP protocol, perfect for integration with MCP clients like Claude Desktop.

3. Frontend Interface (Optional)

Start the web interface for visual management:

# Development mode
pnpm dev:fe

# Production build
pnpm build:fe

The frontend will be available at http://localhost:8180 (development) or served through the backend in production.

Web Interface Features

The frontend provides a comprehensive web-based management interface with the following features:

1. Authentication & Security

• JWT Authentication: Secure login system with token-based authentication
• Automatic Token Refresh: Seamless session management without interruption
• Route Guards: Protected pages requiring authentication
• Persistent Sessions: Remember user login state across browser sessions
• Default Credentials: Username: admin, Password: admin (change in production!)

2. Dashboard & Monitoring

• System Overview: Real-time statistics of servers, tools, and groups
• Live Status Updates: Server-Sent Events (SSE) for real-time monitoring
• Performance Metrics: Request rates, response times, and error rates
• Activity Feed: Recent system activities and events
• Health Monitoring: System health checks and alerts

3. Server Management

• Server List: View all configured MCP servers with status indicators
• Add/Edit Servers: Visual forms for server configuration
• Connection Control: Connect, disconnect, and test server connections
• Status Monitoring: Real-time server connection status
• Configuration Validation: Test server configurations before saving

4. Tool Management

• Tool Browser: Browse all available MCP tools across servers
• Tool Search & Filter: Find tools by name, server, or group
• Tool Testing: Interactive tool execution with parameter input
• Execution History: View past tool executions and results
• Tool Details: Complete tool documentation and schema information

5. Group Management

• Group Configuration: Create and manage server groups
• Member Management: Assign servers to groups
• Tool Filtering: Configure which tools are available per group
• Validation Keys: Set and manage group-level authentication
• Group Statistics: Usage statistics and performance metrics

6. API to MCP Integration

• API Configuration: Convert REST APIs to MCP tools
• Parameter Mapping: Visual editor for API-to-MCP parameter mapping
• API Testing: Test API configurations before deployment
• Import/Export: Share API configurations across environments
• Auto-generation: Automatically generate MCP tools from API specs

7. Debug & Development Tools

• MCP Protocol Monitor: View raw MCP protocol messages
• Tool Debugger: Test tools with detailed execution logs
• Performance Analyzer: Analyze tool performance and bottlenecks
• Error Analysis: Intelligent error diagnosis and fix suggestions
• Message Inspector: Inspect request/response payloads

8. Configuration Management

• System Settings: Configure system-wide settings
• Configuration Editor: Edit configurations with validation
• Backup & Restore: Create and restore configuration backups
• Configuration History: Track configuration changes over time
• Validation: Real-time configuration validation

Authentication Setup

The frontend uses JWT-based authentication. To configure authentication:

1. Default Credentials (Development):

   • Username: admin
   • Password: admin

2. Production Setup:

   • Configure credentials, JWT secret, and server port in system.json (see backend/config/system.json.example and the schema at packages/share/src/config/schemas/system.schema.ts).
   • Set a strong password in root users.admin.password. The current backend hashes the configured password in memory; do not put a precomputed bcrypt hash in this field. Keep the config directory restricted to the deployment user.
   • JWT secret/expiry come from the auth.jwt block in system.json, not environment variables.

3. Environment Variables:

   # Backend (.env) — only env vars the code actually reads; see .env.production.example
   NODE_ENV=production
   CONFIG_PATH=/path/to/config      # directory containing system.json, mcp_server.json, group.json
   VALIDATION_KEY_SECRET='<your-existing-secret-at-least-32-characters>'  # required when group validation is enabled
   

Accessing the Web Interface

1. Start the Backend:

   pnpm dev:api
   # Backend runs on http://localhost:8181
   

2. Start the Frontend (Development):

   pnpm dev:fe
   # Frontend runs on http://localhost:8180
   

3. Login:

   • Navigate to http://localhost:8180
   • Enter credentials (default: admin/admin)
   • You'll be redirected to the dashboard

4. Production Deployment:

   # Build frontend
   pnpm build:fe
   
   # Frontend static files will be in frontend/dist
   # Serve the output with nginx (included in the Web image)
   

   The canonical production topology is a two-container stack. Use docker-compose.release.yml for published GHCR images, or docker-compose.yml to build from source:

   • mcp-knot-web (nginx, host port 8180) — serves the SPA and reverse-proxies /api/, /mcp, /:group/mcp to the backend. SPA fallback (try_files ... /index.html) is configured in frontend/nginx.conf, so refreshing any frontend route works.
   • mcp-knot-api (Node, internal 8181) — the API + MCP endpoint, not a SPA host.

   Always access the app via the nginx port (8180). Hitting the backend port (8181) directly with a frontend path returns 404 Not Found because the backend only serves /api/* and /:group/mcp — this is expected, not a bug.

   # v0.1.1 is published; prepare config and the localhost override per the guide
   export MCP_KNOT_VERSION=v0.1.1
   docker compose -f docker-compose.release.yml -f docker-compose.localhost.yml pull
   docker compose -f docker-compose.release.yml -f docker-compose.localhost.yml up -d --no-build --wait
   curl -f http://localhost:8180/api/ping
   

   Prepare the writable config directory first; it mounts at /app/config and defaults to ./config. Published images are ghcr.io/yourtion/mcp-knot-api and ghcr.io/yourtion/mcp-knot-web. The version variable is required; there is no implicit latest. Both v0.1.1 images are currently Public and anonymous pulls have passed. Actual GHCR amd64 images passed Compose startup, API/Web checks and configuration persistence after restart. arm64 was built and its manifest verified; application runtime on ARM was not tested. See the deployment guide for full initialization JSON, UID 1000 permissions, the localhost override and upgrades. Replace default admin/admin and the JWT secret before public access, then restart the API. API liveness is /api/ping; detailed service status is /api/health.

Configuration

MCP Server Configuration

Create a mcp_server.json file in the backend/config/ directory:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "env": {}
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

Group Configuration

Configure groups in backend/config/group.json:

{
  "groups": {
    "development": {
      "name": "Development Tools",
      "description": "Tools for software development",
      "servers": ["filesystem", "git"],
      "allowedTools": ["read_file", "write_file", "git_status"],
      "validationKey": "dev-key-123"
    },
    "research": {
      "name": "Research Tools",
      "description": "Tools for research and information gathering",
      "servers": ["brave-search", "wikipedia"],
      "allowedTools": ["search", "lookup"],
      "validationKey": "research-key-456"
    }
  }
}

Usage Examples

Group-based MCP Access

Access tools through group-specific endpoints:

# List tools for development group（MCP 2026-07-28 JSON-RPC）
curl -X POST http://localhost:8181/development/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# Call a tool in the research group
curl -X POST http://localhost:8181/research/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: tools/call" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "MCP protocol documentation"
      }
    }
  }'

Connecting with the official MCP SDK (Node)

The /:group/mcp endpoint serves the modern 2026-07-28 protocol by default, and — since the protocol compatibility layer (P7) — also accepts legacy 2025-era clients. Inbound compatibility defaults to 全开 (modern + legacy): a modern client negotiates via server/discover, while a legacy client's bare initialize handshake is still served. This is configurable (see Protocol Compatibility).

For a modern client, the official @modelcontextprotocol/client should use versionNegotiation: { mode: 'auto' } so the SDK probes and adopts the server's 2026-07-28 version.

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const transport = new StreamableHTTPClientTransport(new URL('http://localhost:8181/default/mcp'));
const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  {
    capabilities: { tools: {} },
    // Recommended: lets the SDK probe and adopt the server's 2026-07-28 version.
    versionNegotiation: { mode: 'auto' },
  },
);

await client.connect(transport); // initialize
const { tools } = await client.listTools(); // tools/list
await client.callTool({ name: 'fetch_fetch', arguments: { url: 'https://example.com' } });

Tools are namespaced as <serverId>_<toolName> (e.g. fetch_fetch, context7_query-docs) to avoid collisions across servers. Two built-in meta-tools (group_status, list_group_tools) are also exposed on every group endpoint.

Protocol Compatibility

Hub ships a protocol compatibility layer (@mcp-core/mcp-knot-protocol) that bridges the modern 2026-07-28 era and legacy 2025-era MCP on both directions:

• Inbound (client → Hub): defaults to modern + legacy simultaneously — a modern client negotiates via server/discover, a legacy client's bare initialize is still served. Set compatibility.inbound.enabled: false (or CLI --no-legacy-inbound) to reject legacy clients and accept only modern.
• Outbound (Hub → upstream server): era is auto-probed per server; Hub transparently bridges modern requests to legacy upstreams. Set compatibility.outbound.modernOnly: true (or CLI --modern-only-upstream) to connect only to modern upstreams in the backend. The CLI flag is reserved: its core service currently simulates upstream connections and does not enforce it.
• MRTR & errors: cross-era InputRequiredResult (MRTR) state and protocol errors are normalized into a unified shape regardless of upstream era. A legacy upstream that cannot honor input_required degrades to a clear -32601 error rather than failing silently.

Defaults are intentionally permissive so existing clients keep working. The compatibility block in system.json is optional and partially overridable; omit it entirely for the default all-open behavior.

Testing coverage: cross-era bridging is covered by project-owned e2e (protocol-compliance.test.ts: outbound modern→legacy, inbound legacy→modern) plus unit tests for the adapter/codec/normalizer layers. The official @modelcontextprotocol/conformance TCK is wired as a regression gate (pnpm test:conformance) but, as of TCK v0.1.16, only covers the legacy (2025-11-25) era in server mode — modern-era (2026-07-28) conformance is pending upstream TCK support.

CLI MCP Server Integration

Configure the CLI server in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "mcp-knot": {
      "command": "/path/to/mcp-knot/packages/cli/bin/mcp-knot.js",
      "args": ["--config", "/path/to/mcp_server.json"]
    }
  }
}

Development

Available Scripts

# Development
pnpm dev:api          # Start API server in development mode
pnpm dev:fe           # Start frontend in development mode

# Building
pnpm build            # Build all packages
pnpm check            # Run linting and formatting

# Testing
pnpm test             # Run all tests
pnpm test:coverage    # Run tests with coverage
pnpm test:e2e         # Run end-to-end tests

# Utilities
pnpm inspector        # Launch MCP inspector for debugging

Package Development

Each package can be developed independently:

# Core package
cd packages/core
pnpm dev              # Watch mode compilation
pnpm test:watch       # Watch mode testing

# CLI package
cd packages/cli
pnpm dev              # Watch mode compilation
pnpm test:e2e         # End-to-end testing

# API package
cd backend
pnpm dev              # Development server
pnpm test:mcp         # MCP protocol tests

Documentation

User Guides

• Web UI Guide - Complete web interface usage guide
• CLI Usage Guide - Detailed CLI usage and configuration
• Troubleshooting - Frequently asked questions and troubleshooting

Technical Documentation

• API Reference - Complete API documentation
• Group Routing Guide - Group-based routing documentation

Development & Deployment

• Development Guide - Development environment setup and contribution guide
• Release Process - Unified versions and tag-based publishing
• Deployment Guide - Production deployment instructions
• Troubleshooting - Common issues and solutions

Release Process

The four public packages (share, protocol, core, cli) share one stable version. After changes are merged and main CI passes, run from a clean, up-to-date main:

pnpm run release:prepare patch  # minor, major, or an explicit X.Y.Z also work
# Review the version-only commit and local vX.Y.Z tag
pnpm run release:push

Preparation validates the release, commits only the four version manifests, then creates a local tag. Push atomically sends only main and that tag. The tag-triggered publish.yml validates, builds and checks tarballs, publishes in dependency order with npm OIDC, then completes one GitHub Release. Exact versions already published are skipped on retry. Optional GHCR API/Web publishing is enabled by the repository variable DOCKER_PUBLISH=true, uses the Actions GITHUB_TOKEN with job-scoped packages: write, and publishes latest plus the full release tag for amd64/arm64. New GHCR packages default to private; the maintainer controls their visibility. The current API/Web packages are Public and v0.1.1 anonymous pulls are verified. See GHCR setup and verified results.

Use pnpm run release:validate for full local checks or pnpm run release:dry-run for build/package checks without publishing. Setup, first-publish authentication and retry instructions are in RELEASING.md.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run pnpm check to ensure code quality
5. Submit a pull request

License

ISC License - see LICENSE file for details.