mcp-manage by zarrx-dev - MCP Server

MCP Manager

⚠️ BETA RELEASE - This is a beta release under active development. APIs and features may change. Please report any issues you encounter.

Unified MCP (Model Context Protocol) gateway and configuration manager for multiple AI clients.

Overview

MCP Manager is a powerful tool that acts as a single unified MCP server, internally routing requests to multiple backend MCP servers. Instead of configuring each MCP server individually in your AI client (Claude, Cursor, VS Code, etc.), you configure just one: mcp-manager.

Key Features

Single Configuration Point - Configure one MCP server in your AI client
Multiple Backend Servers - Connect to unlimited MCP servers (GitHub, Jenkins, Obsidian, etc.)
Dynamic Tool Management - Enable/disable servers without restarting your AI client
Tool Namespacing - Automatic prefixing to avoid naming conflicts (e.g., github__create_issue)
Health Monitoring - Automatic health checks and reconnection
Centralized Auth - Manage all credentials in one place
Cross-Client Support - Works with Claude Code, Cursor, VS Code, and more

Installation

Global Installation (Recommended)

npm install -g mcp-manage

After installation, you can use the mcp command directly:

mcp --help
mcp init
mcp add myserver

Using npx (No Installation Required)

npx mcp-manage@latest <command>

# Examples
npx mcp-manage@latest init
npx mcp-manage@latest add myserver

Alias for Convenience

If using npx frequently, create an alias:

# Add to your ~/.bashrc or ~/.zshrc
alias mcp="npx mcp-manage@latest"

# Then use
mcp init
mcp list

Quick Start

1. Initialize Configuration

mcp init

This creates:

~/.mcp/config.json - Main configuration file
~/.mcp/logs/ - Log directory
~/.mcp/data/ - Data directory

2. Add MCP Servers

Add a stdio server (e.g., shadcn):

mcp add shadcn \
  --type stdio \
  --command npx \
  --args "shadcn@latest,mcp"

Add an HTTP server (e.g., GitHub):

mcp add github \
  --type http \
  --url https://api.githubcopilot.com/mcp \
  --auth bearer:YOUR_TOKEN

Interactive mode (recommended):

mcp add myserver
# Follow the prompts
# For custom headers, select "custom" as authentication type
# Then enter each header name and value (supports ${ENV_VAR} syntax)

3. Configure Your AI Client

Add only one entry to your AI client's MCP configuration:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "mcp-manage": {
      "command": "mcp",
      "args": ["serve"]
    }
  }
}

Or if using npx:

{
  "mcpServers": {
    "mcp-manage": {
      "command": "npx",
      "args": ["mcp-manage@latest", "serve"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-manage": {
      "command": "mcp",
      "args": ["serve"]
    }
  }
}

VS Code (settings.json):

{
  "github.copilot.chat.mcp.servers": {
    "mcp-manage": {
      "command": "mcp",
      "args": ["serve"]
    }
  }
}

4. Restart Your AI Client

That's it! All tools from your enabled servers will now be available.

CLI Commands

All commands use the mcp command (or npx mcp-manage@latest if not globally installed):

Server Management

# List all configured servers
mcp list
mcp ls -v  # Verbose mode

# Add a new server (interactive mode)
mcp add <name>

# Add a stdio server with options
mcp add shadcn \
  --type stdio \
  --command npx \
  --args "shadcn@latest,mcp"

# Add an HTTP server with authentication
mcp add github \
  --type http \
  --url https://api.example.com/mcp \
  --auth bearer:YOUR_TOKEN

# Add an HTTP server with custom headers
mcp add context7 \
  --type http \
  --url https://mcp.context7.com/mcp \
  -H "CONTEXT7_API_KEY:${SZ_CONTEXT7_API_KEY}"

# Add server with multiple custom headers
mcp add myserver \
  --type http \
  --url https://api.example.com/mcp \
  -H "X-API-Key:${API_KEY}" \
  -H "X-Custom-Header:${CUSTOM_VALUE}"

# Add command options:
#   -t, --type <type>        Transport type (stdio|http|sse)
#   -c, --command <command>  Command for stdio transport
#   -a, --args <args>        Arguments for stdio transport (comma-separated)
#   -u, --url <url>          URL for HTTP and SSE transport
#   --auth <auth>            Authentication (bearer:TOKEN or basic:CREDS)
#   -H, --header <header>    Custom header (KEY:VALUE, can be used multiple times)
#   --enabled                Enable the server immediately (default: true)

# Remove a server
mcp remove <name>

# Enable/disable servers
mcp enable <name>
mcp disable <name>

# Check server status
mcp status

Tool Discovery

# List all available tools
mcp tools

# Output example:
# Tool Statistics:
#   Total Servers: 3
#   Connected: 3
#   Total Tools: 87
#   Total Resources: 12
#   Total Prompts: 5
#
# By Server:
#   github:
#     Tools: 45
#     Resources: 8
#     Prompts: 2
#   jenkins:
#     Tools: 28
#     Resources: 3
#     Prompts: 1
#   obsidian:
#     Tools: 14
#     Resources: 1
#     Prompts: 2

Gateway Server

# Start the gateway (usually called by AI client)
mcp serve

# Use custom config file
mcp serve --config /path/to/config.json

Transport Types

MCP Manager supports two transport types for connecting to MCP servers:

STDIO Transport

Used for local MCP servers that communicate via standard input/output:

# Add with CLI
mcp add myserver \
  --type stdio \
  --command node \
  --args "/path/to/server.js"

# Examples:
# Node.js MCP server
mcp add nodejs-mcp --type stdio --command node --args "server.js"

# Python MCP server
mcp add python-mcp --type stdio --command python --args "server.py"

# NPX package
mcp add shadcn --type stdio --command npx --args "shadcn@latest,mcp"

Configuration format:

{
  "transport": {
    "type": "stdio",
    "command": "npx",
    "args": ["shadcn@latest", "mcp"]
  },
  "env": {
    "NODE_ENV": "production"
  }
}

HTTP Transport

Used for remote MCP servers that expose an HTTP endpoint:

# Add with CLI
mcp add remote-mcp \
  --type http \
  --url https://api.example.com/mcp

# With bearer token authentication
mcp add github \
  --type http \
  --url https://api.example.com/mcp \
  --auth bearer:ghp_xxxxxxxxxxxxx

# With basic authentication
mcp add jenkins \
  --type http \
  --url https://ci.example.com/mcp \
  --auth basic:username:password

Configuration format:

{
  "transport": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
    }
  }
}

