🌐 omni-mcp

One proxy. All your MCP servers. Every IDE.

Stop copying MCP configs across Cursor, VS Code, Claude Desktop, and Windsurf. omni-mcp gives you a single gateway that consolidates all your MCP servers, applies per-agent access control, and isolates crashes — so one broken server never takes down your entire AI workflow.

⚡ 30-Second Quick Start

# 1. Scaffold your config (auto-imports from your existing IDE MCP configs)
npx omni-mcp-manager init --import

# 2. Start the gateway
npx omni-mcp-manager start

# 3. Open the local UI (no login)
#    http://127.0.0.1:6317/

# 4. Point your IDE to the gateway (get copy-paste snippets)
npx omni-mcp-manager ide-snippets

That's it. All your AI clients now share a single, managed MCP endpoint at http://127.0.0.1:6317/mcp. Manage servers, profiles, and tokens in the local UI at http://127.0.0.1:6317/ (no login; management is restricted to localhost).

🤯 Why Developers Love This

| Before omni-mcp | After omni-mcp | |-----------------|----------------| | 5 servers × 3 IDEs = 15 config entries to maintain | 1 config file + 3 one-line IDE entries | | One server crashes → IDE freezes | Crash isolated → other tools keep working | | All agents see all tools (no control) | Per-agent profiles: Cursor gets admin, Claude gets safe mode | | Adding a server = edit every IDE config | omni-mcp add github --npx "@modelcontextprotocol/server-github" → done everywhere | | Secrets scattered across IDE configs | Secrets live in one place, injected at the proxy layer |

✨ Key Features

• Unified Proxy Routing: Consolidate 10+ individual MCP servers into a single endpoint. Stop managing complex, scattered configuration files across multiple IDEs.
• Profile-Based Access Control: Instantly create user, team, or project-specific profiles. Toggle risky tools on or off with simple, fine-grained controls before exposing them to an LLM.
• Auto-Discovery & Import: Detect existing MCP configs from Cursor, VS Code, and Claude Desktop. Import your server fleet in one command.
• Transport Bridging: Seamlessly map local transports (stdio) and remote streamable HTTP endpoints into a standardized, secure connection pane.
• Crash & Concurrency Protection: Isolate individual servers behind dedicated internal proxies. Prevent cascading failures and stop misbehaving tools from crashing your entire agent workspace.
• Secured Workflows: Inject JWT authentication tokens at the proxy layer while keeping values in a write-only local store. OAuth is a future capability.
• Hot Reload: Change tokens, profiles, secrets, or servers without restarting the gateway. Affected upstream adapters reconnect while IDE sessions stay connected.

🏗️ Architecture Overview

 [Cursor / VS Code / Claude Desktop / Windsurf / Any MCP Client]
                │
                ▼ (Single HTTP Connection)
   ┌────────────────────────────────────────┐
   │            omni-mcp (port 6317)        │
   │                                        │
   │  Token: "cursor" → Profile: admin      │
   │  Token: "claude" → Profile: safe       │
   │  Token: "default" → Profile: safe      │
   ├────────────────────────────────────────┤
   │  Profile "admin": allow ["*"]          │
   │  Profile "safe":  allow [fs, github]   │
   └──────┬──────────────┬─────────────┬────┘
          │              │             │
    (Local stdio)  (Local stdio)  (Remote HTTP)
          ▼              ▼             ▼
   ┌───────────┐  ┌───────────┐  ┌───────────┐
   │filesystem │  │  github   │  │ prod-api  │
   └───────────┘  └───────────┘  └───────────┘

🚀 Getting Started

Install

npm install -g omni-mcp-manager

This installs the omni-mcp command (omni-mcp-manager works as an alias).

Or use without installing:

npx omni-mcp-manager init

Import Existing Config

Already using MCP servers in your IDE? Import them all:

npx omni-mcp-manager init --import

This scans Cursor, VS Code, and Claude Desktop configs, imports all servers, and generates sensible token/profile defaults.

Manual Config

Create ~/.config/omni-mcp/config.json (the CLI default), or select another file with --config <path>:

