modular

Modular MCP is a proxy that manages multiple upstream MCP servers and exposes a single MCP endpoint to your LLM. It minimizes context load by embedding group descriptions in tool metadata and loading detailed tool schemas on demand. When you start Modular MCP, it registers two on-demand tool groups: context7 (for library/documentation-style queries) and playwright (for browser automation). To discover what tools are available in a group, you use the get-modular-tools tool with the desired group. Once you know the available tools, you call modular tools using call-modular-tool, specifying the group and the tool name. This approach lets you scale to many tool servers without overwhelming the LLM with all tool schemas at once. For example, you can first query get-modular-tools(group="playwright") to retrieve browser-related tools, then call a specific tool like browser_navigate with the appropriate arguments to drive a browser session through the upstream Playwright MCP server.

Prerequisites:

• Node.js and npm installed on your system

Step 1: Install Modular MCP via npx (no global install required)

• Ensure you have an existing MCP client configuration (or create one later).

Step 2: Create a Modular MCP configuration file (e.g., modular-mcp.json) with upstream servers

{
  "$schema": "https://raw.githubusercontent.com/d-kimuson/modular-mcp/refs/heads/main/config-schema.json",
  "mcpServers": {
    "context7": {
      "description": "Use when you need to search library documentation.",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    },
    "playwright": {
      "description": "Use when you need to control or automate web browsers.",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    }
  }
}

Step 3: Register Modular MCP in your MCP client (example):

{
  "mcpServers": {
    "modular-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kimuson/modular-mcp", "modular-mcp.json"],
      "env": {}
    }
  }
}

Step 4: Run Modular MCP

• Start the modular-mcp server using your preferred MCP client configuration. The server will expose two tool groups (context7 and playwright) for on-demand loading.

Tips:

• Modular MCP supports environment variable interpolation in configuration files using ${VAR}. Ensure required environment variables are defined before starting. If a referenced variable is undefined, a warning is logged and the placeholder remains.
• The provided configuration uses the standard MCP format with an added description field for each upstream server. You can extend env vars per upstream as needed.
• When integrating with an MCP client, register Modular MCP as a stdio server and point it to modular-mcp.json to enable group-based tool loading.
• If you encounter connectivity or schema loading issues, verify that the upstream MCP servers (context7 and playwright) are reachable and that the respective npx commands succeed independently.
• Default behavior assumes stdio MCP servers; you can add http or other server types if your topology requires it.