MCPM (Model Context Protocol Manager)

MCPM (Model Context Protocol Manager) is an open-source CLI tool designed to manage MCP servers. It uses a global configuration model where servers are installed once and can be organized into logical groups called profiles (virtual tags). These servers and profiles can then be integrated into various MCP clients.

Key Capabilities:

• Global Server Management: Install once, use everywhere.
• Profiles: Organize servers into different workflows using virtual tags.
• Server Discovery: Browse and install servers from the central MCP Registry.
• Direct Execution: Run servers via stdio or HTTP for testing.
• Client Integration: Manage configurations for clients like Claude Desktop, Cursor, Windsurf, VS Code, Cline, and more.
• Public Sharing: Share servers or profiles via secure tunnels.

The generated llm.txt file follows a standardized structure to ensure AI agents can parse it effectively. It includes the following sections:

• Overview: Tool description and key concepts.
• Environment Variables for AI Agents: Documentation for automation variables like MCPM_NON_INTERACTIVE, MCPM_FORCE, and MCPM_JSON_OUTPUT.
• Command Reference: A recursive list of every command, its parameters, and usage examples.
• Best Practices for AI Agents: Patterns for automation, error handling, and common workflows.
• Troubleshooting: Solutions for common issues.

The registry is organized into a servers/ directory where each server is defined by a JSON file. Each server entry must include configuration details such as its endpoint, capabilities, and version.

Directory Layout:

• mcp-registry/servers/: Contains all registered server metadata files ([server-name].json).
• mcp-registry/schema/server-schema.json: The JSON Schema used to validate server configuration files.

MCPM v2.0 uses FastMCP to aggregate multiple servers into a single endpoint via profiles. This allows a client to access multiple server capabilities through one connection. When servers are aggregated, FastMCP automatically namespaces capabilities to prevent conflicts:

• Tools: {server_name}_t_{tool_name} (e.g., browse_t_getPage)
• Prompts: {server_name}_p_{prompt_name} (e.g., filesystem_p_listFiles)
• Resources: Prefixed by the server name.

# Create a development profile
mcpm profile create web-dev
mcpm profile edit web-dev  # Add: browse, git, filesystem servers

# Run all servers in profile together
mcpm profile run web-dev --http --port 8080

Progress notifications in the MCP protocol rely on a progressToken passed in the _meta.progressToken field of a request.

In a FastMCP HTTP-to-Stdio setup, the following occurs:

1. A client sends an HTTP request to the Proxy.
2. The Proxy forwards the request to a Stdio subprocess.
3. The subprocess runs in an isolated memory space with its own ContextVar state.
4. When the subprocess attempts to report progress, get_context() returns the subprocess context, which lacks the original progressToken from the client's HTTP request.
5. The notification is dropped because the token is missing.

Working Case: HTTP $\rightarrow$ Proxy $\rightarrow$ HTTP (Context is preserved). Failing Case: HTTP $\rightarrow$ Proxy $\rightarrow$ Stdio (Context is isolated).

To modify the mcpm.sh project, use the following directory patterns:

• Website Content: Edit files located in the /pages directory.
• MCP Server Registry: Add or modify server manifests located at /mcp-registry/servers/<server-name>/manifest.json.

Note: If you add a new server to the registry, you must run ./dev.sh again to regenerate the necessary JSON files for the API endpoints.

You can share a single server from your global configuration by creating a secure tunnel that generates a public URL. This allows remote clients to connect to your local server.

Use the mcpm share command with the following options:

• SERVER_NAME: The name of the server to share.
• --port <PORT>: Specify a custom port for the tunnel.
• --subdomain <NAME>: Specify a custom subdomain for the public URL.
• --auth: Enable optional authentication, which generates tokens required for connection.

mcpm share SERVER_NAME
mcpm share SERVER_NAME --port 8080
mcpm share SERVER_NAME --subdomain myserver
mcpm share SERVER_NAME --auth

If you need to bypass the automated script, you can manually start the Jekyll server using Docker. Ensure you have processed the server manifests into JSON files first (as performed by ./dev.sh).

To start the server manually, navigate to the pages directory and run the Jekyll container:

cd pages
docker run --rm -it -v "$PWD:/srv/jekyll" -p 4000:4000 jekyll/jekyll:4.2.0 jekyll serve --livereload

When building command-line interfaces using the Click library, ensure you provide consistent help patterns. Always include both short (-h) and long (--help) options. To display structured examples in the help text, use backslash-escaped blocks (\b) to ensure proper formatting in the terminal.

@click.command()
@click.help_option("-h", "--help")
def my_command():
    """Command description.
    
    Example:
    
    \b
        mcpm command example
    """
    pass

When mapping capabilities (like tools) across multiple servers, avoid direct assignment that might overwrite existing entries. Implement a conflict resolution strategy:

• Strict Mode: If a name collision is detected, raise a ValueError.
• Auto-resolution: If not in strict mode, resolve the conflict by prefixing the name with the server_id and a SEPARATOR.

tool_name = tool.name
if tool_name in self.capabilities_to_server_id["tools"]:
    if self.strict:
        raise ValueError(f"Tool {tool_name} already exists")
    else:
        tool_name = f"{server_id}{SEPARATOR}{tool_name}"
self.tools_mapping[tool_name] = tool
self.capabilities_to_server_id["tools"][tool_name] = server_id