{
  "port": 6317,
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" }
    }
  },
  "profiles": {
    "default": { "allow": ["filesystem"] },
    "admin":   { "allow": ["*"] }
  },
  "tokens": {
    "default": { "profile": "default" },
    "cursor":  { "profile": "admin" }
  }
}

Exact $NAME or ${NAME} strings are filled from the process environment first, then from the active secret store — ~/.config/omni-mcp/secrets.json by default, or the macOS Keychain backend. Values are write-only and never returned by the API. See Managed secrets.

Add Servers Without Editing JSON

omni-mcp add puppeteer --npx "@modelcontextprotocol/server-puppeteer" --profile admin
omni-mcp add memory --npx "@modelcontextprotocol/server-memory" --profile default --profile admin

Start the Gateway

omni-mcp start

Connect Your IDE

Run omni-mcp ide-snippets for exact copy-paste configs, or add this to your IDE's MCP config:

{
  "url": "http://127.0.0.1:6317/mcp",
  "headers": { "Authorization": "******" }
}

🎯 Common Use Cases

Solo Developer — Simplify MCP Management

One config to rule them all. Stop editing 3+ IDE configs every time you add a server.

Safety-Conscious Developer — Restrict Dangerous Tools

Give Claude Desktop read-only tools while Cursor gets full access:

{
  "tokens": {
    "cursor": { "profile": "full" },
    "claude": { "profile": "readonly" }
  }
}

Team Lead — Shared MCP Standards

Commit omni-mcp.config.json to your repo. Everyone on the team gets the same MCP setup with one command.

CI/CD — Automated Agents

Give your CI bot its own token with access only to deployment tools:

{
  "tokens": {
    "ci-bot": { "profile": "deploy-only" }
  }
}

📊 CLI Commands

| Command | Description | |---------|-------------| | omni-mcp init | Interactive setup with auto-import from existing IDE configs | | omni-mcp start | Start the proxy gateway | | omni-mcp stop | Graceful shutdown | | omni-mcp status | Show server health, active connections, profiles | | omni-mcp server … | List/show/add/update/remove/clone and toggle servers or CLI opt-in | | omni-mcp profile … | List/show/create/update/delete profiles | | omni-mcp token … | List/show/create/update/delete and enable/disable tokens | | omni-mcp config … | Show/apply/validate/reload config | | omni-mcp logs … | Query, summarize, or explicitly clear traffic logs | | omni-mcp tools … | Direct Playground discovery and calls for enabled servers | | omni-mcp add/remove/validate/reload | Backward-compatible aliases | | omni-mcp ide-snippets | Print IDE-specific setup snippets | | omni-mcp cli <server> <tool> | Discover and invoke tools from CLI-enabled MCP servers | | omni-mcp cli install-skill | Teach Cursor and Claude to use the managed CLI | | omni-mcp secrets … | Write-only secret store (list, set, delete, sync, import-keychain, migrate) |

Install the agent skill

Install the bundled skill user-wide for both Cursor and Claude:

omni-mcp cli install-skill

Use --target cursor|claude|all, --scope user|project, or --force to customize installation. Start a new agent session after installation so the skill is discovered.

🎯 Target Scope & Roadmap

• Phase 1 (Current Focus): Single client-side proxy manager with a local web UI (no login) plus CLI, optimizing developer workflows in Cursor, VS Code, Claude Desktop, and local environments.
• Phase 2 (Team Expansion): Standalone team cloud service wrapping multiple shared MCPs with integrated load balancing, web UI, and OAuth.
• Phase 3 (Enterprise Platform): Full multi-tenant SaaS platform featuring auto-scaling regional proxies, enterprise compliance toggles, and AI-driven automated tool discovery.

📖 Documentation

Full specs are available in docs/specs/:

• Project Overview
• Configuration
• Token & Auth
• Proxy Gateway
• Transport Bridging
• Resilience
• CLI
• IDE Integration
• Web UI
• Traffic logs
• Managed MCP CLI
• Managed secrets
• CLI parity and release contract

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, Conventional Commits, and how versions are published. This project follows the Contributor Covenant.