Super MCP Router

A local MCP router that aggregates multiple MCPs into a single interface for Claude. No installation required - just use npx!

Overview

Super MCP Router allows you to configure multiple MCP servers (both local stdio and hosted HTTP) and access them through a single unified interface with these meta-tools:

• list_tool_packages - List available MCP packages and discover their capabilities
• list_tools - Browse tools in a package (use detail:"lite" for names + descriptions, detail:"full" for complete schemas)
• get_tool_details - Get full schema for specific tools before first use
• use_tool - Execute a tool from any package
• search_tools - BM25 keyword search across all available tools
• get_help - Get detailed guidance on using Super-MCP effectively
• authenticate - Start OAuth authentication for packages that require it
• health_check_all - Check the operational status of all configured packages
• health_check - Check the status of a specific package
• restart_package - Hot-reload a package's credentials without restarting Super-MCP

Documentation

For detailed guides, see the docs/ directory:

Document	Description
Configuration Reference	Complete schema for all config options
Security Policy Guide	Allowlist/blocklist rules, patterns, hot-reload
Security Hardening	Security measures, mitigations, and future work
OAuth & Authentication	API keys, OAuth flows, token storage
Transport Modes	STDIO vs HTTP comparison and selection guide
Error Codes Reference	All error codes with causes and solutions
Timeout Configuration	Per-server and global timeout settings
Multi-Config Best Practices	Organizing configs across files
Architecture Overview	Component design and request flow

Quick Start (No Installation Required!)

Super MCP Router supports two transport modes:

• STDIO (default): For local Claude Desktop integration
• HTTP: For remote access and running multiple instances in parallel

1. Add to Claude Desktop (STDIO Mode)

Add this to your Claude Desktop MCP settings:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "super-mcp": {
      "command": "npx",
      "args": ["-y", "super-mcp-router@latest"]
    }
  }
}

1b. Use HTTP Mode (Remote/Parallel Access)

When to use HTTP mode:

• 🔄 Running multiple instances in parallel (no tool call conflicts)
• 🌐 Remote access from multiple machines
• ☁️ Cloud deployments (AWS, GCP, Azure, etc.)
• 🔧 Load balancing across multiple servers
• 📊 Easier monitoring and debugging with HTTP tools

To run the server in HTTP mode:

# Run on default port 3000
npx super-mcp-router@latest --transport http

# Run on custom port
npx super-mcp-router@latest --transport http --port 8080

# With custom config
npx super-mcp-router@latest --transport http --config /path/to/config.json

Then configure Claude Desktop to connect via HTTP:

{
  "mcpServers": {
    "super-mcp-http": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Running Multiple Instances:

# Terminal 1 - Instance on port 3000
npx super-mcp-router@latest --transport http --port 3000

# Terminal 2 - Instance on port 3001
npx super-mcp-router@latest --transport http --port 3001

# Terminal 3 - Instance on port 3002
npx super-mcp-router@latest --transport http --port 3002

Each instance runs independently with no shared state or conflicts.

2. Restart Claude Desktop

That's it! Super MCP Router will automatically:

• Create ~/.super-mcp/ directory
• Create an empty config file
• Start working immediately (even with no MCPs configured)

3. Add MCP Servers (Optional)

Use the simple CLI to add MCP servers:

# Add common MCP servers
npx super-mcp-router add filesystem
npx super-mcp-router add github
npx super-mcp-router add memory

# See available servers
npx super-mcp-router add --help

Or manually edit ~/.super-mcp/config.json to add custom MCPs.

Transport Modes

See also: Transport Modes Guide for detailed comparison and selection guidance.

STDIO Mode (Default)

• ✅ Best for: Local Claude Desktop integration
• ✅ Zero configuration needed
• ✅ Lowest latency
• ⚠️ Single client only
• ⚠️ Cannot run multiple instances in parallel

HTTP Mode

• ✅ Best for: Multiple parallel instances, remote access, cloud deployments
• ✅ Run unlimited instances simultaneously
• ✅ No tool call conflicts between instances
• ✅ Works with load balancers
• ✅ Easier to monitor and debug
• ⚠️ Requires port configuration
• ⚠️ Slightly higher latency than stdio (minimal)

Configuration

See also: Configuration Reference for complete schema documentation.

Super MCP Router supports the standard MCP mcpServers configuration format, making it easy to drop in existing MCP server configurations.

Create a super-mcp-config.json file:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/directory"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    },
    "notion-api": {
      "type": "sse",
      "url": "https://mcp.notion.com/mcp",
      "oauth": true,
      "name": "Notion Integration",
      "description": "Access and manage Notion workspaces"
    }
  }
}

Configuration Options

Standard MCP fields:

• command: Command to execute (for stdio servers)
• args: Command arguments
• env: Environment variables (supports variable expansion - see below)
• cwd: Working directory for the server process
• type: Transport type:
  • "stdio": Local command execution
  • "sse": HTTP+SSE transport (deprecated as of MCP spec 2025-03-26)
  • "http": Streamable HTTP transport (recommended for HTTP servers)