Authentication Options

The --auth flag supports:

Bearer tokens: --auth bearer:TOKEN
- Adds header: Authorization: Bearer TOKEN
Basic auth: --auth basic:CREDENTIALS
- Adds header: Authorization: Basic base64(CREDENTIALS)

Configuration

Configuration File Location

~/.mcp/config.json

Configuration Schema

{
  "version": "1.0.0",
  "servers": {
    "github": {
      "enabled": true,
      "transport": {
        "type": "http",
        "url": "https://api.githubcopilot.com/mcp",
        "headers": {
          "Authorization": "Bearer ghp_xxx"
        }
      },
      "healthCheck": {
        "enabled": true,
        "interval": 30000,
        "timeout": 5000
      },
      "retryPolicy": {
        "maxRetries": 3,
        "backoffMs": 1000
      },
      "toolNamespace": "github",
      "metadata": {
        "description": "GitHub MCP Server",
        "tags": ["git", "source-control"]
      }
    },
    "jenkins": {
      "enabled": true,
      "transport": {
        "type": "http",
        "url": "https://ci.example.com/mcp-server/mcp",
        "headers": {
          "Authorization": "Basic base64creds"
        }
      }
    },
    "shadcn": {
      "enabled": true,
      "transport": {
        "type": "stdio",
        "command": "npx",
        "args": ["shadcn@latest", "mcp"]
      },
      "env": {
        "NODE_ENV": "production"
      }
    }
  },
  "gateway": {
    "defaultNamespace": true,
    "toolPrefix": "",
    "healthCheck": {
      "interval": 30000
    }
  }
}

Tool Namespacing

Tools are automatically namespaced to avoid conflicts:

Original tool: create_issue
Namespaced:    github__create_issue

Original tool: trigger_build
Namespaced:    jenkins__trigger_build

When the AI calls github__create_issue, MCP Manager:

Parses the namespace: github
Extracts the tool name: create_issue
Routes the call to the GitHub MCP server
Returns the response to the AI

Environment Variables

Use environment variables in your configuration with ${VAR_NAME} syntax. This works in any string field including URLs, headers, command arguments, and environment variables.

Standard Authorization:

{
  "servers": {
    "github": {
      "transport": {
        "type": "http",
        "url": "${GITHUB_MCP_URL}",
        "headers": {
          "Authorization": "Bearer ${GITHUB_TOKEN}"
        }
      }
    }
  }
}

Custom Headers:

{
  "servers": {
    "context7": {
      "transport": {
        "type": "http",
        "url": "https://mcp.context7.com/mcp",
        "headers": {
          "CONTEXT7_API_KEY": "${SZ_CONTEXT7_API_KEY}"
        }
      }
    }
  }
}

In Command Arguments:

{
  "servers": {
    "myserver": {
      "transport": {
        "type": "stdio",
        "command": "node",
        "args": ["server.js", "--token", "${API_TOKEN}"]
      }
    }
  }
}

Architecture

┌─────────────────┐
│   AI Client     │
│ (Claude/Cursor) │
└────────┬────────┘
         │ Single MCP Connection
         │
    ┌────▼────────┐
    │ MCP Manager │
    │   Gateway   │
    └────┬────────┘
         │ Routes to multiple backends
         │
    ┌────┴─────────────────────────┐
    │                              │
┌───▼────┐  ┌─────────┐  ┌────────▼───┐
│ GitHub │  │ Jenkins │  │  Obsidian  │
│  MCP   │  │   MCP   │  │    MCP     │
└────────┘  └─────────┘  └────────────┘

Development

Want to contribute? See for guidelines.

# Install dependencies
bun install

# Run in development
bun run dev

# Build
bun run build

# Lint
bun run lint

# Test
bun test

Contributing

Contributions are welcome! Please read for details on our code of conduct and the process for submitting pull requests.

Changelog

See for a list of changes and version history.

License

MIT - See for details.

Support

Issues: GitHub Issues
Documentation:
Repository: https://github.com/zarrx-dev/mcp-manage