Feature Request: Hierarchical Config Merging (User-level + Repo-level)

[ViperJuice]

Problem Statement

Currently, PMCP requires the config file path to be specified via -c flag, and only reads a single config file. This creates configuration duplication when using gateway across multiple repositories.

Current workflow:

• User has personal MCPs (context7, brightdata, playwright) in ~/.pmcp.json
• Each repo needs .mcp.json with gateway configured
• Gateway must be duplicated in every repo's .mcp.json
• If a repo has project-specific MCPs (like code-index), both gateway AND project MCPs must be in the same file

Example - ai-dev-kit/.mcp.json:

{
  "mcpServers": {
    "gateway": {
      "command": "uvx",
      "args": ["pmcp", "-c", "/home/user/.pmcp.json"]
    }
  }
}

Example - Code-Index-MCP/.mcp.json:

{
  "mcpServers": {
    "gateway": {
      "command": "uvx",
      "args": ["pmcp", "-c", "/home/user/.pmcp.json"]
    },
    "code-index-mcp": {
      "command": "python3",
      "args": ["..."]
    }
  }
}

Gateway config is duplicated in every repo.

Proposed Solution

Enable PMCP to merge configurations from multiple layers:

Option 1: Config Search Path

pmcp  # Automatically searches: ./.pmcp.json → ~/.pmcp.json → merge

Option 2: Multiple Config Files

pmcp -c ~/.pmcp.json -c ./.pmcp.json  # Merge both

Option 3: Explicit Extends

// ./.pmcp.json (repo-level)
{
  "extends": "~/.pmcp.json",  // User-level MCPs
  "mcpServers": {              // Project-specific additions
    "code-index": {...}
  }
}

Benefits

1. Eliminate duplication: Gateway configured once in ~/.pmcp.json
2. Layered configuration:
   • User-level: Personal MCPs (context7, brightdata, playwright)
   • Repo-level: Project-specific MCPs (code-index, filesystem)
3. Team collaboration: Repo config is versioned, user config is personal
4. Portable: Works across all AI frameworks that support .mcp.json
5. Consistent with common patterns: Similar to .eslintrc, tsconfig.json, etc.

Ideal Architecture

~/.pmcp.json (user-level)
├─ context7
├─ brightdata
└─ playwright

./.pmcp.json (repo-level)
├─ code-index
└─ filesystem

PMCP merges both → 5 servers available

Then Claude Code's .mcp.json only needs:

{
  "mcpServers": {
    "gateway": {
      "command": "uvx",
      "args": ["pmcp"]  // No explicit -c needed
    }
  }
}

Use Case

Managing 22 repositories where:

• 19 repos use global config (no local .mcp.json)
• 3 repos have project-specific MCPs + need gateway
• Without merging: Must duplicate gateway config in 3 repos
• With merging: Gateway configured once, repos only specify their additions

Implementation Considerations

• Merge strategy: Repo-level overrides user-level for same server name?
• Environment variable expansion: ~ → home directory
• Config file discovery order and precedence
• Backward compatibility: Single -c flag should continue working

Related

This addresses the "configuration duplication" pain point mentioned in PMCP's progressive disclosure goals. Just as PMCP reduces context bloat for tools, hierarchical configs reduce duplication for configuration.