• url: Server URL (for HTTP servers)
• headers: HTTP headers for authentication

Extended fields (super-mcp specific):

• oauth: Enable OAuth authentication (boolean)
• name: Human-readable name for the package
• description: Description of the package's capabilities
• visibility: "default" or "hidden" (controls display in tool lists)
• timeout: Tool execution timeout in milliseconds (default: 300000 = 5 minutes)

Environment Variable Expansion

Super MCP Router supports environment variable expansion in the env field using ${VAR} or $VAR syntax:

{
  "github": {
    "command": "npx",
    "args": ["@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

This allows you to:

• Keep sensitive tokens out of configuration files
• Share configurations without exposing credentials
• Use different values across environments

Security Note: Only explicitly configured environment variables are passed to MCP servers. This prevents leaking system environment variables to individual servers.

Configuring Tool Timeouts

See also: Timeout Configuration for detailed timeout guide.

Super MCP Router supports configurable timeouts for long-running tool executions. By default, tools timeout after 5 minutes (300,000ms), but you can customize this per-server or globally.

Per-Server Timeout:

{
  "mcpServers": {
    "deep-research": {
      "command": "npx",
      "args": ["-y", "octagon-deep-research-mcp@latest"],
      "timeout": 600000,  // 10 minutes for deep research tasks
      "env": {
        "OCTAGON_API_KEY": "your_api_key"
      }
    }
  }
}

Global Timeout (Environment Variable):

export SUPER_MCP_TOOL_TIMEOUT=600000  # 10 minutes default for all tools

How Timeouts Work:

• Default timeout: 300,000ms (5 minutes)
• Per-server timeout config overrides the default
• SUPER_MCP_TOOL_TIMEOUT environment variable provides a global default
• Timeout automatically resets when the tool sends progress notifications
• Useful for long-running operations like research, data processing, or complex queries

CLI Commands

Super MCP Router includes a simple CLI for managing MCP servers:

Adding MCP Servers

# Add pre-configured MCP servers
npx super-mcp-router add filesystem  # Adds filesystem access
npx super-mcp-router add github      # Adds GitHub integration 
npx super-mcp-router add memory      # Adds persistent memory

# See available servers
npx super-mcp-router add --help

The add command:

• Adds servers to ~/.super-mcp/config.json
• Uses sensible defaults (e.g., ~/Documents for filesystem)
• Reminds you about required environment variables

Default Config Location

If no --config is specified, Super MCP Router uses:

• ~/.super-mcp/config.json (auto-created if missing)

You can still use custom locations:

npx super-mcp-router --config /custom/path/config.json

Using Multiple Configuration Files

See also: Multi-Config Best Practices for organization strategies.

You can split your MCP servers across multiple configuration files for better organization. This is useful for:

• Separating personal and work MCPs
• Grouping MCPs by functionality (e.g., dev tools, AI services, databases)
• Sharing common configurations across projects
• Managing team-wide vs personal tool configurations

Method 1: Multiple --config Arguments

In your Claude configuration, you can specify multiple config files:

{
  "mcpServers": {
    "Super-MCP": {
      "command": "npx",
      "args": [
        "-y",
        "super-mcp-router@latest",
        "--config",
        "/Users/YOU/.super-mcp/personal-mcps.json",
        "--config",
        "/Users/YOU/.super-mcp/work-mcps.json",
        "--config",
        "/Users/YOU/.super-mcp/shared-mcps.json"
      ]
    }
  }
}

Method 2: Environment Variable (Comma-Separated)

Set the environment variable with comma-separated paths:

export SUPER_MCP_CONFIG="/path/to/personal.json,/path/to/work.json,/path/to/shared.json"

Then use Super MCP normally - it will automatically load all specified configs.

Example: Organizing by Function

dev-tools.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/YOU/dev"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN" }
    }
  }
}

ai-services.json:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "YOUR_KEY" }
    }
  }
}

Important Notes

• Duplicate IDs: If the same server ID appears in multiple configs, the last one loaded takes precedence (with a warning logged)
• Error Handling: If any config file fails to load, the entire startup fails (fail-fast behavior)
• Backward Compatible: Single config files work exactly as before - no changes needed to existing setups
• Legacy Format: The old packages array format is still supported and automatically converted

Alternative Installation Methods

While npx is the recommended way to use Super MCP Router (no installation, always up-to-date), you can also:

Install Globally

npm install -g super-mcp-router

Then use in Claude config:

{
  "mcpServers": {
    "Super-MCP": {
      "command": "super-mcp-router",
      "args": [
        "--config",
        "/Users/YOUR_USERNAME/.super-mcp/super-mcp-config.json"
      ]
    }
  }
}

To update: npm update -g super-mcp-router

Clone and Build from Source (For Development)

git clone https://github.com/mindstone/Super-MCP.git
cd Super-MCP
npm install
npm run build

