https://github.com/d-kimuson/modular-mcp
A Model Context Protocol (MCP) proxy server that enables efficient management of large tool collections across multiple MCP servers by grouping them and loading tool schemas on-demand.
https://github.com/d-kimuson/modular-mcp
claude claude-code codex llm mcp mcp-server
Last synced: 14 days ago
JSON representation
A Model Context Protocol (MCP) proxy server that enables efficient management of large tool collections across multiple MCP servers by grouping them and loading tool schemas on-demand.
- Host: GitHub
- URL: https://github.com/d-kimuson/modular-mcp
- Owner: d-kimuson
- License: mit
- Created: 2025-10-22T14:25:46.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-11-15T16:28:59.000Z (2 months ago)
- Last Synced: 2025-11-15T17:32:02.684Z (2 months ago)
- Topics: claude, claude-code, codex, llm, mcp, mcp-server
- Language: TypeScript
- Homepage:
- Size: 131 KB
- Stars: 23
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Modular MCP
[](https://github.com/d-kimuson/modular-mcp/blob/main/LICENSE)
[](https://github.com/d-kimuson/modular-mcp/actions/workflows/ci.yml)
[](https://github.com/d-kimuson/modular-mcp/releases)
[](https://deepwiki.com/d-kimuson/modular-mcp)
A Model Context Protocol (MCP) proxy server that enables efficient management of large tool collections across multiple MCP servers by grouping them and loading tool schemas on-demand.
## Concept
Traditional MCP setups can overwhelm LLM context when dealing with numerous tools from multiple servers. Modular MCP solves this by:
- **Context Efficiency**: Group information is embedded in tool descriptions, so LLMs can discover available groups without making any tool calls
- **On-Demand Loading**: Retrieves detailed tool schemas only when needed for specific groups
- **Separation of Concerns**: Maintains clear phases between tool discovery and execution
- **Proxy Architecture**: Acts as a single MCP endpoint that manages multiple upstream MCP servers
## How it works?
### 1. Configuration
Create a configuration file (e.g., `modular-mcp.json`) for the upstream MCP servers you want to manage. This uses the standard MCP server configuration format, with one addition: a `description` field for each server.
Here's an example using Context7 and Playwright MCP servers:
```diff
{
+ "$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.",
- "type": "stdio",
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"],
"env": {}
},
"playwright": {
+ "description": "Use when you need to control or automate web browsers.",
- "type": "stdio",
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"],
"env": {}
}
}
}
```
The `description` field is the only extension to the standard MCP configuration. It helps the LLM understand each tool group's purpose without loading detailed tool schemas.
**Note**: The `type` field defaults to `"stdio"` if not specified. For `stdio` type servers, you can omit the `type` field for cleaner configuration.
#### Environment Variable Interpolation
Modular MCP supports environment variable interpolation in configuration files, allowing you to avoid committing sensitive information like API keys and tokens to version control.
**Supported syntax**:
- `${VAR}` - Braced variable reference
**Note**: Only the `${VAR}` syntax is supported. The `$VAR` syntax (without braces) is intentionally not supported to avoid conflicts with values that legitimately contain dollar signs (e.g., tokens like `token$abc123`).
**Where interpolation is supported**:
- `stdio` servers: `args` array elements and `env` object values
- `http`/`sse` servers: `url` string and `headers` object values
**Example**:
```json
{
"mcpServers": {
"my-server": {
"description": "Example server with environment variables",
"command": "node",
"args": ["${HOME}/.local/bin/server.js", "--config=${XDG_CONFIG_HOME}/app/config.json"],
"env": {
"API_KEY": "${MY_API_KEY}",
"LOG_DIR": "${HOME}/logs"
}
},
"api-server": {
"description": "HTTP server with authentication",
"type": "http",
"url": "https://api.example.com",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
}
}
```
**Important notes**:
- Environment variables must be set before starting Modular MCP
- If a referenced environment variable is not defined, a warning will be logged and the original placeholder (e.g., `${UNDEFINED_VAR}`) will be preserved
- Variables are substituted at load time, so the config file remains safe to commit
### 2. Register Modular MCP
Register Modular MCP in your MCP client configuration (e.g., `.mcp.json` for Claude Code):
```json
{
"mcpServers": {
"modular-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@kimuson/modular-mcp", "modular-mcp.json"],
"env": {}
}
}
}
```
### 3. Two Tools Registration
When Modular MCP starts, it registers only two tools to the LLM:
- `get-modular-tools`: Retrieves tool name and schemas for a specific group
- `call-modular-tool`: Executes a tool from a specific group
The `get-modular-tools` tool description includes information about available groups, like this:
```
modular-mcp manages multiple MCP servers as organized groups, providing only the necessary group's tool descriptions to the LLM on demand instead of overwhelming it with all tool descriptions at once.
Use this tool to retrieve available tools in a specific group, then use call-modular-tool to execute them.
Available groups:
- context7: Use when you need to search library documentation.
- playwright: Use when you need to control or automate web browsers.
```
This description is passed to the LLM as part of the system prompt, allowing it to discover available groups without making any tool calls.
### 4. On-Demand Tool Loading
The LLM can now load and use tools on a per-group basis:
1. **Discovery**: The LLM sees available groups in the tool description (no tool calls needed)
2. **Exploration**: When the LLM needs playwright tools, it calls `get-modular-tools` with `group="playwright"`
3. **Execution**: The LLM uses `call-modular-tool` to execute specific tools like `browser_navigate`
For example, to automate a web browser:
```
get-modular-tools(group="playwright")
→ Returns all playwright tool schemas
call-modular-tool(group="playwright", name="browser_navigate", args={"url": "https://example.com"})
→ Executes the navigation through the playwright MCP server
```
This workflow keeps context usage minimal while providing access to all tools when needed.
## Benefits
- **Reduced Context Usage**: Only loads tool information when actually needed
- **Scalable**: Can manage dozens of MCP servers without overwhelming context
- **Flexible**: Easy to add/remove tool groups without affecting others
- **Transparent**: Tools execute exactly as if called directly on upstream servers
## Migration from Standard MCP Configuration
If you already have a standard MCP configuration file (e.g., `.mcp.json`), you can easily migrate it to Modular MCP format using the built-in migration command.
### Using the Migration Command
Run the migration command with your existing MCP configuration file:
```bash
npx -y @kimuson/modular-mcp migrate
```
For example, if you have a `.mcp.json` file:
```bash
npx -y @kimuson/modular-mcp migrate .mcp.json
```
The migration command will:
1. Generate a `modular-mcp.json` file with the migrated configuration (defaults to `modular-mcp.json` in the current directory, or use `-o` to specify a custom path)
2. Replace the original file's contents with a Modular MCP server configuration that references the generated `modular-mcp.json` file
## OAuth Authentication for Remote MCP Servers
Modular MCP supports OAuth-based authentication for remote MCP servers using both `sse` and `http` transports.
### Using Built-in OAuth Support (Experimental)
Modular MCP includes an experimental OAuth client that implements the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization):
```json
{
"mcpServers": {
"linear-server": {
"description": "Use when you want to check Linear tickets, etc.",
"type": "sse",
"url": "https://mcp.linear.app/sse"
}
}
}
```
On first connection, your browser will open for OAuth authentication. Tokens are stored locally in `~/.modular-mcp/oauth-servers/` and reused automatically.
**Note:** This feature is experimental. If you encounter issues, use the fallback method below.
### Fallback: Using mcp-remote via stdio
For compatibility with all OAuth servers, you can use `mcp-remote` via `stdio` transport:
```json
{
"mcpServers": {
"linear-server": {
"description": "Use when you want to check Linear tickets, etc.",
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
}
}
}
```
This approach delegates OAuth handling to the `mcp-remote` client and is recommended if the experimental OAuth support doesn't work for your server.