Then use in Claude config:

{
  "mcpServers": {
    "Super-MCP": {
      "command": "node",
      "args": [
        "/absolute/path/to/Super-MCP/dist/cli.js",
        "--config",
        "/Users/YOUR_USERNAME/.super-mcp/super-mcp-config.json"
      ]
    }
  }
}

To update:

cd /path/to/Super-MCP
git pull
npm install
npm run build

Features

• Single Interface: Access all your MCPs through one connection
• Mixed Transports: Combine stdio and HTTP MCPs seamlessly
• HTTP Transport Support: Both HTTP+SSE (legacy) and Streamable HTTP (recommended)
• OAuth Support: Browser-based OAuth flow with persistent token storage
• Tool Discovery: Automatic tool enumeration and caching
• Validation: Schema validation for all tool arguments
• Error Handling: Comprehensive error codes and messages with contextual help
• Improved Authentication: Clear error messages guiding users to authenticate when needed
• Built-in Help System: Interactive guidance with get_help tool
• Security Policy: Block or allow specific tools/packages with regex pattern support
• Hot Reload: Security config changes apply immediately without restart
• Portable: Everything contained within this directory

Project Structure

src/
├── cli.ts              # CLI entry point
├── server.ts           # MCP server with meta-tools
├── registry.ts         # Config loading & package management
├── catalog.ts          # Tool caching & discovery
├── security.ts         # Security policy (allowlist/blocklist)
├── configWatcher.ts    # Config hot-reload for security
├── summarize.ts        # Tool summaries & arg skeletons
├── validator.ts        # Argument validation
├── logging.ts          # Structured logging
├── types.ts            # TypeScript definitions
├── handlers/           # Request handlers
│   ├── useTool.ts      # Tool execution with security checks
│   ├── listTools.ts    # Tool discovery with blocked status
│   └── ...             # Other handlers
├── auth/
│   ├── callbackServer.ts # OAuth callback server
│   └── providers/      # OAuth providers
└── clients/
    ├── stdioClient.ts  # Stdio MCP client
    └── httpClient.ts   # HTTP MCP client

Security

Credential Safety

See also: OAuth & Authentication for detailed auth documentation.

• Never commit your super-mcp-config.json - it contains API keys and credentials
• Tokens stored securely in OS keychain (with file fallback)
• All sensitive data redacted from logs
• File tokens created with 0600 permissions
• Device code flow (no local HTTP server required)

⚠️ Important: The .gitignore file excludes your config file, but double-check before committing!

Security Policy (Tool Blocking)

See also: Security Policy Guide for complete security documentation.

Super MCP Router includes a security policy system that lets you control which tools and packages can be used. This is useful for:

• Blocking dangerous operations (e.g., file deletion)
• Restricting access to specific packages
• Creating allowlists for sensitive environments

Configuration

Add a security section to your config file:

{
  "security": {
    "blockedTools": [
      "filesystem__delete_file",
      "filesystem__write_file",
      "/.*delete.*/i",
      "/.*remove.*/i"
    ],
    "blockedPackages": ["dangerous-package"],
    "allowedPackages": ["filesystem", "github"],
    "allowedTools": ["filesystem__read_file", "filesystem__list_directory"],
    "logBlockedAttempts": true
  },
  "mcpServers": { ... }
}

Layered Security Model

Both allowlist and blocklist rules apply together (layered):

1. Allowlist gate: If allowedPackages or allowedTools is configured, the item must be on the list
2. Blocklist gate: If blockedPackages or blockedTools is configured, the item must NOT be on the list

Configuration	Behavior
Only blocklist	Everything allowed except blocked items
Only allowlist	Only allowed items permitted
Both configured	Must be on allowlist AND not on blocklist
Neither configured	Everything allowed

Pattern Matching

Tools can be specified as:

• Exact names: "filesystem__delete_file"
• Regex patterns: "/.*delete.*/i" (delimited by /, optional flags)

Hot Reload

Security configuration is hot-reloaded when config files change - no server restart required. Edit your config file and the new rules apply immediately to subsequent tool calls.

Built-in Help System

See also: Error Codes Reference for all error codes with solutions.

Super MCP includes comprehensive built-in help accessible through the get_help tool:

Help Topics

• getting_started: Basic workflow and examples
• workflow: Common usage patterns
• authentication: OAuth and API key setup
• tool_discovery: Finding and understanding available tools
• error_handling: Troubleshooting error codes
• common_patterns: Typical usage scenarios
• package_types: Understanding different MCP types

Usage Examples

// Get started with Super MCP
get_help(topic: "getting_started")

// Get help for a specific package
get_help(package_id: "github")

// Get help for an error code
get_help(error_code: -33003)

Enhanced Error Messages

All errors now include contextual guidance pointing to relevant help resources and suggesting next steps.

Development

# Install dependencies
npm install

# Run in development mode
npm run dev -- --config ./super-mcp-config.json

# Build for production
npm run build